DataService.svc methods and messages

The main service with which to interact with itslearning. It contains four different methods:

  1. AddMessage with which you can add messages to the message queue of the Organisation API. All asynchronous messages are handled through this method.

  2. GetMessageTypes which returns all the message types that are available to you.

  3. GetMessageResult which can be used to determine the status of a message previously added to the queue using the AddMessage method.

  4. GetExtensions which returns a list of all extensions supported by the Organisation API.

GetMessageTypes

Returns a list of the message types that the partner can access – in the scope of a site identified by the credentials. It provides the schema for the supported message types and should be considered the definitive source of information (it is dynamically created) for the API. If a partner has access to more than one site the results of GetMessageTypes may be different for each site as the allowable messages can be filtered on a site by site basis.

The message type IDs should not be regarded as statically defined. When developing against the API, you need handle the fact that IDs could change - and will vary between production and pre-production systems!

Request

GetMessageTypes request
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tem="http://tempuri.org/">
<soapenv:Header/>
<soapenv:Body>
<tem:GetMessageTypes>
<MethodParameters>
<request>GetMessageTypesRequest</request>
</MethodParameters>
</tem:GetMessageTypes>
</soapenv:Body>
</soapenv:Envelope>

Response

GetMessageTypes response
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/" xmlns:u="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<s:Header>
<o:Security s:mustUnderstand="1" xmlns:o="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
<u:Timestamp u:Id="_0">
<u:Created>2013-10-02T07:51:25.482Z</u:Created>
<u:Expires>2013-10-02T07:56:25.482Z</u:Expires>
</u:Timestamp>
</o:Security>
</s:Header>
<s:Body>
<GetMessageTypesResponse xmlns="http://tempuri.org/">
<GetMessageTypesResult xmlns:a="http://schemas.datacontract.org/2004/07/Itslearning.Integration.ContentImport.Services.Entities" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<a:DataMessageType>
<a:Identifier>14</a:Identifier>
<a:Name>Create.Calendar.Event</a:Name>
<a:ProcessingType>Synchronous</a:ProcessingType>
<a:Schema><![CDATA[<?xml version="1.0" encoding="utf-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns="urn:message-schema" elementFormDefault="qualified" targetNamespace="urn:message-schema">
<xs:element name="Message" type="MessageType" />
<xs:complexType name="MessageType">
<xs:sequence>
<xs:element name="SyncKeys" type="SyncKeysType" minOccurs="0" maxOccurs="1" />
<xs:element name="Events" type="EventsType" minOccurs="1" maxOccurs="1"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="SyncKeysType">
<xs:sequence>
<xs:element name="SyncKey" type="SyncKeyType" minOccurs="0" maxOccurs="100" />
</xs:sequence>
</xs:complexType>
<xs:complexType name="SyncKeyType">
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute name="ID" type="xs:ID" use="required"/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
<xs:complexType name="EventsType">
<xs:sequence>
<xs:element name="Event" type="EventType" minOccurs="1" maxOccurs="100" />
</xs:sequence>
</xs:complexType>
<xs:complexType name="EventType">
<xs:sequence>
<xs:element name="StartDateTime" type="xs:dateTime" minOccurs="1" maxOccurs="1"/>
<xs:element name="EndDateTime" type="xs:dateTime" minOccurs="1" maxOccurs="1"/>
<xs:element name="Description" type="xs:string" minOccurs="0" maxOccurs="1" />
<xs:element name="SyncKeyRef" type="xs:IDREF" minOccurs="0" maxOccurs="1" />
<xs:element name="IsLesson" type="xs:boolean" default="false" minOccurs="0" maxOccurs="1" />
<xs:choice minOccurs="1" maxOccurs="1">
<xs:element name="UserId" type="xs:integer" />
<xs:element name="UserSyncKey" type="xs:string" />
</xs:choice>
<xs:choice minOccurs="0" maxOccurs="1">
<xs:element name="CourseId" type="xs:integer" />
<xs:element name="CourseSyncKey" type="xs:string" />
</xs:choice>
<xs:choice minOccurs="0" maxOccurs="1">
<xs:element name="GroupHierarchyId" type="xs:integer" />
<xs:element name="GroupHierarchySyncKey" type="xs:string" />
</xs:choice>
</xs:sequence>
</xs:complexType>
</xs:schema>]]></a:Schema>
</a:DataMessageType>
 
</GetMessageTypesResult>
</GetMessageTypesResponse>
</s:Body>
</s:Envelope>

AddMessage

The AddMessage request is used to create content in itslearning. It returns a message identifier and adds the creation request to the job processing queue (in the case of asynchronous messages). Once the request is processed the status (success, warning, error) can be read by the GetMessageResult request (for the message identifier specified).

The data provided in AddMessage allow different types of content to be created in itslearning. It is a wrapper that contains the various supported message types, for example, create.myfiles.

Allow to specify an action to be processed, based on message type. Can have references to files added into temp content block storage area. Mainly usage depends on message type. Returns a message identifier which can be used with GetMessageResult to determine the processing status of this message.

Request

AddMessage Request
<Message xmlns="urn:message-schema">
<CreateCourseElementFile>
<CourseSyncKey>CourseSyncKey1</CourseSyncKey>
<Active>true</Active>
<UserSyncKey>itsla-26ba98b5-539a-4055-ba0e-249ed2673c36</UserSyncKey>
</CreateCourseElementFile>
<Files
<File Name="MyFileName0" Comment="My file comment0">c09e43b3-cb80-44c6-b96d-b29ca65d38b2</File>
<File Name="MyFileName1" Comment="My file comment1">7cad775b-03a3-49b7-b4ae-bcc91d186107</File>
<File Name="MyFileName2" Comment="My file comment2">a4dcdba9-a4ae-4137-93ef-8bd0b6c9b3a8</File>
</Files>
</Message>

Response

AddMessage response
<AddMessage>
<MethodParameters>
<AddMessageResponse>
<AddMessageResult>71</AddMessageResult>
</AddMessageResponse>
</MethodParameters>
</AddMessage>

GetMessageResult

Returns a status based on specified message identifiers. The service provides current message status (has it been processed or not) and if so the status (success, warning, error). If the result of GetMessageResult is a warning or error then it also provides one or more warning/error messages.

Request

GetMessageResult Request
<GetMessageResult>
<MethodParameters>
<request>
<messageId>71</messageId>
</request>
</MethodParameters>
</GetMessageResult>

Response

GetMessageResult
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/" xmlns:u="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<s:Header>
<o:Security s:mustUnderstand="1" xmlns:o="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
<u:Timestamp u:Id="_0">
<u:Created>2013-11-13T14:21:10.007Z</u:Created>
<u:Expires>2013-11-13T14:26:10.007Z</u:Expires>
</u:Timestamp>
</o:Security>
</s:Header>
<s:Body>
<GetMessageResultResponse xmlns="http://tempuri.org/">
<GetMessageResultResult xmlns:a="http://schemas.datacontract.org/2004/07/Itslearning.Integration.ContentImport.Services.Entities" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<a:MessageId>71</a:MessageId>
<a:Status>Finished</a:Status>
<a:StatusDetails>
<a:DataMessageStatusDetail>
<a:Entity>82</a:Entity>
<a:Message>Extension element was created</a:Message>
<a:SyncKey>e3a795c3-f28f-44bd-a347-53f5ecfe2263</a:SyncKey>
<a:Type>Info</a:Type>
</a:DataMessageStatusDetail>
</a:StatusDetails>
</GetMessageResultResult>
</GetMessageResultResponse>
</s:Body>
</s:Envelope>

GetExtensions

Returns a list of extensions that are supported by the Create.Extension.Instance method. The GetExtensions method actually requests the XSD schema describing the extension from the extension itself and returns it. Additionally it also offers some other metadata which might be useful for future Create.Extension.Instance requests.

Request

GetExtensions Request
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tem="http://tempuri.org/">
<soapenv:Header/>
<soapenv:Body>
<tem:GetExtensions/>
</soapenv:Body>
</soapenv:Envelope>

Response

GetExtensions
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/" xmlns:u="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<s:Header>
<o:Security s:mustUnderstand="1" xmlns:o="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
<u:Timestamp u:Id="_0">
<u:Created>2013-11-14T11:45:27.047Z</u:Created>
<u:Expires>2013-11-14T11:50:27.047Z</u:Expires>
</u:Timestamp>
</o:Security>
</s:Header>
<s:Body>
<GetExtensionsResponse xmlns="http://tempuri.org/">
<GetExtensionsResult xmlns:a="http://schemas.datacontract.org/2004/07/Itslearning.Integration.ContentImport.Services.Entities" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<a:Extension>
<a:ContentSchema><![CDATA[<?xml version="1.0" encoding="utf-16"?>
<xs:schema elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:import namespace="http://schemas.datacontract.org/2004/07/Itslearning.Platform.Widgets.Entities" />
<xs:import namespace="http://schemas.datacontract.org/2004/07/Itslearning.Platform.Entities" />
<xs:complexType name="PageContent">
<xs:sequence>
<xs:element minOccurs="0" name="ContentBlockSets" nillable="true" type="ArrayOfContentBlockSet" />
</xs:sequence>
</xs:complexType>
<xs:element name="PageContent" nillable="true" type="PageContent" />
<xs:complexType name="ArrayOfContentBlockSet">
<xs:sequence>
<xs:element minOccurs="0" maxOccurs="unbounded" name="ContentBlockSet" nillable="true" type="ContentBlockSet" />
</xs:sequence>
</xs:complexType>
<xs:element name="ArrayOfContentBlockSet" nillable="true" type="ArrayOfContentBlockSet" />
<xs:complexType name="ContentBlockSet">
<xs:sequence>
<xs:element minOccurs="0" name="ContentBlock" nillable="true" type="ContentBlockBase" />
<xs:element minOccurs="0" name="FileContents" nillable="true" type="ArrayOfFileContent" />
</xs:sequence>
</xs:complexType>
<xs:element name="ContentBlockSet" nillable="true" type="ContentBlockSet" />
<xs:complexType name="ContentBlockBase">
<xs:complexContent mixed="false">
<xs:extension xmlns:q1="http://schemas.datacontract.org/2004/07/Itslearning.Platform.Widgets.Entities" base="q1:ContentBlockSimple">
<xs:sequence>
<xs:element minOccurs="0" name="ColorSchema" type="q1:ColorSchema" />
<xs:element minOccurs="0" name="CreatedDateTime" nillable="true" type="xs:dateTime" />
<xs:element minOccurs="0" name="CreatedDateTimeFormatted" nillable="true" type="xs:string" />
<xs:element minOccurs="0" name="CreatedDescription" nillable="true" type="xs:string" />
<xs:element minOccurs="0" name="CreatedUserId" nillable="true" type="xs:int" />
<xs:element minOccurs="0" name="CreatedUserName" nillable="true" xmlns:q2="http://schemas.datacontract.org/2004/07/Itslearning.Platform.Entities" type="q2:UserName" />
<xs:element minOccurs="0" name="DeletedDateTime" nillable="true" type="xs:dateTime" />
<xs:element minOccurs="0" name="DeletedDateTimeFormatted" nillable="true" type="xs:string" />
<xs:element minOccurs="0" name="DeletedDescription" nillable="true" type="xs:string" />
<xs:element minOccurs="0" name="DeletedUserId" nillable="true" type="xs:int" />
<xs:element minOccurs="0" name="DeletedUserName" nillable="true" xmlns:q3="http://schemas.datacontract.org/2004/07/Itslearning.Platform.Entities" type="q3:UserName" />
<xs:element minOccurs="0" name="IsDeleted" type="xs:boolean" />
<xs:element minOccurs="0" name="IsPlaceholder" type="xs:boolean" />
<xs:element minOccurs="0" name="LastUpdatedDateTime" nillable="true" type="xs:dateTime" />
<xs:element minOccurs="0" name="LastUpdatedDateTimeFormatted" nillable="true" type="xs:string" />
<xs:element minOccurs="0" name="LastUpdatedDescription" nillable="true" type="xs:string" />
<xs:element minOccurs="0" name="LastUpdatedUserId" nillable="true" type="xs:int" />
<xs:element minOccurs="0" name="LastUpdatedUserName" nillable="true" xmlns:q4="http://schemas.datacontract.org/2004/07/Itslearning.Platform.Entities" type="q4:UserName" />
<xs:element minOccurs="0" name="PageId" nillable="true" type="xs:int" />
<xs:element minOccurs="0" name="SyncKey" nillable="true" type="xs:string" />
<xs:element minOccurs="0" name="Title" nillable="true" type="xs:string" />
</xs:sequence>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:element name="ContentBlockBase" nillable="true" type="ContentBlockBase" />
<xs:complexType name="ArrayOfFileContent">
<xs:sequence>
<xs:element minOccurs="0" maxOccurs="unbounded" name="FileContent" nillable="true" type="FileContent" />
</xs:sequence>
</xs:complexType>
<xs:element name="ArrayOfFileContent" nillable="true" type="ArrayOfFileContent" />
<xs:complexType name="FileContent">
<xs:sequence>
<xs:element minOccurs="0" name="ContentType" nillable="true" type="xs:string" />
<xs:element minOccurs="0" name="FileId" type="xs:int" />
<xs:element minOccurs="0" name="Location" nillable="true" type="xs:string" />
<xs:element minOccurs="0" name="Name" nillable="true" type="xs:string" />
</xs:sequence>
</xs:complexType>
<xs:element name="FileContent" nillable="true" type="FileContent" />
</xs:schema>]]></a:ContentSchema>
<a:ExtensionId>5</a:ExtensionId>
<a:Name>Page</a:Name>
<a:SupportsFileUpload>true</a:SupportsFileUpload>
</a:Extension>
<a:Extension>
<a:ContentSchema><![CDATA[<?xml version="1.0" encoding="utf-16"?>
<xs:schema elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:complexType name="FileLinkContent">
<xs:sequence>
<xs:element minOccurs="0" name="Active" type="xs:boolean" />
<xs:element minOccurs="0" name="Description" nillable="true" type="xs:string" />
<xs:element minOccurs="0" name="FileContentType" nillable="true" type="xs:string" />
<xs:element minOccurs="0" name="FileLocation" nillable="true" type="xs:string" />
<xs:element minOccurs="0" name="FileName" nillable="true" type="xs:string" />
<xs:element minOccurs="0" name="HideLink" type="xs:boolean" />
<xs:element minOccurs="0" name="Link" nillable="true" type="xs:string" />
<xs:element minOccurs="0" name="OpenIn" type="ResourceEntity.OpenInType" />
<xs:element minOccurs="0" name="OpenWith" type="ResourceEntity.OpenWithType" />
</xs:sequence>
</xs:complexType>
<xs:element name="FileLinkContent" nillable="true" type="FileLinkContent" />
<xs:simpleType name="ResourceEntity.OpenInType">
<xs:restriction base="xs:string">
<xs:enumeration value="Unknown" />
<xs:enumeration value="ExistingWindow" />
<xs:enumeration value="NewWindow" />
<xs:enumeration value="Popup640" />
<xs:enumeration value="Popup800" />
<xs:enumeration value="Popup1024" />
</xs:restriction>
</xs:simpleType>
<xs:element name="ResourceEntity.OpenInType" nillable="true" type="ResourceEntity.OpenInType" />
<xs:simpleType name="ResourceEntity.OpenWithType">
<xs:restriction base="xs:string">
<xs:enumeration value="Unknown" />
<xs:enumeration value="View" />
<xs:enumeration value="Link" />
<xs:enumeration value="Download" />
</xs:restriction>
</xs:simpleType>
<xs:element name="ResourceEntity.OpenWithType" nillable="true" type="ResourceEntity.OpenWithType" />
</xs:schema>]]></a:ContentSchema>
<a:ExtensionId>5000</a:ExtensionId>
<a:Name>File or link</a:Name>
<a:SupportsFileUpload>true</a:SupportsFileUpload>
</a:Extension>
</GetExtensionsResult>
</GetExtensionsResponse>
</s:Body>
</s:Envelope>

Common validation rules

  1. Message type with identifier [MessageType] does not exist. Supply valid message type identifier.

  2. Messages of type with identifier [MessageType] are "Read" messages. They cannot be processed in this method.

  3. You don't have access to specified message type: [MessageType], please ask for your security setup change.

  4. Message contains duplicates for syncKeys: [SyncKeys]. Make sure your syncKeys are globally unique.

  5. Error while retrieving the message processor.

  6. Message with identifier [MessageId] not found.

  7. Message with identifier [MessageId] not found in scope of current security context. Check if you're using valid username and password for that message.

  8. Unable to read schema for provided message: [ExceptionMessage]

  9. Message must start with <Message xmlns="urn:message-schema">

  10. SyncKey must be unique globaly. Can't use the same syncKey twice. [SyncKey]

  11. Errors when validating message against schema: [ExceptionMessage]

  12. [ElementName] element can't be read

  13. Errors when validating message against schema: [validation exception]

  14. An unknown error has occured.