Communications with the plugin or module

A brief technical overview of plugins and modules

The extension system for Plugins and Modules in itslearning uses its own system for providing SSO between itslearning and the remote web application.

The system also exposes a set of REST API services that are meant to be used exclusively with plugins and modules. These API services allow you to obtain additional information about the user, to help you in providing personalized content.

Whenever a user activates your plugin or module in itslearning, itslearning issues a request to your plugin or module's predefined URL and passes data as a JSON formated query string. The data provided contains values that you can use to identify the current users, as well as OAuth tokens you need to call the REST API. We call this SSOV2 for Plugins and Modules.

This also means that the methods cannot be used by Applications, which use a custom system.

The processes are explained below.

Communications, authorization and security

Communications workflow between itslearning and plugins

Here's an overview of the process that is performed when a teacher adds plugin content to a note:

  • itslearning sends a request to the plugin with information in the query string. See Parameters for more details.

  • The plugin performs its own logic. This usually means that the user interacts with the remote plugin provider site to create or define some content, and the REST API is called to retrieve necessary information from itslearning.

  • The plugin site then creates a form and posts it back to itslearning using the PostTo URL which is specified in the request.

  • The content is then processed by itslearning and a placeholder is inserted into the editor. When the user saves and views the newly created content, the plugin content is displayed to the user along with other data the user may have created in the rich text editor, such as images and text.

  • itslearning just renders HTML which was provided by the plugin. There is no need for specific logic in the plugin definition on itslearning's side.

This can be illustrated as shown below:

images/download/attachments/284207385/image2013-8-29_15_22_23.png

Communications workflow between itslearning and modules

Communications with modules is a even simpler.

On launch, itslearning requests the URL you have provided as the launch URL, along with a query string containing the parameters listed below.
Whichever data you return in response to this request is presented inside an iframe in itslearning.

You may use the REST API to personalize the content, but after launch, all interaction happens directly between the user and your application.

Example request from itslearning to the plugin (or module)

Now, let's consider this example:

First, an teacher inserts a plugin to the editor, and she activates it from itslearning.

Then, itslearning is calling the remote code for the plugin by sending the following request:

Sample request from itslearning to a plugin
GET http://www.myitslplugin.com:902/?itsl_auth=%7b%22TimeStamp%22%3a%222014-01-04T17%3a00%3a30%22%2c%22Country%22%3a%22NO%22%2c%22CustomerId%22%3a%221%22%2c%22EditReference%22%3a%22%22%2c%22EducationalLevel%22%3a%22Higher%22%2c%22FirstName%22%3a%22Admin%22%2c%22Language%22%3a%22en-US%22%2c%22LastName%22%3a%22Admin%22%2c%22OAuthToken%22%3a%2230093542-3827-4b61-b49a-f4914ffa8649%22%2c%22OAuthTokenSecret%22%3a%22822680ad-a438-4672-a009-e6e584a14f31%22%2c%22PersonId%22%3a%221%22%2c%22PostTo%22%3a%22https%3a%5c%2f%5c%2fwww.itslearning.com%5c%2feditor%5c%2fInsertPluginContentHtml.aspx%3fExtensionId%3d5006%26EditorClientInstanceId%3dctl00_ContentPlaceHolder_Description_DescriptionEditorCKEditor_ctl00%22%2c%22Role%22%3a%22Staff%22%7d&itsl_sign=a77702c1f05a0c77177be61033b5c27f HTTP/1.1
Host: www.myitslplugin.com:902
Connection: keep-alive
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8
User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/31.0.1650.63 Safari/537.36
Accept-Encoding: gzip,deflate,sdch
Accept-Language: en-US,en;q=0.8,no;q=0.6
Cookie: ...

The query string is URL decoded, formatted and explained below:

Parameter name

Modules

Plugins

Sample Value

Explanation

itsl_auth

images/s/-vc9tak/8803/xi7l17/_/images/icons/emoticons/check.svg

images/s/-vc9tak/8803/xi7l17/_/images/icons/emoticons/check.svg

itsl_auth={
"TimeStamp":"2014-01-04T17:00:30",
"Country":"NO",
"CustomerId":"1",
"EditReference":"",
"EducationalLevel":"Higher",
"FirstName":"Admin",
"Language":"en-US",
"LastName":"Admin",
"OAuthToken":"30093542-3827-4b61-b49a-f4914ffa8649",
"OAuthTokenSecret":"822680ad-a438-4672-a009-e6e584a14f31",
"PersonId":"1",
"PostTo":"https:\/\/www.itslearning.com\/editor\/InsertPluginContentHtml.aspx?
extensionId=5006&EditorClientInstanceId=ctl00_ContentPlaceHolder_Description_DescriptionEditorCKEditor_ctl00",
"Role":"Staff"
}

JSON serialized list of key/value pairs.

The query string contains data that can be used to construct an OAuth-secured HTTP request

itsl_sign

images/s/-vc9tak/8803/xi7l17/_/images/icons/emoticons/check.svg

images/s/-vc9tak/8803/xi7l17/_/images/icons/emoticons/check.svg

a77702c1f05a0c77177be61033b5c27f

The signature to validate the message. It is a concatenation of the itsl_auth parameter and the shared secret for the plugin. For sample code and more information on how to compute the signature, see Best practices, tips and tricks

launch_parameters

images/s/-vc9tak/8803/xi7l17/_/images/icons/emoticons/check.svg

images/s/-vc9tak/8803/xi7l17/_/images/icons/emoticons/error.svg

report:12

Optional. The launch parameters for the extension Module, which add possibility to open the specific content in the Module after authorization via the ticket.

The value of this parameter can be any string.

Warning! You also should validate this parameters!

JSON key/value pairs from the query string

Itslearning supply modules and plugins with mostly the same JSON formatted data.

There are some subtle differences to accommodate the difference in functionality. The below table explains the JSON-formatted key/value pairs that are passed by itslearning:

Parameter

Modules

Plugins

Sample Value

Explanation

OAuthToken

images/s/-vc9tak/8803/xi7l17/_/images/icons/emoticons/check.svg

images/s/-vc9tak/8803/xi7l17/_/images/icons/emoticons/check.svg

30093542-3827-4b61-b49a-f4914ffa8649

OAuthToken for consumer that can be used for authentication with itslearning's restapi

OAuthTokenSecret

images/s/-vc9tak/8803/xi7l17/_/images/icons/emoticons/check.svg

images/s/-vc9tak/8803/xi7l17/_/images/icons/emoticons/check.svg

aaeddd9d-6e2d-43ec-8e7c-18cd6584bc8c

OAuthTokenSecret for consumer that can be used for authentication with itslearning's restapi

Country

images/s/-vc9tak/8803/xi7l17/_/images/icons/emoticons/check.svg

images/s/-vc9tak/8803/xi7l17/_/images/icons/emoticons/check.svg

NO

The user's country

CustomerId

images/s/-vc9tak/8803/xi7l17/_/images/icons/emoticons/check.svg

images/s/-vc9tak/8803/xi7l17/_/images/icons/emoticons/check.svg

1

The customer the user request is coming from. Integer. A customer can contain many schools.

EducationalLevel

images/s/-vc9tak/8803/xi7l17/_/images/icons/emoticons/check.svg

images/s/-vc9tak/8803/xi7l17/_/images/icons/emoticons/check.svg

Higher

Level of user's education

Language

images/s/-vc9tak/8803/xi7l17/_/images/icons/emoticons/check.svg

images/s/-vc9tak/8803/xi7l17/_/images/icons/emoticons/check.svg

en-GB

The language the user is using

FirstName

images/s/-vc9tak/8803/xi7l17/_/images/icons/emoticons/check.svg

images/s/-vc9tak/8803/xi7l17/_/images/icons/emoticons/check.svg

John

User’s given name.

LastName

images/s/-vc9tak/8803/xi7l17/_/images/icons/emoticons/check.svg

images/s/-vc9tak/8803/xi7l17/_/images/icons/emoticons/check.svg

Smith

User’s family name.

PersonId

images/s/-vc9tak/8803/xi7l17/_/images/icons/emoticons/check.svg

images/s/-vc9tak/8803/xi7l17/_/images/icons/emoticons/check.svg

2

Unique Id of the person for this customer. No relation to UserId for applications.

Role

images/s/-vc9tak/8803/xi7l17/_/images/icons/emoticons/check.svg

images/s/-vc9tak/8803/xi7l17/_/images/icons/emoticons/check.svg

Learner

The role that the user has in itslearning. Can be one of Staff, Learner, Guest. This parameter should not be used as a permission system, but rather to for example prevent Learner's from seeing parts of the application that you'd only like Staff users to see.

Timestamp

images/s/-vc9tak/8803/xi7l17/_/images/icons/emoticons/check.svg

images/s/-vc9tak/8803/xi7l17/_/images/icons/emoticons/check.svg

2014-01-04T17:00:30

Time stamp in UTC

PostTo

images/s/-vc9tak/8803/xi7l17/_/images/icons/emoticons/error.svg

images/s/-vc9tak/8803/xi7l17/_/images/icons/emoticons/check.svg

https:\/\/www.itslearning.com\/editor\/InsertPluginContentHtml.aspx?
ExtensionId=5006&EditorClientInstanceId=ctl00_ContentPlaceHolder_Description_DescriptionEditorCKEditor_ctl00

The URL where the plugin should post back it's html content to itslearning. Note: this may change dynamically, so don't parse it or expect a certain number of parameters.

EditReference (Optional)

images/s/-vc9tak/8803/xi7l17/_/images/icons/emoticons/error.svg

images/s/-vc9tak/8803/xi7l17/_/images/icons/emoticons/check.svg

1232

A value that the plugin can use to restore a previous state. The plugin will only receive this parameter if the plugin has posted back EditReference=[editReferenceValue] when it was saved. As an example, if the plugin is a drawing tool that generates an image, the editReference could be stored in the plugin's database as some kind of identifier, and be used when opening the plugin in edit-mode to retrieve the drawing-state of the image. This would enable a user to draw something, and later edit his drawing.

CourseId

images/s/-vc9tak/8803/xi7l17/_/images/icons/emoticons/check.svg

images/s/-vc9tak/8803/xi7l17/_/images/icons/emoticons/error.svg

41

If extension is executed from a course, unique course identifier is included.

CourseSyncKey

images/s/-vc9tak/8803/xi7l17/_/images/icons/emoticons/check.svg

images/s/-vc9tak/8803/xi7l17/_/images/icons/emoticons/error.svg

AABBCC

If extension is executed from a course and the course's members are synchronized from a hierarchy, the unique course synchronization key is included. It will contain "N/A-NO-ACCESS-PROTECTED-DATA" if the requesting application has not been approved for extended data

ItslearningSection

images/s/-vc9tak/8803/xi7l17/_/images/icons/emoticons/check.svg

images/s/-vc9tak/8803/xi7l17/_/images/icons/emoticons/error.svg

CourseMenu

Provides the section of itslearning where the user clicked to activate the extension. Possible values: AdministrationMenu, TopMenu, EPortfolio, HeadteacherMenu, MentorMenu, CourseMenu, AssessmentRecord

TermId

images/s/-vc9tak/8803/xi7l17/_/images/icons/emoticons/check.svg

images/s/-vc9tak/8803/xi7l17/_/images/icons/emoticons/error.svg

111

If extension is executed from an assessment record, unique term identifier is included.

TermSyncKey

images/s/-vc9tak/8803/xi7l17/_/images/icons/emoticons/check.svg

images/s/-vc9tak/8803/xi7l17/_/images/icons/emoticons/error.svg

Term_12

If extension is executed from an assessment record the unique term synchronization key is included.

Posting plugin content back to itslearning for display.

(Plugins only)

When your application has collected all the necessary data and is ready to return some content to itslearning, it will have to do so by issuing a HTTP POST request to the URL supplied by itslearning.By posting directly to the itslearning-provided URL, we are reusing the end user's itslearning session, so there is no need for additional authentication.The typical content to post back would be an iframe or object element that will still retrieve its main content from your servers.

You will need to post data using the ISO-8859-1 character set.

Optional POST parameter sent to itslearning from the plugin

Parameter name

Sample value

Explanation

PreviewURL

https://myapp.example.com/resources/image/23ksxp3.png

Contains a URL to a preview image of the plugin content. This will be used as a placeholder in the rich text editor. See quick start for more information.
If you include the PreviewURL parameter it must contain a link to an image satisfying the following criteria:

  • The link must be using a secure connection, i.e. https.

  • The image must be no wider than 440 pixels

  • The image must be no higher than 220 pixels.

  • The image must be no larger than 100 kilobytes.

  • The image must be of one of the following formats: png, jpg, gif (no animations).

Viewing licensed / restricted content

If you are serving plugin content which requires a license, you need to authenticate and authorize users trying to view this content.

This can be done by appending a specific authentication string to links to external content inside the plugin.
The string is {itsl_auth} and it is a placeholder which will be substituted for a user's authentication parameters by itslearning. See below for the data available in the query string..

Don't use single quotes around href tags containing {itsl_auth} as the parameters substituted for the {itsl_auth} string may contain single quotes.

Example

Let's say we have a plugin which provides direct links to scientific articles from within itslearning. These articles are not publicly available, but a university has bought a license to use this service. This means that we need to authenticate the student when she clicks a link to an article. A professor writes a note where he recommends an article called "The duality principle of electron spin in sparse quantum fields" to his students. If he simply added a link to this article (assuming it was even possible) the students would have to log in on the content provider site to access the article.

By using a plugin the content provider inserts a link to the article into the editor:

http://www.sciencearticles.no/nepstad_birkeland/electron_spin.pdf?{itsl_auth}.

itslearning then inserts authentication parameters so that when the student clicks the link the content provider is able to authenticate the user.

Legacy information for plugins using SSO version 1

HTTP GET Parameters passed in SSOv1

The below parameters have been removed from SSO v2, and are included as a reference only. To retrieve this information with SSOv2, please use the corresponding REST API methods.

Parameter name

Sample value

Explanation

LicenseIds

101,104,105

A comma separated list of integers representing the itslearning license IDs valid for the current user. This parameter is only sent if your application is licensed.

ExternalLicenseIds

yourownlicenseid1,
yourownlicenseid2

A comma separated list of license IDs from your own licensing system which you have entered into the license agreement in itslearning. Each ID corresponds to an itslearning license ID in the LicenseIds parameter. (ExternalLicenseIds[i] corresponds to LicenseIds[i]) There are always an equal amount of fields in LicenseIds and ExternalLicenseIds, although the fields in ExternalLicenseIds can be empty. If your license ID string contains commas (',') or backslashes ('\') these will be escaped, i.e. they will be preceded by a backslash. E.g. "temp\license2,3" will become "temp\\license2\,3". This parameter is only sent if your application is licensed.

SchoolId

3|HullPrimary,2|,5|,4|,14|,28|,25|,22|,13|,26|

A comma separated string of IDs of the schools the user belongs to. A schoolID is unique within a customerID. Each school ID may actually consist of two IDs. One numeric itslearning school ID X and a legal ID Y. These are separated by a pipe character '|', as X|Y. The school might not have a legal ID. In that case its place is empty as you see in the example where only the first school has a legal ID ("HullPrimary").