Dispatch Service

API V1 reference

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

Dispatch Service

This service provides an interface to SCORM Dispatch, a tool used to deliver SCORM content from SCORM Cloud to client LMSs in the form of a simple and highly compatible SCORM 1.2 package. The three important entities to keep in mind when using the API are Course, Dispatch Destination, and Dispatch. A course is any host course that has been imported under your AppId. A dispatch destination should map to clients or locations where you\’ll be sending your dispatches. In this way, dispatches can be enabled or disabled (or downloaded) per client / location. Finally, a dispatch represents the intersection of a course and destination, and has the downloadable output of a simple SCORM 1.2 package that can then be launched at the given destination. The dispatch package does not contain the course assets of the target course, it just gives access to the package hosted on SCORM Cloud. A dispatch can be enabled or disabled at any time, even after deployment of the dispatch packages, allowing a system of centralized access for the dispatch creator.



getDestinationList

  • Semantics: Calling this method will return a page of results showing the list of existing dispatch destinations in your account. Callers should assume another page of data is available by calling again with the page parameter incremented, until an empty list is returned.

  • Required Arguments:

    • appid-- Your application id
    • page-- Which page of results to return. Page numbers start at 1.

  • Optional Arguments:

    • tags-- A comma separated list of tags to filter results by. Results must be tagged with every tag in the list

  • Example Call:

    http://cloud.scorm.com/api?method=rustici.dispatch.getDestinationList&appid=myappid&page=1(&tags=test1,test2)

  • Example response:

    <dispatchDestinations page="1">
   <dispatchDestination>
     <id>1eec6b17-326f-4678-a490-b870a0506140</id>
     <name>Noddy</name>
     <tags/>
     <createdBy>Test User</createdBy>
     <createDate>2010-07-29T19:14:39.000+0000</createDate>
     <updateDate>2010-07-29T19:14:39.000+0000</updateDate>
   </dispatchDestination>
   <dispatchDestination>
     <id>6922b1a3-791b-4597-8abb-48de707434a7</id>
     <name>Test Destination</name>
     <tags>
       <tag>test1</tag>
     </tags>
     <createdBy>Test User</createdBy>
     <createDate>2010-08-24T15:28:55.000+0000</createDate>
     <updateDate>2010-08-24T15:28:55.000+0000</updateDate>
   </dispatchDestination>
</dispatchDestinations>



getDestinationInfo

  • Semantics: Calling this method will return information about the dispatch destination named by the given destinationid parameter.

  • Required Arguments:

    • appid-- Your application id
    • destinationid-- The id of the destination being accessed

  • Example Call:

    http://cloud.scorm.com/api?method=rustici.dispatch.getDestinationInfo&appid=myappid&destinationid=1eec6b17-326f-4678-a490-b870a0506140

  • Example response:

    <dispatchDestination>
   <id>1eec6b17-326f-4678-a490-b870a0506140</id>
   <name>Noddy</name>
   <tags/>
   <createdBy>Test User</createdBy>
   <createDate>2010-07-29T19:14:39.000+0000</createDate>
   <updateDate>2010-07-29T19:14:39.000+0000</updateDate>
</dispatchDestination>

  • Error codes:

    • 1-- Destination with given id does not exist
    • 98-- Permission denied to access destination with given id



createDestination

  • Semantics: Calling this method will create a new Dispatch Destination in your SCORM Cloud account, customized with the given parameters, and will return the id for the newly created destination.

  • Required Arguments:

    • appid-- Your application id
    • name-- The name of the new destination

  • Optional Arguments:

    • tags-- A comma separated list of tags to add to this destination
    • email-- The email address associated with the user creating this destination

  • Example Call:

    http://cloud.scorm.com/api?method=rustici.dispatch.createDestination&appid=myappid&name=Test+Destination(&tags=test1,test2&email=test@test.com)

  • Example response:

    <destinationId>6922b1a3-791b-4597-8abb-48de707434a7</destinationId>



updateDestination

  • Semantics: Calling this method will update the Dispatch Destination, identified with the given destinatonid, in your SCORM Cloud account.

  • Required Arguments:

    • appid-- Your application id
    • destinationid-- The id of the destination being updated

  • Optional Arguments:

    • name-- The new name for this destination
    • tags-- A comma separated list of tags to set for this destination

  • Example Call:

    http://cloud.scorm.com/api?method=rustici.dispatch.updateDestination&appid=myappid&destinationid=6922b1a3-791b-4597-8abb-48de707434a7&name=Test+Destination+2(&tags=test1,test3)

  • Example response:

    <success />



deleteDestination

  • Semantics: Calling this method will delete the Dispatch Destination, identified with the given destinatonid, from your SCORM Cloud account.

  • Required Arguments:

    • appid-- Your application id
    • destinationid-- The name of the new destination

  • Optional Arguments:

  • Example Call:

    http://cloud.scorm.com/api?method=rustici.dispatch.deleteDestination&appid=myappid&destinationid=6922b1a3-791b-4597-8abb-48de707434a7

  • Example response:

    <success />



getDispatchList

  • Semantics: Calling this method will return a page of results showing the list of existing dispatches in your account. Callers should assume another page of data is available by calling again with the page parameter incremented, until an empty list is returned.

  • Required Arguments:

    • appid-- Your application id
    • page-- Which page of results to return. Page numbers start at 1.

  • Optional Arguments:

    • destinationid-- Show only dispatches belonging to the destination named by this id
    • courseid-- Show only dispatches for the course named by this id
    • tags-- A comma separated list of tags to filter results by. Results must be tagged with every tag in the list

  • Example Call:

    http://cloud.scorm.com/api?method=rustici.dispatch.getDispatchList&appid=myappid&page=1(&destinationid=6922b1a3-791b-4597-8abb-48de707434a7&courseid=course001&tags=test1,test2)

  • Example response:

    <dispatches page="1">
   <dispatch>
     <id>2737abf6-46f9-479d-a52b-34cd8e8dadae</id>
     <destinationId>1eec6b17-326f-4678-a490-b870a0506140</destinationId>
     <appId>N67DM67K0E</appId>
     <courseAppId>N67DM67K0E</courseAppId>
     <courseId>SequencingForcedSequential_SCORM20043rdEditionb0535515-a4c9-4dad-bd85-04bcc54f96b7</courseId>
     <enabled>true</enabled>
     <tags/>
     <notes></notes>
     <createdBy>Test User</createdBy>
     <createDate>2011-01-26T17:51:31.000+0000</createDate>
     <updateDate>2011-01-26T17:51:31.000+0000</updateDate>
     <registrationcount>2</registrationcount>
     <instanced>true</instanced>
     <registrationcap>0</registrationcap>
   </dispatch>
   <dispatch>
     <id>6ecc95a8-a8a8-40d2-991c-a9e34314f695</id>
     <destinationId>6922b1a3-791b-4597-8abb-48de707434a7</destinationId>
     <appId>N88DM88K0E</appId>
     <courseAppId>N88DM88K0E</courseAppId>
     <courseId>RunTimeAdvancedCalls_SCORM20043rdEdition-1e6b40aa7-0fe8-44a0-95ce-5cdb960c6630</courseId>
     <enabled>true</enabled>
     <tags>
       <tag>newer</tag>
     </tags>
     <notes></notes>
     <createdBy>Test User</createdBy>
     <createDate>2011-02-24T18:00:33.000+0000</createDate>
     <updateDate>2011-02-24T18:00:33.000+0000</updateDate>
     <expirationDate>2011-02-24T18:00:33.000+0000</expirationDate>
     <registrationcount>2</registrationcount>
     <instanced>true</instanced>
     <registrationcap>0</registrationcap>
     <postbackurl>https://example.com/postback</postbackurl>
     <authtype>form</authtype>
     <urlname>testuser</urlname>
     <urlpass>testpass</urlpass>
     <resultsformat>full</resultsformat>
   </dispatch>
</dispatches>

Note

postbackurl, authtype, urlname, urlpass, and resultsformat are only present if postbackurl is set on the dispatch; otherwise they are omitted from the response.

expirationDate is omitted from the response if not set on the dispatch.



getDispatchInfo

  • Semantics: Calling this method will return information about the dispatch named by the given dispatchid parameter.

  • Required Arguments:

    • appid-- Your application id
    • [dispatchid|registrationid] : Exactly one of these parameters must be included (see below)

  • Optional Arguments:

    • dispatchid-- The id of the dispatch being accessed
    • registrationid-- A registration tied to this dispatch (as created by Cloud when the dispatch is launched)

  • Example Call:

    http://cloud.scorm.com/api?method=rustici.dispatch.getDispatchInfo&appid=myappid&dispatchid=6ecc95a8-a8a8-40d2-991c-a9e34314f695

  • Example response:

    <dispatch>
   <id>6ecc95a8-a8a8-40d2-991c-a9e34314f695</id>
   <destinationId>6922b1a3-791b-4597-8abb-48de707434a7</destinationId>
   <appId>N88DM88K0E</appId>
   <courseAppId>N88DM88K0E</courseAppId>
   <courseId>RunTimeAdvancedCalls_SCORM20043rdEdition-1e6b40aa7-0fe8-44a0-95ce-5cdb960c6630</courseId>
   <enabled>true</enabled>
   <tags>
     <tag>newer</tag>
   </tags>
   <notes></notes>
   <createdBy>Test User</createdBy>
   <createDate>2011-02-24T18:00:33.000+0000</createDate>
   <updateDate>2011-02-24T18:00:33.000+0000</updateDate>
   <expirationDate>2011-02-24T18:00:33.000+0000</expirationDate>
   <registrationcount>2</registrationcount>
   <instanced>true</instanced>
   <registrationcap>0</registrationcap>
   <postbackurl>https://example.com/postback</postbackurl>
   <authtype>form</authtype>
   <urlname>testuser</urlname>
   <urlpass>testpass</urlpass>
   <resultsformat>full</resultsformat>
</dispatch>

Note

postbackurl, authtype, urlname, urlpass, and resultsformat are only present if postbackurl is set on the dispatch; otherwise they are omitted from the response.

expirationDate is omitted from the response if not set on the dispatch.

  • Error codes:

    • 1-- Dispatch with given id does not exist
    • 2-- Registration with given id does not exist
    • 3-- Registration exists, but is not tied to a dispatch
    • 4-- Both dispatchid and registrationid were specified (cannot specify both)
    • 98-- Permission denied to access dispatch with given id



createDispatch

  • Semantics: Calling this method will create a new dispatch in your SCORM Cloud account, customized with the given parameters, and will return the id for the newly created dispatch.

  • Required Arguments:

    • appid-- Your application id
    • destinationid-- The id of the destination this dispatch will be associated with
    • courseid-- The id of the course this dispatch will be associated with

  • Optional Arguments:

    • tags-- A comma separated list of tags to add to this dispatch
    • email-- The email address associated with the user creating this dispatch
    • expirationdate-- The date this dispatch will expire and can not be launched (formatted yyyyMMddHHmmss in UTC time)
    • registrationcap-- Integer value of limit to dispatch registrations created
    • postbackurl-- Specifies a URL for which to post activity and status data in real time as the dispatched course is completed
      • If the authtype specified is form, or not included, then this status data is posted as ‘data’ (the key name) along with the other form variables. If the authtype is specified as httpbasic, then the data is HTTP POSTed as the body of the request. The data starts with the <registrationreport ... > element and uses the schema documented in getRegistrationResult
      • For information on testing your postbackurl, see the testRegistrationPostUrl call.
      • To update postback information or specify later, call updateDispatches.
    • authtype-- Optional parameter to specify how to authorize against the given postbackurl, can be “form” or “httpbasic”. If form authentication, the username and password for authentication are submitted as form fields “username” and “password”, and the registration data as the form field “data”. If httpbasic authentication is used, the username and password are placed in the standard Authorization HTTP header, and the registration data is the body of the message (sent as text/xml content type). This field is set to “form” by default.
    • urlname-- You can optionally specify a login name to be used for credentials when posting to the URL specified in postbackurl
    • urlpass-- If credentials for the postbackurl are provided, this must be included, it is the password to be used in authorizing the postback of data to the URL specified by postbackurl
    • resultsformat-- This parameter allows you to specify a level of detail in the information that is posted back while the course is being taken. It may be one of three values: \“course\” (course summary), “activity” (activity summary, or “full” (full detail), and is set to “course” by default. The information will be posted as xml, and the format of that xml is specified below under the method “getRegistrationResult”

  • Example Call:

    http://cloud.scorm.com/api?method=rustici.dispatch.createDispatch&appid=myappid&destinationid=6922b1a3-791b-4597-8abb-48de707434a7&courseid=course001(&tags=test1,test2&email=test@test.com)

  • Example response:

    <dispatchId>6ecc95a8-a8a8-40d2-991c-a9e34314f695</dispatchId>

  • Error codes:

    • 1-- Dispatch destination with given id does not exist
    • 2-- Course with given id does not exist
    • 98-- Permission denied to create dispatch against destination with given id



updateDispatches

  • Semantics: Calling this method will update the selected dispatches in your SCORM Cloud account, using the parameters given. Selection of dispatches to update is based either on a specific dispatch using the dispatchid parameter, or groups of dispatches using the destinationid, courseid, or tags parameters in any combination.

  • Required Arguments:

    • appid-- Your application id
    • [dispatchid|destinationid|courseid|tags] : One of these parameters must be included (see below)

  • Optional Arguments:

    • dispatchid-- The id of the dispatch to update
    • destinationid-- The id of the destination used to select the dispatch group to update
    • courseid-- The id of the course used to select the dispatch group to update
    • tags-- A comma separated list of tags used to select the dispatch group to update. Each dispatch selected will have to be tagged with each tag in the list.
    • enabled-- Setting true or false will enable or disable the selected group of dispatches. Disabled dispatches cannot be launched.
    • open-- Setting true or false will open or close the selected group of dispatches. Closed dispatches cannot have new registrations created for them.
    • instanced-- Setting true or false will enable or disable registration instancing for the selected group of dispatches.
    • addtags-- A comma separated list of tags to add to the selected dispatches
    • removetags-- A comma separated list of tags to remove from the selected dispatches
    • expirationdate-- The date this dispatch group will expire and can not be launched (formatted yyyyMMddHHmmss in UTC time)
    • registrationcap-- Integer value of limit to dispatch registrations created
    • registrationcount-- Integer value of how many dispatch registrations have been created (using this parameter, this count can be manually altered)
    • postbackurl-- Specifies a URL for which to post activity and status data in real time as the dispatched course is completed
      • If the authtype specified is form, or not included, then this status data is posted as ‘data’ (the key name) along with the other form variables. If the authtype is specified as httpbasic, then the data is HTTP POSTed as the body of the request. The data starts with the <registrationreport ... > element and uses the schema documented in getRegistrationResult
      • For information on testing your postbackurl, see the testRegistrationPostUrl call.
    • authtype-- Optional parameter to specify how to authorize against the given postbackurl, can be “form” or “httpbasic”. If form authentication, the username and password for authentication are submitted as form fields “username” and “password”, and the registration data as the form field “data”. If httpbasic authentication is used, the username and password are placed in the standard Authorization HTTP header, and the registration data is the body of the message (sent as text/xml content type). This field is set to “form” by default.
    • urlname-- You can optionally specify a login name to be used for credentials when posting to the URL specified in postbackurl
    • urlpass-- If credentials for the postbackurl are provided, this must be included, it is the password to be used in authorizing the postback of data to the URL specified by postbackurl
    • resultsformat-- This parameter allows you to specify a level of detail in the information that is posted back while the course is being taken. It may be one of three values: “course” (course summary), “activity” (activity summary, or “full” (full detail), and is set to “course” by default. The information will be posted as xml, and the format of that xml is specified below under the method “getRegistrationResult”

  • Example Call:

    http://cloud.scorm.com/api?method=rustici.dispatch.updateDispatches&appid=myappid(&dispatchid=6ecc95a8-a8a8-40d2-991c-a9e34314f695&destinationid=6922b1a3-791b-4597-8abb-48de707434a7&courseid=course001&tags=test1,test2&enabled=false&addtags=deprecated,old&removetags=test1)

  • Example response:

    <success />



downloadDispatches

  • Semantics: Calling this method will use the dispatches selected by the given parameters to create and deliver a package containing the resources used to import and launch those dispatches in client systems. The return of this call is a download stream containing a zip file, which in turn contains zip files for each of the selected dispatches.

  • Required Arguments:

    • appid-- Your application id

  • Optional Arguments:

    • dispatchid-- The id of the dispatch to download
    • destinationid-- The id of the destination used to select the dispatch group to download
    • courseid-- The id of the course used to select the dispatch group to download
    • tags-- A comma separated list of tags used to select the dispatch group to download. Each dispatch selected will have to be tagged with each tag in the list.

  • Example Call:

    http://cloud.scorm.com/api?method=rustici.dispatch.downloadDispatches&appid=myappid(&dispatchid=6ecc95a8-a8a8-40d2-991c-a9e34314f695&destinationid=6922b1a3-791b-4597-8abb-48de707434a7&courseid=course001&tags=test1,test2)

  • Example response: Results in application/octet-stream for zip of zips file



deleteDispatches

  • Semantics: Calling this method will delete the selected dispatches from your SCORM Cloud account, using the parameters given. Selection of dispatches to delete is based either on a specific dispatch using the dispatchid parameter, or groups of dispatches using the destinationid, courseid, or tags parameters in any combination.

  • Required Arguments:

    • appid-- Your application id
    • [dispatchid|destinationid|courseid|tags] : One of these parameters must be included (see below)

  • Optional Arguments:

    • dispatchid-- The id of the dispatch to delete
    • destinationid-- The id of the destination used to select the dispatch group to delete
    • courseid-- The id of the course used to select the dispatch group to delete
    • tags-- A comma separated list of tags used to select the dispatch group to delete. Each dispatch selected will have to be tagged with each tag in the list.

  • Example Call:

    http://cloud.scorm.com/api?method=rustici.dispatch.deleteDispatches&appid=myappid(&dispatchid=6ecc95a8-a8a8-40d2-991c-a9e34314f695&destinationid=6922b1a3-791b-4597-8abb-48de707434a7&courseid=course001&tags=test1,test2)

  • Example response:

    <success />