LTI tool custom parameters

This article applies to LTI 1.1 only

Custom parameters are used to send some specific information that helps the Talis Aspire LTI Tool to automatically find a reading list related to the course, unit or module that a learning environment might be related to.

Why do you need these?

In many cases you will need to use a custom parameter to allow the module or course code in your learning management system to be ‘mapped’ to your module or course codes in Talis Aspire.

In the LTI conversation there are two parameters passed called the context_label (often a code or shortened title) and context_title (often the title of the module or course in the LTI consumer). Learning management systems decide what data is in these fields. Talis Aspire treats the fields in order of precedence, looking for module codes and time periods in the context_label and then the context_title.

This tool supports the following parameters

All parameters are optional and will default to the values shown here. The values here all relate to the use of regular expressions and back references in the context of using PHP’s preg_replace() function.

• node_code_regex
  • A regular expression that will capture the node code as it should be found in Talis Aspire Reading Lists.
  • Defaults to selecting the whole value /^(.*)$/
  • When creating your own the regex should match the WHOLE string and contain at least one group.
  • Remember that if the node code appears in the title there will likely be other characters after the chosen code.
• node_code_replacement
  • A replacement string (which can contain back references).
  • Defaults to the first back reference ${1}
  • The resultant string should match the code of a node in the Talis Aspire hierarchy.
• time_period_regex
  • A regular expression that will capture the time period as it should be found in Talis Aspire Reading Lists.
  • Defaults to selecting the whole value /^(.*)$/
  • When creating your own the regex should match the WHOLE string and contain at least one group.
• time_period_replacement
  • A replacement string (which can contain back references).
  • Defaults to the first back reference ${1}
  • The resultant string should match a time period slug as configured in Talis Aspire. Read more on Time Periods
• knowledge_grouping_code
  • The actual node code. This can be used for testing or for edge cases where the node code must be passed manually.
• time_period
  • The actual time period string. This will be matched against the time period 'slug' that Talis Aspire uses in our List Linking API. This can be used to tell us the appropriate time period if it is not contained in the context_title or context_label

In most learning management systems the custom parameters can be set at a global level for all links created with this tool. You will probably have to add them to a text box as key value pairs on individual lines like this.

 node_code_regex=/^(.*)$/
 node_code_replacement=${1}

HELP! Regular expressions make me feel wobbly!

You can get help on regular expressions using these excellent tools:

• RegexOne — interactive tutorial which leads you through the basic concepts of regular expressions step by step. Use this if you have never or rarely written a regular expression.
• regex101 — interactive editor which shows an explanation of your regular expression.
• regexplanet — this tool allows you to setup a number of different test cases, and then execute the regular expression and see how different php functions would handle that expression. In the LTI tool we would be using preg_replace()

Note: In Blackboard, using an = in a regular expression (e.g. node_code_regex=/^(?=thing)(.*)$/) will cause blackboard to fail to validate the parameters and throw an error when you try to save the settings. Try to write your regular expressions without look-ahead references!

Some common examples:

These examples show the module code as it might appear in the learning management system, with corresponding regular expressions and the values expected to be seen in Talis Aspire Reading Lists.

Trouble shooting

Because these types of integration are typically running in a place which Talis staff do not normally have access to, it can be hard for Talis to see all the information they need to diagnose any issues.

When raising an issue about the LTI integration, please submit the following information along with your support ticket.

• The name and version of the learning environment you are using. e.g. Blackboard Learn October 2014 release
• If you are using the Moodle plugin - the name and version of the plugin that you have installed.
• A screen-shot of the LTI settings screens, including the launch URL and any custom parameters
• A screen-shot of any other configuration screens that you have edited when setting up the integration (e.g. you added the Moodle plugin)
• A screen-cast of the issue happening. Please make sure that we can see the browser location bar and status bars, as these often give very important clues.
• We may also ask you to follow these instructions for generating a .har file.