FAQ content

LTI: Customize the Automagic matching settings & Library LTI Page

In this article

There are 3 major pieces when customizing the Automagic LTI tool:

  1. Customize the basic tool setting options for things like the tool name and use of LibGuides customizations.
  2. Configure the Automagic matching -- LTI parameter & LibGuides metadata matching, search type for matching content, and content display options.
  3. Customize the options of what will be displayed on the Library LTI Page.

This FAQ takes you through the second and third elements: content matching and customizing the Library LTI page -- both critical. For more on adjusting the tool settings, see this FAQ.


To adjust the matching and Library LTI Page options for an Automagic tool:

  1. Go to the LibApps Dashboard.
    • Log in using your LibApps login URL, or
    • Log into any of your Springshare products, click the blue menu on the left, and choose LibApps.
  2. Go to Admin > LTI Tool Builder.
    • LibApps Admins can access this area. If you are on the LibApps dashboard and do not see an Admin menu, you are not a LibApps Admin.
  3. Click the View/Edit Tool () icon for the Automagic tool you are using.
    • Note: the process for adjusting the setup options is the same for Version 1.0 and Version 1.3 tools.
modifying the setup options for an Automagic tool, part 1

Content matching: target system & field names

When editing an Automagic tool, the Automagic Matching tab will present you with options for setting the target system, selecting the LTI Parameter Name from your LMS, and entering the LibGuides Metadata Name. 

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!

Matching up how the LTI Parameter Name works with the LibGuides Metadata Name
Matching up how the LTI Parameter Name works with the LibGuides Metadata Name
Set 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

Select the parameter field name to use:

  1. From the LTI Parameter Name dropdown, select one of the standard parameters or select to input a Custom parameter.
    1. If you've chosen to enter a custom value, enter that in the Custom LTI Parameter Name field.
  2. Click Save.
selecting a the lti parameter field for your LMS
Set 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!

Selecting the LibGuides metadata field name:

  1. Enter the LibGuides Metadata Name that you've chosen to use.
  2. Click Save.
selecting a the LibGuides metadata name to use

Content matching: search type

There are two types of searches you can choose from for Automagic matching: Course Metadata Matching (aka 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.

selecting the Search type for Automagic matching

Course Metadata Matching

The Course Metadata Matching (formerly known as 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.

Please remember, this is a starts with search, not a contains. And we do not 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 via a regex for x characters for your LTI Automagic tool. The "regex" (or regular expression) will remove x number of characters at the beginning of the string. It needs to be a consistent number for this to work.

For example, let's say your course numbers look like 2018FA.HIS1000.01.JONES. You'd request a regex that removes 7 characters. Once that's in place, the LTI Automagic tool will initially search on HIS1000.01.JONES instead of 2018FA.HIS1000.01.JONES. If it doesn't find any matches, it'll remove the last character and run it again, so it will search on: HIS1000.01.JONE. It will continue in that way, removing a character from the end, until it either finds a match or exhausts the string (i.e., there are no matches).

If you're interested in setting up a regex for your site, please submit a ticket asking us to add a regex for x characters for your LTI Automagic tool.

Translation Table

The Translation Table 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. 

When using this option, the tool takes the LTI Parameter Name field value passed from the LMS 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.

You could potentially have the tool search on 3 completely different values to find various pieces of 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.

Once the tool finds all of the matches, it displays those matches based on the Content Display Behavior options you've selected.


Content display behavior

Like the options just above, these options can be changed at any time--before and/or after the Automagic tool is added to your LMS.

Understanding how the display behavior functions can take some time to fully comprehend. To that end, the  LTI Automagic: Content Matching Flowchart file attached will walk you through how it all works in flowchart form. You may want to download it or use it as a reference as you make your display behavior decisions.

Before we get into the Content Display Behavior options, it's good to have an understanding of the default display behavior. Once the tool has run the search (matching LMS value to LibGuides metadata), it sends all matches (or lack thereof) to the LMS. Default display is as follows:

Content Display Behavior options
  • If a single guide OR course match is found, that guide OR course loads.
  • If multiple guides and/or course matches are found (one of each; multiple of one/both), the Library LTI Page loads with all matches listed. If a subject match is also found, the Database link and Subject Expers areas are customized for that subject.
  • If neither guide nor course matches are found, the Library LTI Page loads with no guides or courses listed. (Only the Database link and any additional sections you opt to display in the Library LTI Page Builder section.)
  • If only a subject match is found, the Library LTI Page loads with the Database link and Subject Experts areas customized for that subject.

The options in the Content Display Behavior area allow you to change this default behavior however you'd like. Want to display a default guide if there are no matches? No problem! Always want to display the Library LTI Page, because you want people to have access to LibChat or booking rooms / appointments? You've got it! Want it all - a default guide and access to LibAnswers / LibCal widgets? You can have it all!

Options:

  • When a single matching Guide or Course is found
    • Choose to either force the Library LTI page to display, even if just a single match is found between all 3 content types, or to redirect to the matching guide/course.
  • Optional "default" Guide redirect when no matches are found
    • Displays the selected guide if there are no matches in any content area. If there is at least one match (guide, course, or subject), this guide will not display.
    • If you want this guide to also display on the Library LTI page when there are no guide matches, but there are course and/or subject matches, use the third option, in addition to this option.
  • Optional "default" Guide link when no matches are found
    • Allows you to display a specific guide link on the Library LTI page if there are no guide matches for that course. This is helpful when there is a course and/or subject match, but no guide match, or when there are no matches whatsoever, and you've selected the "always display the Library LTI page" option for the above option -- your users will always have a link to a guide.

No matter what display behaviors you select, your users will never be given an error message or an empty page. They'll either be taken to a guide of your choosing or shown the Library LTI Page.


Library LTI Page display

When the Automagic LTI Tool has been added to a course in your LMS, users may see the Library LTI Page when you've chosen to have it displayed instead of being redirected to guide/E-Reserves course or when there are multiple matches.

In addition to displaying links to matching guides and E-Reserves courses, the Library LTI Page can also include selected content from your LibGuides, LibAnswers, and/or LibCal systems. This provides students with easy access to your A-Z Database list, LibCal bookings & appointments, LibAnswers FAQs, and LibChat -- all embedded right within the LMS course.


Customize the content columns

The Library LTI Page is divided into two columns. By default, any matches to guides or courses will automatically appear at the top of the left-hand column. The rest of the items can be customized to display or not, as you wish. They will always appear in the order listed in the options (you cannot rearrange the content). If you do not have LibCal or LibAnswers, just leave those sections set to "Do not display".

‚ÄčTo customize the content columns, go to the Library LTI Page tab of the Automagic tool you're working on.

  1. Use the Left Column Content options to customize what content displays in the first column.
    1. LibGuides AZ List: When selected to display, this displays a link to your Databases A-Z page on your LibGuides site. If you're using the translation table and there's a subject associated with the course, it'll automatically narrow to that subject. The page opens within the LMS frame, so the student never leaves their course site!
    2. LibCal Room Booking Widget: If you have LibCal and are using the legacy Room Bookings module (instead of the new Spaces module), you can set a widget to display that allows students to book rooms (from a single group of rooms) right from their course site! Just select the group from the dropdown.
    3. LibCal Spaces Widget: If you have LibCal and are using the upgraded Spaces module (instead of Room Bookings), you can display a widget that allows students to book your spaces right from within their course page. Just select the space category from the dropdown menu.
      • NOTE: if you migrated from Room Bookings to Spaces, you will need to set the Room Bookings widget to "Do Not Display" and use the Spaces widget instead.
    4. LibCal Appointment Scheduler Widget: If you have LibCal, you can set a widget to display that allows students to book appointments with librarians right from their course site! Just select your LibCal site from the dropdown.
    5. LibAnswers Search Box: If you have LibAnswers, you can select a search box widget from your site to display at the bottom of the left column.
  2. Use the Right Column Content options to customize what content displays in the second column.
    1. LibCal Library Hours Widget: If you have LibCal, you can display the "Today's Hours" widget! Just select your site from the dropdown.
    2. LibChat Widget: If you have LibAnswers, you can choose a LibChat widget to display - students can chat with you right from their course site! Select the appropriate widget from the dropdown.
    3. Subject Librarians Listing: If you'd like, you can choose to show librarian profiles from your LibGuides site (the one selected in the Target LibGuides System field). Choose to not display any profiles, display profiles from the related subject area, or display all profiles.
Left Column Content and Right Column Content options

Preview, debug, & troubleshoot

Preview & debug the Automagic Library LTI Page

Previewing your Library LTI Page allows you to see how your LTI page will look in your LMS when using the Automagic tool. Not only will this show you how your content columns will appear, but it also allows you to test out specific metadata matches. For example, if you wanted to see if the right guides and subjects are being returned for a particular LTI parameter, you can enter it on the Preview page to see the results.

  1. On the Library LTI Page tab, click on the Preview Page button.
The Preview Page button in the Library LTI Page Builder
  1. To test a specific parameter, enter it in the LTI Parameter Value field and click the Test button.
    • The content on the page will update automatically, based upon your parameter matching, content display behavior, and content column settings.
    • If you are not seeing the content you're expecting, double-check your LTI Tool settings and guide/subject/course metadata.
Testing parameter matching on the Preview Page

Debug mode

Debug mode allows you to look under the hood of the Automagic tool. When enabled, a debug summary will show you how the LTI Parameter Value you're testing was applied. (Please note: when using debug mode, the preview page will not redirect you to matching guides/course pages.)

  • Tool info: this will show you the search term being used, which will be the LTI Parameter Value you entered.
    • If you previously requested to apply a regular expression (regex) to your LTI Parameter Values, an additional section will show you what the search terms look like after the regex has been applied.
  • Match info: this provides a summary of the matching guide, course, and/or subject metadata from your LibGuides content.
    • When using stepped searching for the automagic tool, you'll see the eventual matching value after the search term was reduced.
    • For example, if you searched for SMPL101-02 and the eventual matching metadata value was SMPL101, then you would see SMPL101 listed.
    • If there were no matching metadata in your LibGuides content, "[no match]" will appear instead.
    • If you had configured the LTI tool to redirect to a matching guide or course page, the Match Redirect URL will display the URL of that page (the actual redirect is disabled while using debug mode).
  • Translation Info: if you are using the translation table instead of stepped searching, this section will show you the guide_meta_value, course_meta_value, and subject_meta_value terms for the LTI parameter value you entered.
example of debug mode
Example output from Debug Mode

Troubleshooting

There are a few reasons guides (or subjects or courses) may not appear when using the LTI tool in your Learning Management / Courseware System (LMS) (e.g., Blackboard, Canvas, Brightspace / D2L, Moodle, Sakai, etc.). The debug mode for the Preview will help to identify potential issues between LibApps and your LMS talking to one another. However, there may be other things to check on as well -- some things that are fixable and some that are designed to work that way. 

Did you add the metadata? And is it the right metadata?

Hey, we all do stuff like this, right? You know you need to add it, you've added a bunch, but you missed one or two! This one is a simple fix: add the metadata and test it out.

You'll also want to check to ensure:

  • You added the right metadata "name" - double-check what you have in the LTI setup area and what you have in the guide itself. If the metadata "name" doesn't exactly match the name entered in your Automagic setup, the Automagic tool will ignore the field.
  • You added the right metadata "value" to match the course(s) in your LMS. If it doesn't match at least the beginning portion of the value from the LMS, the guide will not appear via the Automagic tool.
Guide Settings Which Cause Guides to NOT Appear via LTI:
  • Guide Status = Unpublished, Private
  • Guide Type = Internal, Template
  • Group = A group that has a type of Internal
E-Reserves Settings Which Cause Courses to NOT Appear via LTI:
  • The Term associated with the course has dates in the past or future.