NIM

Navigating to the Integration List

Every Integration will have a record available within Qmlativ, which you can view by navigating to the Integration List screen. To locate this list of Integrations:

Explanation of the integration list

On the Integration List screen, you will see a list of Integrations. By default, these Integrations are sorted by the Vendor Name (1) and then by the Product Name (2), which should make the Integrations easy to locate within the list. The Description (3) column provides an explanation of the purpose of the Integration, and should help you, as the district, determine if the Integration will be useful for your district. The Status (4) column shows the current state of the Integration, such as whether it is Available or if it has been Discontinued. A Discontinued Integration that appears for you is one that has either recently been discontinued from use or one that you have used in the past which is no longer available.

The Has Development Permissions (5) column provides an indication of whether the Integration is allowed to access your environment while it is in development by the vendor. In a Live environment, this should display as unchecked, however, in a Training environment, you may see this item checked if you are working with a vendor for development purposes.

The Can Generate Secret (6) column provides an indication as to whether you, as the district, are allowed to generate the secret that is used for the Integration’s authentication. If this box is checked, the vendor has enabled the option and expects that you will provide the secret to them using a secure method so they may authenticate with Qmlativ (see the Vendor Integration Setup below). If this option is unchecked, the vendor has chosen to manage secret authentication themselves using Skyward’s secure Partner Portal.

Starting integration access setup

From the Integration List screen, click the Open (1) button on the Integration for which you want to grant access, this will take you to the Integration Details screen.

On the Integration Details screen, select the Integration Accesses (1) tab, which will display a list of Integration Access records available for this Integration (note that no records will display when you first view this screen). Click the Add Integration Access (2) button to begin the Add Integration Access workflow

Add Integration Access Workflow

In the Add Integration Access Workflow, you will need to set the following fields on the Integration:

Additional Configuration

Beyond the above settings on the Add Integration Access workflow, there may be additional configuration necessary depending on the APIs used by the third-party Integration. If any additional configuration is necessary, a Configuration section will appear below the Expiration Date.

OneRoster Configuration

Description: the OneRoster API allows third-party Integrations access to rostering information, such as name and certain demographic information, as well as information related to scheduling and grading.

Click the arrow (1) next to the OneRoster Configuration selector, this will display a list of available OneRoster Configurations. Click the Select (2) button next to the appropriate configuration, if one is available, or click the Add One Roster Configuration (3) button to add a new configuration.

Adding a OneRoster Configuration

On the Add One Roster Configuration workflow, you will need to fill in several fields:

Custom API Configuration

Description: the Custom API allows third-party Integrations to potentially access any field within Qmlativ. However, the fields to which they have access are limited based on review by Skyward.

To see a list of the fields to which an Integration has access, you can navigate to Administration Access > API > Integration, open the specific Integration from the list, then click on the Integration APIs tab. On the Integration APIs tab, select the Custom API from the list, and a list of Integration Objects and Integration Fields will be displayed in the lists below.

Click the magnifying glass (1) next to the Custom API Entities selector, this will display a list of available Entities. Check the boxes (2) next to the Entities that you want the Integration to access when using the Custom API.

NOTE: in a single-district configuration, it is common to select all Entities from the list, so that the Integration may access information from the entire district. However, there may be situations where limiting access to specific Entities may be required, such as for certain licenses (for instance, if a high school uses an Integration, but the elementary school does not).

In a multi-district configuration, it is common to create a separate Integration Access for each district that is utilizing the Integration, and then limiting the Integration Access to the entities within that specific district. This will allow more granular control on a district-by-district basis.

Saving Integration Access

After filling in the main section of the Add Integration Access workflow (1) and any additional configuration (2), click the Save button to complete the first step of the workflow.

Completing the Add Integration Access Workflow

After saving the workflow, you will be presented with a window indicating that the process was completed successfully, which means the Integration Access record was created.

If the Integration allows you to generate a secret, you will have a Generate Secret (1) button displayed at the top along with the Close (2) button. If you are not allowed to generate the secret, you will only see the Close button. Click the Generate Secret (1) button to generate a secret for this Integration Access.

NOTE: the Generate Secret button will generally only be available to you if the third-party vendor offers a form of self-setup for the Integration or if the Integration is being used from a physical device that requires setup at the district (such as a time tracking device). This option is entirely dependent upon the third-party vendor’s Integration setup, and when available, should include instructions in the Vendor Integration Setup section below.

Starting the generate secret workflow

If you clicked the Generate Secret button above, you will automatically begin the Generate Secret Workflow. However, if you clicked the Close button instead, or you otherwise need to generate a new secret for an Integration, you can navigate to the Integration Accesses tab (1) on the Integration Details screen, as explained above, and look at the Can Generate Secret column (2) to see if you are allowed to generate a secret. If you can generate a secret, you can click the down arrow on the row (3) and click the Generate Secret button to start the workflow, and you can continue the workflow as outlined in the Completing the Add Integration Access step above.

Completing the workflow

After starting the Generate Secret Workflow, you will need to copy the Secret that is generated from the box on the screen. To make this easy, you can click the Copy (1) button. Once you have copied the information, you need to make sure the I Have Copied This Data (2) box has been checked (this will happen automatically when you click the Copy button), then click the Run Process (3) button to complete the process.