Overview: Atomic Search 1.3 Installation - Canvas

1. Atomic Search User

1. First, confirm that the customer has created the Atomic Search service user in their LMS to be used for the installation. If they haven’t, have them create that now or reschedule the call for when they’re able to do so.

2. Uninstall any old installs of Atomic Search

If the customer has installed Atomic Search as part of an evaluation, you should remove the installs, or the Search menu will appear multiple times.

1. Go to the Canvas account or course where you installed Atomic Search.
2. Go to Settings.
3. Click on the Apps tab and click the View App Configurations button.
4. Click on the gear menu next to Atomic Search and choose Delete.

3. Create the Atomic Search service user role

1. Log in as a root-level Canvas admin
2. Create a new Canvas Account level role for Atomic Search under the Permissions section.
3. Limit the permissions of the Atomic Search role as described in the table below:

#	Permission	Why it is needed:
1	Announcements - view	Retrieve announcement content for indexing.
2	Course Content - view	Retrieve course content for indexing.
3	Courses - view list	List the courses in an account for indexing.
4	Discussions - view	Retrieve the name and description of discussions for indexing.
5	Assignments and Quizzes - edit	Find out if assignments and quizzes are published or unpublished.
6	Manage LTI	Install the Atomic Search external application into a course or sub-account. This permission can be removed after Atomic Search is installed (it’s sometimes a concern for customers).
7	Question banks - view and link	Retrieve quiz and question content for indexing.
8	Users - view list	Find out what courses a user is enrolled in and what their role is in those courses. Atomic Search uses this information to limit what the user can search.

1. Add the new service user as an admin and assign them the new Atomic Search user role that you created in Step 2.

1. Browse to the root account of your instance of Canvas.
2. Click on Settings and then the Admins tab.
   1. 
3. Scroll to the bottom and click on +Account Admins.
4. Select the new Atomic Search user role from the Add More drop-down list.
5. Add the Atomic Search user email or SIS ID in the text box and click Continue…, confirm that the user is found and shows correctly, and then select OK Looks Good, Add This 1 User.

5. Ensure the Atomic Jolt Application Application Installer developer key is enabled

To complete the Search installation, the Atomic Jolt Application Installer developer key must be enabled:

1. Browse to the root/sub-account level. Select Developer Keys in the left-hand Canvas navigation menu.
2. Click on the Inherited tab near the top.
3. Scroll to the bottom of the page and click Show All Keys.
4. Scroll down until you see the Atomic Jolt Application Installer developer key.
5. If the key is not On, select On.

If the customer wants to used a scoped developer key, complete the setup using these instructions. Add the key and secret from the key into the customer’s site in the admin panel.

6. Create a new Developer LTI Key for Atomic Search

To install, you must create a new LTI Key under the Developer key section.

1. Go to the Developer Keys menu and navigate to the Account tab.
2. Click on + Developer Key button and choose + LTI Key.
3. Name the key: “Atomic Search”.
4. Owner Email: Add your email address (or the email of the search service user).
5. Select the Method: Enter URL
   1. Paste the URL for the version you are installing:
      1. US Prod - https://search.atomicjoltapps.com/lti_config.json
      2. IE Prod - https://search.atomicjoltappsie.com/lti_config.json
      3. AUS Prod - https://search.atomicjoltappsau.com/lti_config.json
6. Save the Key and turn the key on (beneath State).
7. Copy the Client ID (from the Details column) to use in the admin panel later and to do the install in Canvas.

7. Start indexing Atomic Search using the welcome app

To start indexing your content to use with Atomic Search using OAuth:

1. Log out of Canvas with your Admin user and open a private browser. Log in to Canvas as the Atomic Search user. You may need to workaround an SSO by using this URL: http://[institution].instructure.com/login/canvas.
2. Go to the install page for your region:

US/Canada/Central and South America	https://search.atomicjoltapps.com/account_install
Asia, Australia, Pacific Islands	https://search.atomicjoltappsau.com/account_install
Europe, Africa	https://search.atomicjoltappsie.com/account_install

1. Enter your Canvas domain and click the Authorize button.
   1. If you use a vanity domain (e.g., something other than schoolname.instructure.com), use that domain during installation.
2. It will ask you to authorize the Atomic Jolt Application Installer to talk to your instance of Canvas on your behalf. Verify that it is authorizing as the Atomic Search user.
3. You will next see a list of the accounts and courses you have access to.
   1. The installation does not list courses that you are not an instructor in.
4. Click on the Index button only next to the account you want to use Atomic Search in to kick off indexing of your Canvas content.
   1. Atomic Jolt will reach out to let you know when indexing has been completed.

8. Configure the app instance and add the Client ID to the admin panel

1. Login to the Atomic Jolt admin panel in the customer install region.

US/Canada/Central and South America	https://actadmin.atomicjoltapps.com/users/sign_in
Asia, Australia, Pacific Islands	https://actadmin.atomicjoltappsau.com/users/sign_in
Europe, Africa	https://actadmin.atomicjoltappsie.com/users/sign_in

1. Navigate to the new customer app instance under the Eval tab.
2. Fill out the details for the customer and primary contact, and mark the account as paid.
3. Go to the LTI Advantage tab.
4. Under the Pinned Client Id section, click on Add new Client Id, and paste in the client ID that was generated in Step 3.7. Select the ISS as: canvas.instructure.com in the dropdown.
5. Save.

9. Install Atomic Search by Client ID

1. Browse to the Canvas account in which Search will be installed and select: Settings > Apps > View App Configuration.
2. Select +App. Select ‘Configuration Type’ = By Client ID.
3. Enter the Client ID that the customer provided after creating the new Developer LTI Key in Step 6.

10. Add the Search widget global javascript to your Canvas theme

You can add a search box to the top right of every screen in Canvas by adding the Atomic Search global javascript to your Canvas theme:

1. Download or copy this script to a file on your hard drive. 
2. Upload the script to your Canvas theme.
   WARNING: If you already have a global javascript, you should combine your old script with the Atomic Search script before you upload it.
   1. Log in as a Canvas account Admin.
   2. Go to the account where you installed Atomic Search (the root account or a sub-account).
   3. Click on Themes.
   4. Click on the Current theme to open it in the theme editor.
   5. Click on the Upload tab at the top left of the screen.
   6. Under JavaScript file:
      1. If a file is listed, view it and copy it into the top of the Atomic Search script you downloaded, and save it.
      2. Click Select and find the Atomic Search script.
   7. Click Preview Your Changes.
   8. Click Save theme.
      1. If it is the first time you have changed the theme, you may need to specify a new name for the theme.
   9. Click Apply Theme.
3. Verify that you didn’t break things.
   1. Log in to Canvas in a different browser or a private/incognito browser window.
   2. Make sure everything looks ok.
   3. Navigate to a course page and make sure the Search widget shows up.
   4. If you broke things, navigate to the themes page in your original browser and remove the global javascript or apply a different theme.

Common Search widget javascript problems are:

1. Putting the Atomic Search global javascript in the middle of other global javascript.
2. Existing global javascript has errors that prevent the Atomic Search global javascript from running.

You can inspect the browser javascript console to look for these errors.

9. Configure Canvas Live Events to send events to Atomic Search

When Canvas Live Events are configured to send events to Atomic Search it notifies Atomic Search when content is added or updated in your courses. When Atomic Search receives those notifications it begins updating the index for that content and usually finishes updating it within a few seconds. This applies to both active and inactive courses. This can help keep the index current. 

1. Check to see if they have Canvas Data Services installed by looking for it in the Canvas lefthand navigation menu, listed as ‘Data Services’. If they do, proceed to ‘Configure Canvas Live Events for Atomic Search’. If not, follow the directions beneath ‘Install Canvas Data Services’.

Install Canvas Data Services:

1. Browse to the root account and select Developer Keys in the lefthand Canvas navigation menu.
2. Open Inherited Tab. Scroll to the bottom and select ‘Show all keys’. Search for “Canvas Data Services” on the page. 
3. Turn on the key beneath ‘State’. Copy the Client  ID below ‘Details’.
4. Browse to the account in which Search will be installed and select: Settings > Apps > View App Configuration.
5. Select +App. Select ‘Configuration Type’ = By Client ID.
6. Enter the Canvas Data Services Client ID that you copied from the Developer Keys.

Configure Canvas Live Events for Atomic Search

• Install the Canvas Data Services LTI using these instructions from Canvas.
• In Canvas, browse to the root account. Select Data Services in the left-hand Canvas navigation menu.
• Select the +Add button to create a new Data Stream. 
• Name: "Atomic Search".
• Delivery Method: SQS.
• URL: Select and enter the SQS URL corresponding to the Atomic Search region nearest to you:
  • US / Canada / Central & South America
    https://sqs.us-east-1.amazonaws.com/318936073860/canvas-live-events-AJ-ACT
  • Europe / Africa
    https://sqs.eu-west-1.amazonaws.com/318936073860/canvas-live-events-AJ-ACT
  • Australia / Asia
    https://sqs.ap-southeast-2.amazonaws.com/318936073860/canvas-live-events-AJ-ACT
• Authentication: None
• Message Type: Canvas
• Application Type: Data Streaming
• Select the following Events:
  • Assignment:
    • assignment_created
    • assignment_updated
  • Attachment
    • attachment_created
    • attachment_deleted
    • attachment_updated
  • Course (not all)
  • course_created
  • course_updated
  • Discussion Topic
  • discussion_topic_created
  • Discussion_topic_updated
• Modules (select all)
• Module Items (select all)
• • Syllabus
  • syllabus_updated
  • Wiki Page
  • wiki_page_created
  • wiki_page_deleted
  • wiki_page_updated
• Select Save & Exit

Once you have enabled the Live Events, you can verify that it is enabled by editing a page to add unique text to it and then searching your course for that text.

---

This is a rare circumstance, but:

1. If you have chosen not to install with the global navigation menu placement, you must hard code the tool ID in the global Javascript at the top of the script you downloaded. 
   1. var atomicSearchConfig = {
   2.   accountId: 1, // The ID of your root account (usually 1)
   3.   externalToolId: 9018, // The ID of your installation of Atomic Search
   4. };
   6. var atomicSearchWidgetScript = document.createElement("script");
   7. atomicSearchWidgetScript.src = "https://d2u53n8918fnto.cloudfront.net/atomic_search_widget.js" + "?ts=" + new Date().getTime();
   8. document.getElementsByTagName("head")[0].appendChild(atomicSearchWidgetScript);
   10. NOTE: The atomicSearchConfig var must be defined BEFORE the main Atomic Search script.
   11. To find the accountId and external tool ID in the script, navigate to the root account and choose the Search menu. The IDs will be in the URL. For example:

https://atomicjolt.instructure.com/accounts/1/external_tools/9018