How to Use the Raw Data API
The Raw Data API allows users to interact with LearningSpace’s data API interface and retrieve XML-formatted responses from specified Activities.
This document is intended for developers and system integrators who want to write applications interacting with LearningSpace's data API interface for the above-mentioned reasons.
Location
http://<your_learningspace_server_address>/w/api/rawdata.cgi
Input Parameters
The first parameter has to be affixed to the rawdata.cgi after a question mark: ?
The value of the parameter has to be preceded by an equals sign: =
Multiple parameters can be defined within a single query by using the ampersand: &
EXAMPLE
http://<your_learningspace_server_address>/w/api/rawdata.cgi?client_secret=w3jPOV1mWjklf3e627Y8Hm2v8Nb2c9UZ&sid=23
Bolded parts are the variables; for instance, client_secret= the API key generated on the Security tab of the System Manager.
append_sid | When used with the sid parameter with value 1, the current sid is displayed in the first node (rawdata_stuff) as <sid></sid>. When used with value 2, the current sid is displayed as an attribute of the root node <rawdata_stuff>. Default: 0. |
exclude_case_info | A value of 1 tells the API not to include the case information (code- book), which results in a faster retrieval of the list of activities. Default: 0. |
page | Page index starting from 0. |
page_size | The number of activities per output XML (defaults to unlimited). If there is too much data to display, the API could time out. To prevent timeout, use this parameter to fine-tune the number of displayed results. This parameter can only be used without the sid parameter. |
client_secret | A valid API key secret that we can generate on the System Module’s Security tab |
sid | Activity* identifier (optional). When the sid parameter is not specified, the API returns all activity, case, and item lists. |
* The API refers to activities as events. They are NOT to be confused with Calendar entry-related events on the user interface.
The first parameter must be passed to the rawdata.cgi after a question mark (?), and the parameter's value must be preceded by an equal sign (=). Multiple parameters can be defined within a single query using the ampersand (&).
Example: http://<your_learningspace_server_address>/w/api/rawdata.cgi?client_secret=”API_KEY”&sid=23
Sample Queries and Outputs
http://<your_learningspace_server_address>/w/api/rawdata.cgi?client_secret=x
<!-- rawdata_export version="2.0" -->
<events>
<event sid="26" title="Clinical Skills Assessment">
<cases>
<case CID="29" name="CSA Abdominal Pain 2018 (RLQ)">
<item phrase="Onset * 48 hours" short_id="RLQHx001">
<answer value="1"/>
<answer value="0"/>
</item>
<item phrase="Progression * no change" short_id="RLQHx002">
<answer value="1"/>
<answer value="0"/>
</item>
</case>
</cases>
</event>
<page_info current_page="0" events_per_page="9223372036854775807" max_page="0" total_event_count="11"/>
</events>
http://<your_learningspace_server_address>/w/api/rawdata.cgi?client_secret=”API_KEY”&sid=23
<!-- rawdata_export version="2.0" -->
<rawdata_stuff>
<learner UCID="87432" UID="4" AdditionalCustomID=”1234” name="Alexander, Timothy">
<case name="CSA Abdominal Pain 2018 (RLQ)">
<resp achieved_points="1" max_achievable="1" section="RLQHx001" value="Yes"/>
<resp achieved_points="1" max_achievable="1" section="RLQHx002" value="Yes"/>
<resp achieved_points="1" max_achievable="1" section="RLQHx003" value="Yes"/>
<resp achieved_points="0" max_achievable="1" section="RLQHx004" value="No"/>
<resp achieved_points="1" max_achievable="1" section="RLQHx005" value="Yes"/>
</case>
</learner>
<learner UCID="77571" UID="5" AdditionalCustomID=”3456” name="Ambrozewicz, Pooja">
<case name="CSA Abdominal Pain 2018 (RLQ)">
<resp achieved_points="1" max_achievable="1" section="RLQHx001" value="Yes"/>
<resp achieved_points="1" max_achievable="1" section="RLQHx002" value="Yes"/>
<resp achieved_points="1" max_achievable="1" section="RLQHx003" value="Yes"/>
<resp achieved_points="1" max_achievable="1" section="RLQHx004" value="Yes"/>
<resp achieved_points="1" max_achievable="1" section="RLQHx005" value="Yes"/>
</case>
</learner>
</rawdata_stuff>
NOTE: If there is no value set for the Additional Custom ID field for a user, it is left empty like this:
AdditionalCustomID=""
XML Output Structure
When rawdata.cgi is invoked without the sid parameter:
Node | Attribute | Description |
<events> | N/A | First node encapsulating the other nodes below. |
<event> | sid | Unique numerical identifier of the Activity. |
| title | Title of the activity - as entered on the Edit Activity page on the user interface. |
<cases> | N/A | The child node of <event> encapsulating all the cases assigned to the activity. |
<case> | CID | Unique numerical identifier of the case. |
| name | Name of the case - as entered on the Edit Case page on the user interface. Presenting complaint, if entered, is displayed in parentheses. |
<item> | phrase | A question within a section as seen on a checklist on the user interface. |
| short_id | The section’s short identifier and number in which the question is used. Section abbreviation as seen on the user interface and the question’s number. Also includes the case Presenting complaint, if applicable. |
<answer> | value, value_max, value_min | The possible numerical values of the possible answers to the question. Max/min values are applicable when the direct scoring method is used. |
<page_info> | current_page | Displays the current XML output page number if the page parameter is used. |
| events_per_page | Indicates how many activities are displayed on a single page of the XML output. It is defined by the page_size parameter. |
| max_page | Displays how many pages are available. Depends on the page_size parameter and the number of activities available (total_event_count). |
total_event_count | The number of activities available. |
Example: http://<your_learningspace_server_address>/w/api/rawdata.cgi?client_secret=”API_KEY”
When rawdata.cgi is invoked with the sid parameter:
Node | Attribute | Description |
<rawdata_stuff> | N/A | First node encapsulating the other nodes below. |
<learner> | UCID | The learner's UCID, if added, as entered in the Edit User pop-up on the user interface.** |
| UID | Unique numerical identifier of the learner. |
Additional Custom ID | An additional unique numerical identifier of the learner. | |
| name | The learner's name in first, last, and middle name format as entered in the Edit User pop-up on the user interface.** |
<case> | CID | Unique numerical identifier of the case. |
| name | Name of the Case. Case name on the Edit Case page as seen on the user interface. Presenting complaint is displayed in parenthesis, if available. |
<resp> | achieved_points | The score the learner was given for a specific question. |
| max_achievable | The maximum score the learner could receive for the specific question. |
| section | The section’s short identifier and number in which the question is used. Section abbreviation as seen on the user interface and the question’s number. Also includes the case Presenting complaint, if applicable. See <item> short_id. |
value | The textual representation of the selected response. | |
virtual_section_tag | List of the virtual sections to which this item belongs (the section names are separated by ';' ) | |
<sid> | N/A | The sid parameter used for the current query. |
Example: http://<your_learningspace_server_address>/w/api/rawdata.cgi?client_secret=”API_KEY”&sid=23
Error Codes
'--No_rawdata_found': no responses found for the activity
'--No_case_for_event' : no case assigned to the activity
'--Request_error' : internal error
'--Authentication_failed' : user has no access to the current activity
'--Event_notfound' : no activity has been found
'--Invalid_event_range_specified_for_total_event_count_[total event count] ' : the specified page does not exist or is invalid
Related pages: