The Library LTI Page has a lot of customization options available. Let's take a look through the Parameter Matching area, as this is a critical step to properly setting up your Automagic tool.
You must be a LibApps Admin to access this area.
You must be a LibApps Admin to get the configuration information for your system.
- Go to LibApps: Log into any Springshare app, click the blue menu > choose LibApps.
- Go to Admin > LTI Tool Builder > LTI Automagic tab.
- Click the heading for the Library LTI Page Builder section.
Target LibGuides System:
The Automagic tool can only be used with one LibGuides system at a time. For most customers, this isn't a problem, as they only have one LibGuides system. If you're in this camp, simply choose your system from the dropdown (it'll be the only one!) and you're done.
Others subscribe to multiple systems and have them all listed under one Customer Record, so they can easily move back and forth between the various systems using a single login and the blue LibApps menu. In these cases, you must choose which system you'll be using for Automagic, as (like the Highlander) there can be only one.
Putting the LTI Parameter Name and LibGuides Metadata Name Together
When the user clicks the Automagic LTI link in an LMS course site, the LMS sends LibApps a bunch of data about that course. The Automagic tool then finds the field name defined in the LTI Parameter Name and notes the value of that field sent from the LMS. In our example, it's the context_label field, so the tool would note the value (e.g., BUS150).
It then finds the field name defined in the LibGuides Metadata Name and heads off to LibGuides to find any guides, courses, or subjects that have metadata with that field name. If it finds any, it checks out the value of that field and sees if it matches the value sent from the LMS.
In our example below, the field names are: LTI - context_label; LibGuides - lti. On the left, you'll see some data listed in a table - that is a sample of data sent to the tool from Canvas. The context_label field has a value of BUS150. On the right, you'll see a sample of metadata from a guide in LibGuides. The lti field has a value of BUS150 as well, so that guide is sent back to the LMS as a match!
Setting the LTI Parameter Name
This is the field from your LMS (Blackboard, Canvas, D2L, Moodle, Sakai, etc.) that you want to match against. There are a standard set of LTI Parameters you can choose from or you can use a custom field. It's up to you! A couple that we know folks use, in order of frequency:
- context_label = yes, it says "label", but in LTI speak, this equates to the course number.
- context_title = course title
Adding the parameter field name:
- Click the text with blue dashed underline under the LTI Parameter Name heading.
- Enter the field name you want to match against (e.g., context_label).
- Click the blue checkmark to save.
Setting the LibGuides Metadata Name
This is the field in LibGuides that you want to match the LTI Parameter Name values against. Basically, it's the name of the metadata you want to associate with the Automagic LTI tool. Each guide, course, or subject you ultimately want to display in an LMS will have a piece of metadata with this as the name, and a value to match against.
Everyone must use the same name when adding metadata to LibGuides, so make sure everyone knows what it is and it's used consistently across your system. It's best to choose something easy to remember and easy to spell, to facilitate this. A spelling mistake means the field will be ignored - databases are quite literal! ;)
We tend to go with lti as our LibGuides Metadata Name in our own testing & examples - it's short, sweet, and to the point!
Adding the metadata field name:
- Click the text with blue dashed underline under the LibGuides Metadata Name heading.
- Enter the field name you want to match against (e.g., lti).
- Click the blue checkmark to save.
Parameter Matching: Search Type
There are two types of searches you can choose from for Automagic matching: Stepped and Translation Table.
The value coming from the LMS can sometimes be a very long string, which includes some data that is far more specific than most folks may want to get when adding metadata to LibGuides, like section or semester information. On the other hand, there may be a good reason you do want to pay attention to semester or section information. The two search options provide solutions for all.
The Stepped search takes the LTI Parameter Name field value from the LMS and runs a "starts with" search against all related LibGuides Metadata Name field values in guides, E-Reserves courses, and subjects.
- If it finds one or more matches for a particular content type, it stops searching that content type and continues on with the others.
- Once it's done searching that full string, it checks to see if there are matches in all areas. If there is, it stops searching. If not, it removes a character from the end of the string and runs the search again, skipping any content type that already has at least one match.
- It continues to do this until either each content type has at least one match OR the string is exhausted.
Again, this is a starts with search, not a contains, nor do we allow for wildcard searches. If you have semester data at the beginning of the string, you can still use the Automagic tool! So long as it's a standard number of characters for each course / semester / whatever is at the beginning, we can remove those characters prior to running the search.
The Translation Table search is a bit of a different animal and requires you to upload a CSV file defining the values to be searched. The template has 4 columns: LTI Parameter Value, Guide, Course, and Subject Values. It still uses the LTI Parameter Name and LibGuides Metadata Name fields to know what values to match on, but that's where the similarity to the Stepped search ends.
The Translation Table takes the LTI Parameter Name field value and searches for that in the first column of data in the Translation Table. Once it finds it, it looks at the Guide value and searches for that value only in Guide metadata. Then it does the same for the Course and Subject values, searching E-Reserves Course metadata and Subject metadata, respectively. So in this case, you could potentially have the tool search on 3 completely different values to find content in your LibGuides system.
This is especially useful if your course numbers are set up in a particularly complex way, if you're using a non-standard (or custom) field from your LMS for matching, or if you have very broad subject guides and very specific E-Reserves course information.