Course Service

API V1 reference

This page applies to SCORM Cloud API V1. You can check out the API V2 reference here.

Course Service

This secured service allows for many operations related to courses, including importing new courses and retrieving information about imported courses.



importCourseAsync

  • Semantics: The semantics of this method are similar to the importCourse method. The difference is that this call is asynchronous and returns immediately, instead of waiting for the import process to complete. Instead of returning the results of a completed import, it returns an import result token, which should be used in subsequent calls to getAsyncImportResult to actually get the import results (or import errors). If the redirectUrl parameter is used, the browser will be redirected after the file has been posted, and this URL will have the following parameters appended to the querystring: a “success” parameter noting success/failure, and if successful, it will also include courseid, appid, and tokenid parameters. If the call fails, the “errcode” and “msg” paramters will be included which specify the error that occurred.

    Note: the import result token is valid for one week after the course import finishes – whether it succeeds or fails.

  • Required Arguments:

    • appid– Your application id
    • courseid– The id used to identify this course

  • Optional Arguments:

    • redirecturl– The url that a browser should be redirected to after the operation completes.
    • email– An email address associated with an existing SCORM Cloud website user. If this parameter is included, user information will be attached to this event in the event history on the SCORM Cloud website.
    • culture– This parameter should specify a culture code (see the complete listing at Language Support). If specified, and supported, the parser warnings found during import will be returned in the appropriate specified language.
    • itemid– The item identifier of a specific learning object to import. This allows for the import of an aggregation or a specific SCO/asset within an organization.

  • Example call: An example call is best illustrated with a simple http form:

    <form id="importCourseForm" method="post"
     action=" http://cloud.scorm.com/api?method=rustici.course.importCourseAsync&appid=myappid&courseid=course003(&email=user@test.com)"
     enctype="multipart/form-data">
         <input type="file" name="filedata" size="40" /> <br />
         <input type="submit" value="Send" />
</form>

  • Example response (if not redirected using the redirecturl param):

    <token>
   <id>e2bfa26e-2e96-48e3-86a6-f435fba6dccb</id>
</token>



getAsyncImportResult

  • Semantics: This call is the other necessary half of asynchronous importing. An import is started asynchronously using importCourseAsync. The results of the import started can be retrieved using getAsyncImportResult. The result of this call returns a status, and additional information based on that status. If an error or other exception has occurred during the import, the status will be set to “error” and details of the error will be added to the output. If the status is “finished”, the import results will be included. See example call/response below.

    Note: the import result token is valid for one week after the course import finishes – whether it succeeds or fails.

  • Required Arguments:

    • appid– Your application id
    • token– The id of the token returned by importCourseAsync.

  • Example Call:

    http://cloud.scorm.com/api?method=rustici.course.getAsyncImportResult&appid=myappid&token=e2bfa26e-2e96-48e3-86a6-f435fba6dccb

  • Example response:

    //Job created, but not yet started
<status>created</status>

//When still running
<status>running</status>

//When error has occurred
<status>error</status>
<error>[Error message here]</error>

//When completed without error
<status>finished</status>
<importresults>
 <importresult successful="true">
 <title>Photoshop Example -- Competency</title>
 <message>Import Successful</message>
 [possibly <parserwarnings>
             <warning>[warning text]</warning>
           </parserwarnings>  ]
 </importresult>
</importresults>



preview

  • Semantics: Calling this method will preview the course by redirecting the user’s browser. This method is intended to be called directly in a browser.
  • Required Arguments:
    • appid– Your application id
    • courseid– The id used to identify this course absent, use the most recent version.
  • Optional Arguments:
    • versionid– The version of the package which will be used. If
    • redirecturl– The URL to redirect the user to when the preview is exited. By default, this redirects to scorm.com. For convenience, this parameter can alternatively be any of the following keywords: “closer”, “blank”, “message” which will redirect to a page that automatically tries to close the browser tab/window, a blank page, or a page with a simple message about the course being complete, respectively. If not one of the special arguments above, the redirecturl must be a full URL (scheme, host, and all) or an absolute path — relative paths will be rejected.
  • Example response:
    • The user’s browser will be redirected to the preview page
  • Error codes:
    • 1– The course specified by the given courseid can not be found



properties

  • Semantics: Calling this method will allow the user access to the properties editor for this course, by redirecting the user’s browser. This method is intended to be called directly in a browser, although it’s recommended and typical for it to be embedded on a page using an iframe.
  • Required Arguments:
    • appid– Your application id
    • courseid– The id used to identify this course
  • Optional Arguments:
    • cssurl– A URL to an external stylesheet to be applied to the properties editor
    • culture– This parameter should specify a culture code (see the listing at Language Support). If specified, and supported, the properties control will be displayed in that language.
    • editor– This should be set to “latest” in order to access the latest version of the properties control
  • Example response:
    • The user’s browser will be redirected to the properties editor page



exists

  • Semantics: This method is used to check a whether or not the specified course exists.

  • Required Arguments:

    • appid– Your application id
    • courseid– The id used to identify this course

  • Example response:

    <result>true</result>



getAssets

  • Semantics: This method provides a simple mechanism to download files for a given course. If no error occurs during processing of the call, this method will not return any XML response, but rather an application/octet-stream response containing the data of the requested course assets. This call provides a way to quickly retrieve important files like the imsmanifest.xml or metadata files, or many files at once, returned in the form of a zip file. If the optional path parameter is not specified, all the assets for the course will be returned in the zip file.

  • Required Arguments:

    • appid– Your application id
    • courseid– The id used to identify the course under which the assets should be found.

  • Optional Arguments:

    • path– The (relative) file path to a specific asset. The path is relative to the course root. If this parameter has only a single value, just the one file will be returned. If this parameter has multiple values, each of the assets specified will be packaged together into a zip file. If this parameter is not specified, all the assets for the course will be returned in the zip file. The structure of the zip file will have the courseid as the root, and each file will be at the relative path specified underneath that root. (If no path specified, the structure will exactly resemble the structure returned in the call to getFileStructure.)

  • Example Call:

    http://cloud.scorm.com/api?method=rustici.course.getAssets&appid=myappid&courseid=course003(&path=images/birdfeeder.jpg&path=images/birdfeederscaled.jpg)

  • Example response:

    • Success will result in a file download, while an error will return error details in the common format



updateAssets

  • Semantics: This method can be used to update the assets of the course specified. Files found in the zip file, which is sent through the request or specified by the optional path parameter, will be overlayed on top of the files belonging to the course specifed by courseid . Note however that the existing manifest file will not be overwritten.

  • Required Arguments:

    • appid– Your application id
    • courseid– The id used to identify the course for deletion

  • Example Call:

    http://cloud.scorm.com/api?method=rustici.course.updateAssets&appid=myappid&courseid=course003(&path=default/Course003.zip)

(or HTTP multipart post data if no path specified))

  • Example response:

    <success />

  • Error codes:

    • 1– The course specified by the given courseid cannot be found
    • 2– The file specified in the optional path parameter can’t be found
    • 3– Internal processing of the assets file caused an IO exception



deleteCourse

  • Semantics: A call to this method will cause the course specified by the courseid parameter (belonging to the client named by appid) to be deleted.

  • Required Arguments:

    • appid– Your application id
    • courseid– The id used to identify the course for deletion

  • Optional Arguments:

    • email– An email address associated with an existing SCORM Cloud website user. If this parameter is included, user information will be attached to this event in the event history on the SCORM Cloud website.

  • Example Call:

    http://cloud.scorm.com/api?method-rustici.course.deleteCourse&appid=myappid&courseid=course003(&email=user@test.com)

  • Example response:

    <success />

  • Error codes:

    • 1– The course specified by the given courseid cannot be found
    • 2– Deleting the files associated with this course caused an internal security exception



getFileStructure

  • Semantics: This method returns xml that represents the file structure of the course files belonging to the course named by the courseid parameter, along with some very basic metadata about the files, such as file length and last modified date. All dates shown are of the format yyyyMMddHHmmss and in the UTC timezone.

  • Required Arguments:

    • appid– Your application id
    • courseid– The id used to identify the course

  • Example Call:

    http://cloud.scorm.com/api?method=rustici.course.getFileStructure&appid=myappid&courseid=course003

  • Example response:

    <dir name="photoshop_competency">
   <file name="adlcp_v1p3.xsd" size="2846" modified="20090108210616"/>
   <file name="adlnav_v1p3.xsd" size="2109" modified="20090108210616"/>
   <file name="adlseq_v1p3.xsd" size="2649" modified="20090108210616"/>
   <file name="datatypes.dtd" size="6357" modified="20090108210616"/>
   <file name="Exam.htm" size="20073" modified="20090108210616"/>
   <dir name="images">
     <file name="37.gif" size="70" modified="20090108210616"/>
     <file name="72.gif" size="169" modified="20090108210616"/>
     <file name="Addition.gif" size="136" modified="20090108210616"/>
     [...]
     <file name="ZoomToolIcon.gif" size="142" modified="20090108210616"/>
   </dir>
   [...]
   <file name="XMLSchema.dtd" size="16018" modified="20090108210616"/>
</dir>

  • Error Codes:

    • 1– Could not find the given course specified by courseid belonging to the given appid



deleteFiles

  • Semantics: A call to this method will attempt to delete each file specified by the relative path named in the path parameter. The path specified is relative to the root of the course files belonging to the course named by the courseid parameter. The method returns a list of results for each path, and whether the deletion was successful.

  • Required Arguments:

    • appid– Your application id
    • courseid– The id used to identify the course whose files are named for deletion
    • path– The relative path (relative to the course file root) to the file(s) to be deleted. Note that this parameter can have multiple values, in which case, each file specified will be deleted (or attempted, that is).

  • Example Call:

    http://cloud.scorm.com/api?method=rustici.course.deleteFiles&appid=myappid&courseid=course003&path=image1.jpg(&path=image2.jpg&path=image3.jpg)
    • Note that it could be fairly easy to exceed the maximum length of a query string based GET request with a long list of files, and hence the POST action should be used in those cases

  • Example response:

    <results>
   <result path="images/birdfeeder.jpg" deleted="true"/>
   <result path="images/doesnotexist.jpg" deleted="false"/>
</results>

  • Error Codes:

    • 1– Course named by courseid not found
    • Any errors in deleting the named files will just report a deleted=“false” for that file.



getAttributes

  • Semantics: Calling this method will return the names and values of the editable attributes for the course named by the courseid parameter. These attributes can be updated with a call to updateAttributes, as detailed elsewhere in this doc.

  • Required Arguments:

    • appid– Your application id
    • courseid– The id used to identify the course for which the attributes will be retrieved

  • Optional Arguments:

    • versionid– The course version to use. A list of course versions can be retrieved using getCourseDetail. Omit this parameter, leave it empty, or set it to -1 to affect all course versions. The attributes registrationInstancingOption, title, and scormVersion are not version-specific, so this call will return the same value for those attributes regardless of the versionid specified.

  • Example Call:

    http://cloud.scorm.com/api?method=rustici.course.getAttributes&appid=myappid&courseid=course003

  • Example response:

    <attributes>
   <attribute name="alwaysFlowToFirstSco" value="false"/>
   <attribute name="commCommitFrequency" value="10000"/>
   <attribute name="commMaxFailedSubmissions" value="2"/>
   [...]
   <attribute name="validateInteractionResponses" value="true"/>
   <attribute name="wrapScoWindowWithApi" value="false"/>
</attributes>

  • Error Codes:

    • 1– Course named by courseid not found



updateAttributes

  • Semantics: This method allows you to update the attributes belonging to the course named by courseid. The attribute names and values are specified as name/value parameters in the HTTP request, see example usage below. Any faulty values given will be ignored. An error free call to this method will return a list of attributes that have been changed along with their new values. (If an attribute is set to it’s existing value, it will not appear in the returned list. Only changed values will appear.) Documentation for the available attributes and their corresponding values can be found here.

  • Required Arguments:

    • appid– Your application id
    • courseid– The id used to identify the course for which the attributes will be updated

  • Optional Arguments:

    • versionid– The course version to use. A list of course versions can be retrieved using getCourseDetail. Omit this parameter, leave it empty, or set it to -1 to affect all course versions. The attributes registrationInstancingOption, title, and scormVersion are not version-specific, so calling this method with any of those attributes will update them across all versions regardless of the versionid set. (Other attributes in the same API call will be version-restricted, however, if a versionid is provided.)

  • Example Call:

    http://cloud.scorm.com/api?method=rustici.course.updateAttributes&appid=myappid&courseid=course003&showNavBar=true&showCourseStructure=false(and so on)

  • Example response:

    <attributes>
   <attribute name="showCourseStructure" value="false"/>
   <attribute name="showNavBar" value="true"/>
</attributes>

  • Error codes:

    • 1– Course named by courseid not found



getMetadata

  • Semantics: A call to this method will return important metadata items associated with the specified course. Optional parameters can be included to specify both the scope of the metadata that is returned (course level only or activity level), as well as the format of the metadata (summary or detailed).

  • Required Arguments:

    • appid– Your application id
    • courseid– The id used to identify the course for which the attributes will be updated

  • Optional Arguments:

    • scope– The scope of the return metadata. If specified as “course” return only data about the root learning object. If specified as “activity”, return data for every activity / learning object in the course.
    • mdformat– If specified as summary, return only the most important subset of metadata such as title, description, duration, typical time, key words, and mastery score for each learning object. If specified as “detail”, return a much larger set of data.

  • Example Call:

    http://cloud.scorm.com/api?method=rustici.course.getMetadata&appid=myappid&courseid=course003(&scope=activity&mdformat=detail)

  • Example response:

    • If mdformat is “course” or “activity”: (*Note only learning objects with metadata will contain a metadata element)

      <package>
<metadata>
 <title>Package Title</title>
 <description>Package Description</description>
 <duration>Package Duration</duration>
 <typicaltime>0</typicaltime>
 <keywords>
   <keyword>Training</keyword>
 </keywords>
</metadata>
<object id="B0">
 <metadata>
   <title>Root Title</title>
   <description>Root Description</description>
   <duration>0</duration>
   <typicaltime>0</typicaltime>
   <keywords>
     <keyword>Training</keyword>
   </keywords>
 <metadata>
   [* if mdformat is "activity"
   <children>
     <object id="i1">
       <metadata>
         <title>Title</title>
         <description>Description</description>
         <duration>0</duration>
         <typicaltime>0</typicaltime>
         <keywords>
           <keyword>Training</keyword>
         </keywords>
         <masteryscore/>
       </metadata>
     </object>
   </children>]
</object>
</package>

  • Error codes:

    • 1– Course named by courseid not found



getManifest

  • Semantics: This method provides a simple mechanism to download the manifest for a given course. If no error occurs during processing of the call, this method will not return any XML response, but rather an application/octet-stream response containing the data of the requested manifest.

  • The manifest returned depends on the learning standard:

    • SCORM (1.2 or 2004): imsmanifest.xml
    • Tin Can/xAPI: tincan.xml
    • AICC: the relevant .crs file
    • cmi5: cmi5.xml

  • Required Arguments:

    • appid– Your application id
    • courseid– The id used to identify the course under which the assets should be found.

  • Example Call:

    http://cloud.scorm.com/api?method=rustici.course.getManifest&appid=myappid&courseid=course003

  • Example response:

    • Success will result in a file download, while an error will return error details in the common format

  • Error Codes:

    • 1– Could not find the given course specified by courseid belonging to the given appid



getCourseList

  • Semantics: This method will return a list of courses associated with the given appid. If the optional filter parameter is specified, it will be used as a substring filter against the course id to narrow the returned list of courses.

  • Required Arguments:

    • appid– Your application id

  • Optional Arguments:

    • filter– A string that will be used to filter the list of courses. Specifically only those courses whose courseid’s match the filter, or contain the filter as a substring, will be returned in the list.
    • tags– A comma separated list of tags to filter results by. Results will include only courses which are tagged with every tag in the list

  • Example Call:

    http://cloud.scorm.com/api?method=rustici.course.getCourseList&appid=myappid(&filter=idSubstring&tags=test1,test2)

  • Example response:

    <courselist>
   <course id="test321" title="Photoshop Example -- Competency" versions="-1" registrations="2" >
       <tags>
       <tag>test1</tag>
       <tag>test2</tag>
       <tags>
   </course>
   <course id="course321" title="Another Test Course" versions="-1" registrations="5" >
       <tags></tags>
   </course>
</courselist>



getCourseDetail

  • Semantics: This method will return a number of details surrounding the course specified by the given appid and courseid parameters. It is typically most helpful in discovering version information about the given course. To read more about content versioning, please see Course Versioning and Overwriting.

  • Required Arguments:

    • appid– Your application id
    • courseid– The course id for the given course

  • Example Call:

    http://cloud.scorm.com/api?method=rustici.course.getCourseDetail&appid=myappid&courseid=course123

  • Example response:

    <course id="course123" title="Golf Explained - Sequencing Versions" versions="3" registrations="16" size="2040257" >
  <versions>
    <version>
      <versionId><![CDATA[0]]></versionId>
      <updateDate><![CDATA[2011-07-22T17:39:06.000+0000]]></updateDate>
    </version>
    <version>
      <versionId><![CDATA[1]]></versionId>
      <updateDate><![CDATA[2011-07-25T16:19:59.000+0000]]></updateDate>
    </version>
    <version>
      <versionId><![CDATA[2]]></versionId>
      <updateDate><![CDATA[2011-07-25T20:15:37.000+0000]]></updateDate>
    </version>
  </versions>
  <tags></tags>
</course>

  • Tin Can Course Example response:

    <course id="course123" title="Golf Explained - Sequencing Versions" versions="3" registrations="16" size="2040257" >
  <versions>
    <version>
      <versionId><![CDATA[0]]></versionId>
      <updateDate><![CDATA[2011-07-22T17:39:06.000+0000]]></updateDate>
    </version>
  </versions>
  <tags></tags>
  <learningStandard><![CDATA[Tin Can]]></learningStandard>
  <tinCanActivityId><![CDATA[scorm.com/GolfExample_TCAPI]]></tinCanActivityId>
</course>



importCourse

Caution

This method is synchronous: it waits until the course import completes before returning. Our CDN/caching layer will automatically fail requests that take longer than 60 seconds, so this method is not reliable for large course imports. We recommend using importCourseAsync instead.


  • Semantics: This method expects the incoming HTTP request to be a POST of multipart (i.e. HTTP form w/ input of type file) data. Every other parameter (other than the file data) must be specified on the querystring. When this method is called, the service will try to import the posted course file. If the import is successful, the imported course will be registered using the courseid provided. If the given courseid refers to an existing course, a new version of the course will be created (for more information, see Course Versioning and Overwriting). If the optional redirecturl parameter is specified, the browser sending the request will be redirected to the given url, appending the following querystring parameters: a “success” parameter noting success/failure, and if successful, a “title” parameter that specifies the title of the imported course. If the call failed, the url will be appended with an “errcode” parameter specifying the error code, and a “msg” parameter specifying the error message. This allows developers to direct the user automatically to another page when a form is submitted in a browser.

  • Required Arguments:

    • appid– Your application id
    • courseid– The id used to identify this course

  • Optional Arguments:

    • redirecturl– The url that a browser should be redirected to after the operation completes.
    • email– An email address associated with an existing SCORM Cloud website user. If this parameter is included, user information will be attached to this event in the event history on the SCORM Cloud website.
    • culture– This parameter should specify a culture code (see the listing at Language Support). If specified, and supported, the parser warnings found during import will be returned in the appropriate specified language.
    • itemid– The item identifier of a specific learning object to import. This allows for the import of an aggregation or a specific SCO/asset within an organization.

  • Example call: An example call is best illustrated with a simple http form:

    <form id="importCourseForm" method="post"
     action=" http://cloud.scorm.com/api?method=rustici.course.importCourse&appid=myappid&courseid=course003(&email=user@test.com)"
     enctype="multipart/form-data">
         <input type="file" name="filedata" size="40" /> <br />
         <input type="submit" value="Send" />
</form>

  • Example response (if not redirected using redirectUrl):

    <importresult successful="true">
    <title>Photoshop Example -- Competency</title>
    <message>Import Successful</message>
    [possibly <parserwarnings>
                  <warning>[warning text]</warning>
              </parserwarnings>  ]
</importresult>

  • Error codes:

    • 2– The file specified in the optional path parameter can’t be found
    • Also remember to check the successful flag on the importresult element, as even a “successful” web service call to importCourse can result in a failed import (for example, if the zip file being imported does not contain an imsmanfiest.xml file)