This article contains an explanation of all the custom parameters we currently support. Some LMS, like Moodle, allow the configuration of the custom parameters at both the tool configuration level and at the test level. However, some LMS, like Canvas, only allow the configuration of parameters at the configuration level.
If a custom parameter is defined at the tool configuration level it will be applied to all tests (that are launched after it is configured). If it is defined at the test level, it will only be applied at the test level. If a custom parameter is defined at the configuration level it can not be changed at the test level.
How custom Parameters work
In order for LTI integration with Inspera to work as intended, some extra data may be required to allow each institution to shape the LTI integration to their own needs. This extra data is configured using custom parameters. It is sent to Inspera whenever there is a new launch by a teacher.
Only the LMS admin can configure custom parameters at the configuration level. These can be changed at any point in time and will impact all future launches for all tests (old and new).
In some LMS, teachers can set custom parameters at the test level and those will only be used in all future launches of that specific test.
If not set, the default values of all custom parameters is false, which means that it is only necessary to configure the custom parameters that are relevant for the workflows of your institution.
Important custom parameters
There are some custom parameters that should always be configured to ensure the proper functioning. These should be configured at the tool configuration level. Some of these may only be relevant for a specific LMS but they will not hurt your workflow. You may check each of them to get a better understanding of what they do.
- skip_incomplete_members = true (this prevents interruptions in the enrollment of contributors/candidates in the case of errors)
- use_template_on_create = true (only for institutions that work with templates and use an LMS that allows custom parameters at the test level)
- Keep_test_title = true (relevant for institutions using D2L).
You should also consider:
- How are the users identified (see User Synchronization with IA section)
- Should candidates/instructors be automatically enrolled in the test (see the common setups or the contributors management, candidates management and user synchronization sections)
Common Setups
-
In order to achieve this, you should use the custom parameter:
- enroll_candidates = true
If you want this to happen in all tests in all courses, add it to the tool configuration. If you want this to happen only in some tests, do not set it up at the tool configuration level and instruct your teachers to set it up when creating the test where this should be applied (if the LMS supports it).
Extra: if you want students that are removed from the course to be disenrolled from the IA test, use remove_candidates=true. It’s important to note that this will remove any candidates that may have been added to the test directly in IA if they are not added to the course in the LMS.
-
In order to achieve this, you should use the custom parameter
- enroll_contributors = true
If you want this to happen in all tests in all courses, add it at the tool configuration level. If you want this to happen only in some tests, do not set it up at the tool configuration level and instruct your teachers to set it up when creating the test where this should be applied (if the LMS supports it).
Extra: if you want teachers that are removed from the course to be removed as contributors from the IA test, use remove_contributors=true. It’s important to note that this will remove any contributors that may have been added to the test directly in IA, if they are not added as teachers to the course in the LMS.
-
In most cases when using SSO, the unique identifier for users is the email. In that case, you should add the configuration:
- username_resolver=BY_EMAIL
In case the unique identifier is different you need to identify the correct one and define the username_resolver custom parameter accordingly. For more details please check the documentation on username_resolver under the user synchronization section.
You should also identify the correct auth type (google, saml, etc) for user identification. This will be the same as the one configured when setting up the IA instance. After identifying it, configure the custom parameter:
- lti_authtype=<the same auth type>
For the list of available values check the section about this custom parameter in the user synchronization section.
Both these custom parameters need to be defined at the tool configuration level.
-
Yes. With the candidateid_resolver custom parameter.
In order to identify the proper value of the parameter (you can check the possible values in the candidates management section), the LMS system admin must identify the LTI property that contains the name of the candidate and/or run define the custom candidateid_resolver accordingly. They can then use run a test in debug mode to see the values being sent to Inspera.
For instance, if it is the email, it should be
- candidateid_resolver=BY_EMAIL
-
There can be three different scenarios
- The user already exists in IA and has at least the required roles
- The user remains unchanged in IA
- The user already exists in IA but does not have the required roles
- The required roles will be added to the user, the remaining roles they may have will remain
- The user does not yet exist in IA
- A new user is created in IA with the required roles
This happens either during teacher enrollment or when the teacher launches the test through LTI.
The required roles will depend on the mapping between the LMS and IA roles.
There are two mappings:
- LTI - IA
- LTI offers some roles (like instructor) and these roles are mapped to the roles in IA
- The default mapping is instructor in LTI -> Author, Planner, Grader, Chief Invigilator in IA
- If another mapping is required please reach out to our support team. IA does not support mapping of subroles
- LMS - LTI
- The LMS admin must ensure that the LMS - LTI mapping is properly set up so that the LTI roles are then mapped to IA
- If the LTI - IA mapping is the default one, all LMS teacher roles should be mapped to the LTI instructor role
- The user already exists in IA and has at least the required roles
- If two or more LMS are configured to the same IA tenant, a prefix should be defined that is unique to this LMS. This should be configured at the tool configuration level. This prefix will be added as a prefix to test id to distinguish between tests created through different LMS and it can have any value the LMS system admin so chooses:
- arid_prefix=<value defined by the system admin>
- If this is happening, most likely the LMS admin configured that same custom parameter at the tool configuration level and it can not be overridden. Check with them. If that is not the case, use the debug custom parameter to verify which values are being sent to IA. If the current values are being sent but resulting in an incorrect behaviour please reach out to our service desk.
List of Custom Parameters
Remember that if not configured, all custom parameters will default to false.
- Contributors Management
- Candidates Management
- General User Management
- User Synchronization with IA
- Distinction between LMS
- Debug
- Test Information
Contributors Management
enroll_contributors
- If false, no contributors (apart from the current user) will be automatically added to the test in IA. However, if a teacher clicks on the link to the test in the LMS they will be enrolled as contributors regardless of this parameter.
- If true, the users added as participants in the course will be automatically added to the test in IA as contributors.
remove_contributors
- If false, removing a participant from the course in the LMS will not have an impact on the test contributors in IA.
- If true, if a user has been added as a contributor to a test in IA but is not (or no longer) a participant in the course in the LMS, then they will be removed as contributor.
Candidates Management
enroll_candidates
- If false, no candidates will be automatically enrolled in the test in IA.
- If true, the students added as participants in the course will be automatically enrolled in the test in IA as candidates.
remove_candidates
- If false, removing a student from the course’s participants list in the LMS will not remove the corresponding candidates from the test in IA.
- If true, if a user has been added as a candidate to a test in IA but is not (or no longer) a participant (as a student) in the course in the LMS, then they will be removed from the candidates list in the test in IA.
General User Management
skip_incomplete_members (this should always be set to true)
- If false, if an error occurs when enrolling a candidate or a contributor, the rest of the candidates/contributors will not be enrolled.
- If true, if an error occurs when enrolling a candidate or a contributor, that user will be skipped and the enrollment will continue.
- Should be set at the tool configuration level.
User Synchronization with IA
As explained in our LTI documentation, when a teacher launches a test through the LMS two things happen:
- Log the user into IA
- Enroll the user into the test
Teachers who are not supposed to be enrolled in the test in IA should not click on the link to the test in the LMS.
In order for this to happen, it is necessary to define the username and the external id that should be associated with this user in IA. This is used when creating the users in IA (if applicable) and to identify an already created user.
These are also used when a user wants to log in directly into IA (not through the LMS).
As such, it is important to ensure that the username and external_id created when the user comes from the LMS are the same that is used when the user access IA directly.
The following custom parameters should be considered to ensure a seamless user identification process:
- username_resolver
- lti_username_externalid_suffix
- lti_authtype
All these custom parameters should be set at the tool configuration level.
username_resolver
- this custom parameter defines how the username external_id for the users in Inspera are defined
- every username must be unique, so the username_resolver should ensure that no users will end up with the same username
- by default, the username is the first and last name and the external_id is based on the user_id and oauth_client_key
- if the default configuration doesn't ensure the uniqueness of the username a different configuration must be selected. Alternatives: BY_EMAIL, BY_SOURCEDID, BY_INSPERA_PROPERTY. For more information on the LMS fields used, please check the table inside the expandable the section
-
The following table explains which fields from each service are used to build the external_id and the username.
Value for username_resolver Login Membership External_ID & Username DEFAULT user_id = user_id
prefix comes from the custom parameter lti_username_externalid_suffix
given_name = lis_person_name_given
family_name = lis_person_name_family
user_id =userId
given_name = givenName
Family_name = familyName
external_id: oauth_client_key+user_id+prefix
username = given_name+family_name
BY_USERID Same as DEFAULT Same as DEFAULT Same as DEFAULT BY_EMAIL email = lis_person_contact_email_primary email = email external_id = email
username = email
BY_SOURCEDID source_id = lis_person_sourcedid source_id = sourcedId external_id = source_id
username = source_id
BY_INSPERA_PROPERTY
This requires two extra custom parameters
value = inspera_property_lti_login value = inspera_property_membership external_id = value
username = value
How to use BY_INSPERA_PROPERTY value for the username_resolver:
- This allows the usage of any field from the LTI login and membership services.
- The inspera_property_lti_login and inspera_property_membership custom parameters should be set to the corresponding field names.
Example:
- A user wants to use the custom field “ext_user_username” in login and “ext_user_username2” in membership (made up names). They should set the custom parameters as:
- username_resolver=BY_INSPERA_PROPERTY
- inspera_property_lti_login=ext_user_username
- inspera_property_membership=ext_user_username2
lti_username_externalid_suffix
- Used to define the suffix for the external_id mentioned in the description of the username_resolver. It will normally be something like “@example.com”
lti_authtype
- In IA we may have different ways of logging the same user in (GOOGLE, GENERIC_SAML, etc). There is an external_id associated with each of these. These are internally called auth_type. If there is a specific login, then this needs to be set up to match the same.
- Default is LTI
- Possible values: 'GENERIC_SAML', 'GOOGLE', ‘OIDC’, ‘SHIBBOLETH’
-
For this example username_resolver=BY_EMAIL and lti_authtype=LTI are both set as the email is the unique identifier and the oauth type is SAML.
Steps Needed:
-
Login to your Inspera portal using SSO to check externalUserId mapping field in the saml-assertion. The same field will need to be mapped as externalUserId from Inspera and the LMS. Use a test user to identify the email address attribute from the SAML token.
-
In the Developer debugging window, get the SAML response for the assertion https://{domain}/saml/endpoint/assertion
-
Decode the SAML response using any SAML tool. The Decoded version should be similar to the following
- Inspera accepts ‘urn:oid:1.3.6.1.4.1.5923.1.1.1.6’ name or the friendly-name 'eduPersonPrincipleName' as the default attribute-name for holding the externalUserId in the SAML response. (SAML field reference)
- If eppn (eduPersonPrincipleName) is not available in the SAML response, you will need to add this to attributelist in SAML configuration. This is the field that will be used for mapping the user across both the platforms - LMS and Inspera.
- By default, Inspera accepts eppn as externalUserId. If you want to use another attribute, you need to inform Inspera during the SAML setup.
- If we can identify an attribute within the SAML assertion that contains the email address, and then combine it with BY_EMAIL username_resolver. This will work if externalUserId is the same in Inspera and LMS. Using eppn with BY_EMAIl only works if eppn is holding the same email-address as registered in the LMS.
-
candidateid_resolver
- When a student is launching the test from the LMS or is being enrolled through the enroll_candidates custom parameter, a candidate_id needs to be created to represent that student on that test. A student can take several tests but a candidate id needs to be unique for each test.
- This resolver indicates how the candidate_id is built on Inspera. By default the user_id is displayed, but other values can be used.
- It is important to ensure that candidate_ids are unique. If there are 2 or more students with the same candidate_id, only the first one will be enrolled in the test. Alternative values: BY_EMAIL, BY_NAME, BY_SOURCEDID, BY_INSPERA_PROPERTY. For more information please check the table inside the expandable section
-
The following table explains which fields from each service are used to build the candidate_id.
Value for candidateid_resolver lti-login-parameter membership-name DEFAULT user_id userId BY_EMAIL lis_person_contact_email_primary email BY_NAME name name BY_SOURCEDID lis_person_sourcedid sourcedId BY_INSPERA_PROPERTY inspera_property_lti_login inspera_property_membership How to use BY_INSPERA_PROPERTY value for the candidateid_resolver:
- This allows the usage of any field from the LTI login and membership services.
- The inspera_property_lti_login and inspera_property_membership custom parameters should be set to the corresponding field names.
Example:
- A user wants to use the custom field “cand_id” in login and “cand_id_memb” in membership (made up names). They should set the custom parameters as:
- candidate_id_resolver=BY_INSPERA_PROPERTY
- inspera_property_lti_login=cand_id
- inspera_property_membership=cand_id_memb
Distinction between LMS
arid_prefix
- If two or more LMS are configured to the same IA tenant, a prefix should be defined that is unique to this LMS. This should be configured at the tool configuration level. This prefix will be added as a prefix to test id to distinguish between tests created through different LMS.
- Should be set at the tool configuration level.
Debug
If the tool configuration is not working as intended, the debug mode can be turned on. This is done with the debugview custom parameter.
debugview
- If false, the communication between the LMS and IA works normally.
- If true, the debug mode is activated, meaning that the user is able to see the request that would have been made from the LMS to IA. With the debug mode on, the request doesn’t reach IA and thus will have no impact on IA.
Test Information
In the case of LMS that allow custom parameters to be defined at the test level, these are the ones that can be used. It’s possible to define some information regarding the IA test in the LMS via some custom parameters
inspera_test_start_time and inspera_test_end_time
- Define the start and end time of the test accordingly. They need to be a time stamp in ISO format (e.g., “2023-09-06T21:04+02:00” or “2023-09-06T19:04Z”).
- If they are not set, they will need to be set in IA before activating the test.
keep_test_title (this should always be set to true)
- If false, the name of the test in IA will be replaced with the one coming from the LMS
- If true, the name of the test in IA is not changed. This needs to be used in the case the LMS does not send the title at every launch (e.g., D2L)
- Should be set at the tool configuration level.
lti_candidate_extratime
- Sets the extra time in minutes for all candidates
- Default is 0
assessment_path_parent
- If true, the test in IA will be created as an Assessment Path
- If an id is sent, it needs to be the id of the Assessment Path test under which this test will be created, e.g., if the url for accessing the assessment path parent test is https://name.inspera.com/admin#deliver-test/97539878, then the id is 97539878
lti_test_template
- If false, the test created in IA is not based on a template
- If id, the id sent should be the id of the template on which the test should be based, e.g., if the url for accessing the template is https://name.inspera.com/admin#deliver-test/97539878, then the id is 97539878
use_template_on_create (this should always be set to true to prevent the teacher forgetting it when using templates)
- This only matters if the lti_test_template was used. However, defining it for other tests has no impact.
- If false, whenever the test is launched from the LMS, any changes will be overridden by the template values
- If true, the template values are only used when the test is created on the first launch.
- Should be set at the tool configuration level to avoid teachers forgetting it