Invitation Service

API V1 reference

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

Invitation Service

This service provides calls to create and enable/disable SCORM Cloud invitations as well as for retrieving information about invitations.



createInvitation

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

  • Required Arguments:

    • appid-- Your application id
    • courseid-- The course to which this invitation is being created
    • public-- A boolean (true or false only) parameter specifying whether the invitation is public or private. A true value creates a public invitation and false a private invitation. Public invitations will not be sent to recipients even if addresses are provided. A public invitation will have a URL associated with it which can be provided to learners. The destination of that public URL is a page that requires learners to enter a name and email in order for a registration to be created and the training launched. Private invitations do not have public launch URLs, but instead creates a launch URL for a specific registration for each email specified in the “addresses” field. Registrations are created at invitation creation time for each email specified.

  • Optional Arguments:

    • emailSubject-- The subject of the email that will be sent to any addresses provided (for private invitations). Below is a list of tags that can be added to the emailSubject field or emailBody field to be replaced by the course or user specific information when sent.
      • [COURSE] - the course name
      • [COURSE_DESCRIPTION] - the course description
      • [COURSE_DURATION] - the course duration
      • [USER] - the recipients name
      • [URL] - the course launch URL
      • [URL:name] - a link to the launch URL with text ‘name’
    • emailBody-- The test that will be sent in the body of emails sent to any addresses provided (for private invitations). In addition to the ‘tags’ listed above, the emailBody also accepts html tags.
    • addresses-- A comma separated list of email addresses for which registrations will be created for private invitations.
    • send-- A boolean (true or false only, default false) parameter specifying whether the private invitations will be emailed to the provided addresses or not.
    • creatingUserEmail-- The email of the user who is creating the invitation. This value is required in order to send private invitations.
    • registrationCap-- Integer value of limit of public invitation registrations to allow
    • 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”
    • expirationdate-- The date this invitation will expire and can not be launched (formatted yyyyMMddHHmmss in UTC time)

  • Example Call:

    http://cloud.scorm.com/api?method=rustici.invitation.createInvitation&appid=myappid&courseid=mycourseid&public=true&creatingUserEmail=myname@mydomain.com

  • Example response:

    937296cb-ae79-4190-bb6f-9a39b97785ac



createInvitationAsync

  • Semantics: This method has the same behavior as the createInvitation service method, but when choosing to send private invitations, the individual learner registration creation and invitation email sending occurs asynchronously. The method will still return the invitation Id, but the job of creating the registrations and sending the invitation email may not yet be complete. To check the status of your createInvitationAsync job, use the getInvitationStatus method with the invitation Id value returned from this method.

  • Required Arguments:

    • appid-- Your application id
    • courseid-- The course to which this invitation is being created
    • public-- A boolean (true or false only) parameter specifying whether the invitation is public or private. A true value creates a public invitation and false a private invitation. Public invitations will not be sent to recipients even if addresses are provided. A public invitation will have a URL associated with it which can be provided to learners. The destination of that public URL is a page that requires learners to enter a name and email in order for a registration to be created and the training launched. Private invitations do not have public launch URLs, but instead creates a launch URL for a specific registration for each email specified in the “addresses” field. Registrations are created at invitation creation time for each email specified.

  • Optional Arguments:

    • emailSubject-- The subject of the email that will be sent to any addresses provided (for private invitations). Below is a list of tags that can be added to the emailSubject field or emailBody field to be replaced by the course or user specific information when sent.
      • [COURSE] - the course name
      • [COURSE_DESCRIPTION] - the course description
      • [COURSE_DURATION] - the course duration
      • [USER] - the recipients name
      • [URL] - the course launch URL
      • [URL:name] - a link to the launch URL with text ‘name’
    • emailBody-- The test that will be sent in the body of emails sent to any addresses provided (for private invitations). In addition to the ‘tags’ listed above, the emailBody also accepts html tags.
    • addresses-- A comma separated list of email addresses for which registrations will be created for private invitations.
    • send-- A boolean (true or false only) parameter specifying whether the private invitations will be emailed to the provided addresses or not.
    • creatingUserEmail-- The email of the user who is creating the invitation. This value is required in order to send private invitations.
    • registrationCap-- Integer value of limit of public invitation registrations to allow 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”
    • expirationdate-- The date this invitation will expire and can not be launched (formatted yyyyMMddHHmmss in UTC time)

  • Example Call:

    http://cloud.scorm.com/api?method=rustici.invitation.createInvitationAsync&appid=myappid&courseid=mycourseid&public=false&creatingUserEmail=myname@mydomain.com&addresses=,name1@mydomain.com

  • Example response:

    937296cb-ae79-4190-bb6f-9a39b97785ac



getInvitationStatus

  • Semantics: This method returns the status of the create registration and send email job associated with the creation of an invitation. This method is most relevant to invitations created using the createInvitationAsync method.

  • Required Arguments:

    • appid-- Your application id
    • invitationId-- The id of the invitation to check the job status of

  • Optional Arguments: none

  • Example Call:

    http://cloud.scorm.com/api?method=rustici.invitation.getInvitationStatus&appid=myappid&invitationId=937296cb-ae79-4190-bb6f-9a39b97785ac

  • Example response:

    <status>complete</status>

  • Response Glossary:

    • started-- Job has been started and is in progress
    • canceled-- Job has been canceled
    • complete-- Job is complete
    • error-- Job threw exception(s) - error elements will also be returned with the response
    • notfound-- Job was not found. This will be returned for public invitations which do not have any jobs beyond creating the invitation.



getInvitationInfo

  • Semantics: This method returns the details of the invitation specified by the sent invitationId.

  • Required Arguments:

    • appid-- Your application id
    • invitationId-- The id of the invitation to check the job status of

  • Optional Arguments:

    • detail-- A boolean (true or false only) parameter specifying whether to return registration summary info for any user invitations that are returned for the invitation.

  • Example Call:

    http://cloud.scorm.com/api?method=rustici.invitation.getInvitationInfo&appid=myappid&invitationId=937296cb-ae79-4190-bb6f-9a39b97785ac&detail=true

  • Example response:

    <invitationInfo>
   <id><![CDATA[35568984-16cf-4d81-92dd-ea69eb4dacd4]]></id>
   <body><![CDATA[Dear [USER],<p>You have been invited to take 'Feedback 1.2 invite app'. To start your training click on the Play button or copy the training URL into your browser.</p><a href='[URL]'>Play course</a><br><br>URL: [URL]]]></body>
   <courseId><![CDATA[Feedback1.2inviteapp00ec1901-a17c-4165-9294-fdb105707541]]></courseId>
   <subject><![CDATA[Feedback 1.2 invite app]]></subject>
   <url/>
   <allowLaunch>true</allowLaunch>
   <allowNewRegistrations>true</allowNewRegistrations>
   <public>false</public>
   <created>true</created>
   <createdDate>2012-05-02T22:13:47.503+0000</createdDate>
   <userInvitations>
       <userInvitation>
           <email><![CDATA[email1@scorm.com]]></email>
           <url><![CDATA[ http://cloud.scorm.com/fasttrack/InvitationLaunch?userInvitationId=12af1419-7d4d-464a-9c24-e3b0271272e0]]></url>
           <isStarted>false</isStarted>
           <registrationId><![CDATA[as5a3fe8-8e02-4677-af83-f6d818256278]]></registrationId>
           <registrationreport format="course" regid="as5a3fe8-8e02-4677-af83-f6d818256278" instanceid="0">
               <complete>unknown</complete>
               <success>unknown</success>
               <totaltime>0</totaltime>
               <score>unknown</score>
           </registrationreport>
       </userInvitation>
       <userInvitation>
           <email><![CDATA[email2@scorm.com]]></email>
           <url><![CDATA[ http://cloud.scorm.com/fasttrack/InvitationLaunch?userInvitationId=288bc606-765f-4c28-bf10-cb219ca8d9cd]]></url>
           <isStarted>false</isStarted>
           <registrationId><![CDATA[b2103cd4-8d94-44da-8e25-b0b8822e567b]]></registrationId>
           <registrationreport format="course" regid="b2103cd4-8d94-44da-8e25-b0b8822e567b" instanceid="0">
               <complete>unknown</complete>
               <success>unknown</success>
               <totaltime>0</totaltime>
               <score>unknown</score>
           </registrationreport>
       </userInvitation>
   </userInvitations>
</invitationInfo>



getInvitationList

  • Semantics: This method returns a list of invitations that meet the filter criteria.

  • Required Arguments:

    • appid-- Your application id

  • Optional Arguments:

    • filter-- A regular expression that will be used to filter the list of invitations. Specifically only those invitations whose invitation Id’s match the given expression will be returned in the list.
    • coursefilter-- A regular express that will be used to filter the list of invitations. Specifically only those invitations that are associated with courses whose courseid’s match the given expression will be returned in the list.

  • Example Call:

    http://cloud.scorm.com/api?method=rustici.invitation.getInvitationList&appid=myappid&filter=35568984-16cf-4d81-92dd-ea69eb4dacd4

  • Example response:

    <invitationlist>
   <invitationInfo>
       <id><![CDATA[35568984-16cf-4d81-92dd-ea69eb4dacd4]]></id>
       <body><![CDATA[Dear [USER],<p>You have been invited to take 'Feedback 1.2 invite app'. To start your training click on the Play button or copy the training URL into your browser.</p><a href='[URL]'>Play course</a><br><br>URL: [URL]]]></body>
       <courseId><![CDATA[Feedback1.2inviteapp00ec1901-a17c-4165-9294-fdb105707541]]></courseId>
       <subject><![CDATA[Feedback 1.2 invite app]]></subject>
       <url/>
       <allowLaunch>true</allowLaunch>
       <allowNewRegistrations>true</allowNewRegistrations>
       <public>false</public>
       <created>true</created>
       <createdDate>2012-05-02T22:13:47.503+0000</createdDate>
       <userInvitations/>
   </invitationInfo>
</invitationlist>



changeStatus

  • Semantics: This method sets the availability settings of an invitation. An invitation with “enable” set to true can be launched. A public invitation with “open” set to true allows additional registrations to be created for the invitation.

  • Required Arguments:

    • appid-- Your application id
    • invitationId-- The id of the invitation to check the job status of
    • enable-- A boolean (true or false only) parameter specifying whether to set the invitation to enabled (launchable) or not.

  • Optional Arguments:

    • open-- A boolean (true or false only) parameter specifying whether a public invitation is still available for learner’s to create new registrations. For public invitations, “open” defaults to false for this method. Invitations are open (true) by default.
    • expirationdate-- The date this invitation will expire and can not be launched (formatted yyyyMMddHHmmss in UTC time)

  • Example Call:

    http://cloud.scorm.com/api?method=rustici.invitation.getInvitationStatus&appid=myappid&invitationId=937296cb-ae79-4190-bb6f-9a39b97785ac

  • Example response:

    <success />