In this article, we'll go over the steps for setting up an Integrations Hub Pushabck with iMIS EMS.
*** Not sure if you have EMS or iMIS Web Service? Here's an easy way to check:
Within your iMIS account, navigate to:
Settings > About iMIS > iMIS version
Version 20.3 or later = EMS
Version 20.2 or earlier = Web Service
Here is a screenshot of what this settings area will look like or similar to:
Basic Setup within Integrations Hub
1. Get Started with Integrations Hub.
2. Add a new Lookup connector from the Integrations Hub dashboard.
3. You will be brought to a page with different Lookup options. Select iMIS OAuth.
4. Keep this screen open in your browser. We'll be jumping over to your iMIS account to adjust some settings but we'll need to return to this page once we're done.
iMIS Side Settings
5. In a new browser tab, go to your iMIS organization account URL: https://{instanceurl}/staff
Example:
My organization is called King of The Hill and my website is KingoftheHill.com. This means my iMIS account login link should be: https://KingoftheHill.com/staff
6. Request admin login credentials from your staff if you don't have them already (it's important that these credentials are admin, other account types will not have access to what we need). Once you have the proper credentials, login to iMIS with these credentials on the above page.
7. Now we're going to begin adjusting some settings in order to configure looking up data from an IQA and prefilling a form.
8. Looking back to your iMIS dashboard items located on the far left of your screen, click Rise > Intelligent Query Architect. Once this page loads, click "New" (located at the top), and select "Folder".
9. Write "OpenWater" as the folder name and then click "Save".
10. Save this gist then import it into the OpenWater folder. Do this by selecting the folder OpenWater, and click Import at the top of your screen. A new popup will appear with a file importer. Select the gist we had you save, and click "Upload".
11. Ensure you update the destination with the new folder, and click "Import".
12. Now open the IQA we created and test it.
You should be able to see some sample data under the tab "Run".
What we care most about is the first name, last name, and email. If these are present, your initial test has passed- the IQA is populating test data.
13. On the Define tab, you can get the IQA path. You will need this in the next step so copy/paste this into a notepad for future use in these instructions.
Additionally, you'll need to navigate to the "Security" tab. From here, you'll see a checkbox that says "Available via the REST API." That needs to be enabled for Integrations Hub to be able to find this IQA.
Back to Integrations Hub
14. Head back to your Integrations Hub tab that you left open in your browser in Step 5. We will now be adding your settings and credentials here.
Give your Lookup a name ( I suggest something like [Program Name] Lookup [Year])
Then paste in the IQA from Step 14
Add the following credentials from iMIS
Credentials Name- I suggest the same name you gave your lookup: [Program Name] Lookup [Year]
Service Base URL- https://{imisInstanceUrl}
Client ID
Client Secret- Here is a random secret generator we can suggest
Admin User Name
Admin Password
15. Here is an example of my newly created credential. If I did it correctly, once I press save the integrations hub will populate the available fields.
16. You can now set the Label and Value. The Label is what will show to the end user searching, the Value is the ID or Key that will be used for the Pre-fill.
Note: Currently auto-complete and pre-fill use the same IQA, however in a future version we will support multiple IQAs.
17. Set the autocomplete settings to the below values, Save, then Test.
Label: {FirtName} {LastName}
Value: ID
18. To the right of the Save button, click Test. The test feature will help you search the pre-fill to see how it will look in OpenWater:
19. Now head to the pre-fill tab. Paste in the same IQA from the Autocomplete tab. Then press Save. (Note: for advanced cases you may wish to use one query to provide data for autocomplete, and another to pull more extensive pre-fill information from).
20. The prefill tab matches search result data into OpenWater field aliases. Click Add Prefill item twice, then add a field.
21. You should now see the below:
22. We are going to map on successful auto-complete for the pre-filling of a regular text field, along with a table.
The first field will have the table section as blank, and the field set as
Alias: resultValue, Value Field: ID
The next field's label will be "resultTable" with the following:
Alias: email, Value Field: Email
Alias: firstName, Value Field: First Name
Alias: lastName, Value Field: Last Name
Not sure what an Alias is or how to find them? Read this article.
23. Press Save, and Test. You can now see the data in the test harness:
24. Now let's copy the Autocomplete URL from the Autocomplete tab and the Prefill URL and head back to OpenWater:
Finishing Up in OpenWater
25. We're going to create a program for where our Lookup will be used, a form for our program (that has the field where we want to use for looking up information from iMIS), then, a few test submissions. If you already have these items in place, feel free to skip to the next section: X
26. As an OpenWater admin you can login to your organization's instance here:
https://{InstanceName}.secure-platform.com/admin
27. Follow the prompt to login then you'll be brought to your dashboard that will look similar to this:
28. We're now going to add a program. Go to Programs in your Dashboard list the click the "Add Program" button towards the top of the page.
29. Using the search function on the top right of this page, search for and install the Integrations Hub sample program:
30. You should now be taken directly into your sample program. From here, navigate to your submission form by selecting Round Settings > Submission Form from the top navigation on your screen. Once in the form editor, you can edit the sample Lookup page by clicking "Select":
31. Once in the form, click on Search Here, then we'll set the "Autocomplete" and "Set Field Values" URLs.
The "Autocomplete" URL will be the autocomplete URL we copied.
The "Set Values" URL will be the prefill URL we copied.
32. Save your form. If you are prompted to add open/ close dates for the program, feel free to add them.
Testing Your New Lookup
33. Last, create a test submission in your new submission form to see if the Lookup is working as intended:
Get your program's direct link, it will take you to the submission form you built to fill out a test submission.
For your test form, fill in whatever test data you'd like i.e. John Doe, Test Company, etc. and try adding a name to your Lookup's "Search Here" field.
If working properly, you should see the names appear for selection in the Search Here field.
Once you select a name, basic user information should prefill in the form.