Communications with the plugin or module
Page contents
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:
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:
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 |
|
|
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 |
|
|
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 |
|
|
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 |
|
|
30093542 - 3827 -4b61-b49a-f4914ffa8649 |
OAuthToken for consumer that can be used for authentication with itslearning's restapi |
OAuthTokenSecret |
|
|
aaeddd9d-6e2d-43ec-8e7c-18cd6584bc8c |
OAuthTokenSecret for consumer that can be used for authentication with itslearning's restapi |
Country |
|
|
NO |
The user's country |
CustomerId |
|
|
1 |
The customer the user request is coming from. Integer. A customer can contain many schools. |
EducationalLevel |
|
|
Higher |
Level of user's education |
Language |
|
|
en-GB |
The language the user is using |
FirstName |
|
|
John |
User’s given name. |
LastName |
|
|
Smith |
User’s family name. |
PersonId |
|
|
2 |
Unique Id of the person for this customer. No relation to UserId for applications. |
Role |
|
|
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 |
|
|
2014 - 01 -04T17: 00 : 30 |
Time stamp in UTC |
PostTo |
|
|
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) |
|
|
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 |
|
|
41 |
If extension is executed from a course, unique course identifier is included. |
CourseSyncKey |
|
|
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 |
|
|
CourseMenu |
Provides the section of itslearning where the user clicked to activate the extension. Possible values: AdministrationMenu, TopMenu, EPortfolio, HeadteacherMenu, MentorMenu, CourseMenu, AssessmentRecord |
TermId |
|
|
111 |
If extension is executed from an assessment record, unique term identifier is included. |
TermSyncKey |
|
|
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.
|
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"). |