How do I export grades from Desire2Learn?

How would an app developer at a school (using Java) export grades from the D2L Instance?

If I am building a D2L Valence App that needs to use a utility account (like the approach described: https://stackoverflow.com/a/9950523/680651) to export a bunch of grades:

How do I do the one time config of appid and app key?

How do I do the one time config of the user id and user key?

What REST calls do I need to actually get class lists and export the grades?

Solution

Regarding Utility account:

I would consider trying to use the instructor context so you don't have to enforce roles. But if you do go with a utility account:

Regarding One time config of AppID and AppKey:

Request a key from keytool following the keytool walkthrough
Follow up will occur from that tool back through Desire2Learn and to approved contact at your institution to make sure the key is supposed to be enabled.
When enabled you can compile these keys directly into your java code or a resource file (or a db). They are used in the java libraries in a couple places and allow you to turn on or off individual apps from within Desire2Learn Manage Extensibility Tool.

Regarding one time config of utility account userid and userkey:

Its probably easiest to turn the Getting Started Sample into an installer:

The auth library used in the the sample can be used to just authenticate to your own instance (rather than prompt for a host name). This will produce an authentication url like "https://my.host.name/d2l/auth/api/token?x_a=......" which should be set as the step to "pick a utility account to run this application".
Adjust the java sample in index.jsp and change the lines that save the userid and userkey to the session:

session.setAttribute("userID", userContext.getUserId());

session.setAttribute("userKey", userContext.getUserKey());

and instead save it to a database.
When configuring your app, run this and login to D2L with the utility account you want to use. When the login is complete the index.jsp code will be run and save the keys.
These keys are used in the java libraries and prove to the LMS what user context the calls are made in.

Regarding getting a course list and grades for courses:

For all the calls I would use the library operation called ID2LUserContext createAuthenticatedUri passing in the path noted in the docs.
Get org units (includes courses) for an instructor with the org unit by user call

Sample Request for this call:

GET
https://valence.desire2learn.com/d2l/api/lp/1.0/enrollments/users/3667/orgUnits/?x_b=JgqB2bumFwQkWft-gUP8Qr&x_a=L2Hd9WvDTcyiyu5n2AEgpg&x_d=XeTMX5fliLPTJdtKqeE_a0esDmTriSC9Aq9sMtpoO00&x_c=2AhFhrwhv1RsIdshAMba0upiux7Bhz-znS-VqjXhQh8&x_t=1333565539
HTTP/1.1 Accept-Encoding: gzip,deflate User-Agent: Jakarta
Commons-HttpClient/3.1 Host: valence.desire2learn.com

(The values x_a, x_b, x_c, x_d and x_t are used for authentication and are automatically added if you use a client library)

3.This call will ultimately contain OrgUnitInfo structures

And here is the raw response:

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store
Pragma: no-cache
Content-Length: 17300
Content-Type: application/json; charset=UTF-8
Expires: -1
Server: Microsoft-IIS/6.0
X-Powered-By: ASP.NET
X-AspNet-Version: 2.0.50727
Date: Wed, 04 Apr 2012 18:52:08 GMT

{"PagingInfo":{"Bookmark":"6789","HasMoreItems":true},"Items":[

<SNIP/>

{
         "OrgUnit":          {
            "Id": 6789,
            "Type":             {
               "Id": 3,
               "Code": "Course Offering",
               "Name": "Course Offering"
            },
            "Name": "In",
            "Code": "dSCL_101_ONGOING_01"
         },
         "Role":          {
            "Id": 71,
            "Code": null,
            "Name": "Instructor Role"
         }
      }    

<SNIP/>

4.The IDs from that OrgUnitInfo structures can be used to retrieve grades via the grades for a course action

For a background on how to turn the doc resources into a working call you will want to review the documentation conventions.