Before Setting Up Your API or LTI

This article will help you begin the process of setting up your LTI/LMS.

This article will discuss the following:

1. Whitelist your LMS Instance
2. Generate the API Key
3. Read+Write Keys vs. Read-Only Keys
   
4. How Courses are Mapped 
5. If Courses Cannot Be Mapped

⚠️ Remember to Whitelist Your LMS Instance ⚠️

Email support@givepulse.com to request that your LMS Instance URL be whitelisted before proceeding. Failing to do so may result in errors when integrating with GivePulse.

How to Generate the API Key+Secret

Get the LTI Key and LTI Secret for your GivePulse group. This is found under More Tools > API within the group dashboard.

Please note: If you have your own subdomain (e.g. jcu.givepulse.com), you should use your subdomain URL in place of www.givepulse.com. If you would like to test the integration, you can do so by using dev.givepulse.com or subdomain-dev.givepulse.com (jcu-dev.givepulse.com) in place of www.givepulse.com. If you need help accessing your dev site, please reach out to support@givepulse.com.

Once there, generate the key by adding a label, selecting Read+Write or Read-Only privileges (please see the next section to learn more about the difference between Read+Write and Read-Only keys) and finally clicking the blue button to generate consumer values:

Consider Read-Only Keys or Read+Write Keys

Read-Only keys will be used to only read data from GivePulse.

Read + Write keys will be used to write data to GivePulse if necessary (ex: If the GivePulse LTI app is unable to map the LMS course to a course on GivePulse, a new course will be created on GivePulse).  

When to use Read Only: If you are mapping an existing course on GivePulse to an existing course on the LMS, we recommend using Read-Only Keys.

When to use Read+Write: If you are trying to create a new course that does not exist on GivePulse and is not being synced via API or SFTP sync, you can use Read + Write keys.

How Courses are Mapped 

This function can be used to help map 1.0, 1.1, and LTI 1.3.

We need the following attributes to map courses between the LMS and GivePulse and keep students authenticated on both platforms.

User Attributes Needed

• lis_person_contact_email_primary - User e-mail address. Only provided if the privacy level is set to Public or EmailOnly
• lis_person_name_family - User family name. Only provided if the privacy level is set to Public or NameOnly
• lis_person_name_full - User full name. Only provided if the privacy level is set to Public or NameOnly
• lis_person_name_given - User given name. Only provided if the privacy level is set to Public or NameOnly
• lis_person_sourcedid - User identity, either person sync key (used across system integrations) or user id of Platform user entity id.
• user_id - Platform user entity id (not sync key in any case) Note: This is the platform user id and not the itslearning person id.
• roles - Comma-separated list with institution roles and context roles of the user. Full URN is always provided.

Course Attributes Needed

• custom_canvas_course_id=TERM_CRN    OR
• contex_label=TERM.CRN OR
• You can use any other attributes and format but we need to be informed.

If Courses Cannot Be Mapped

If the GivePulse LTI app is unable to map a course using the given info, and Read + Write keys are used for integration, it will create a new course on GivePulse with provided info in the request. If Read-Only keys are used, it will redirect to the Explore page and will not create a new course.