| ℹ️ Information |
|---|
| This repository contains the connector and configuration code only. The implementer is responsible to acquire the connection details such as username, password, certificate, etc. You might even need to sign a contract or agreement with the supplier before implementing this connector. Please contact the client's application manager to coordinate the connector requirements. |
HelloID Provisioning Source Connector for Skyward Qmlativ Custom API
- Available Data
- Setting up the API Access
- Configure HelloID
- HelloID docs
Access to data is controlled by Skyward approval. Please refer to the Intergation Access XML for specifics to which table and fields are available. Also, it refers to what CRUD action are available as well.
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:
- Open the Main menu within Qmlativ.
- Select the Administrative Access portal.
- Choose the API module.
- Select the Integration feature.
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.
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.
In the Add Integration Access Workflow, you will need to set the following fields on the Integration:
- Name (required): This is a “friendly” name that allows the district to easily identify the Integration Access and allow the district to differentiate it from another Integration Access for the same Integration. It is often useful to name this with the Integration’s name plus the year or purpose of the access being granted, such as “{Integration} 2023” or “{Integration} Vendor Testing”. Note: this name does not affect the access credentials used to connect to the API(s).
- Description (optional): This description allows you to provide more details on the purpose of the Integration Access if the Name field does not provide enough context.
- Integration (required): When starting the Add Integration Access Workflow from the Integration Details screen, the Integration will be automatically set to the Integration which was selected at the start of the workflow. When starting the workflow from other locations, such as the Integration Access List screen, this field will need to be filled in with the name of the Integration to which you are granting access.
- Key (required): This key functions as the Client Key or “username” by the third-party vendor when authenticating with Qmlativ’s APIs. This value must be unique, and the third-party vendor may require that the value be configured to a specific value (see Vendor Integration Setup below).
- Authentication Type (required): The indicates the type(s) of authentication are available to the third-party vendor when authenticating with Qmlativ. Skyward recommends setting this option to “Any”, as this will allow the vendor to access the Integration using their preferred authentication type, and it will not require any changes to be made if other authentication types are added or removed in the future. a. NOTE: “Basic” is currently offered as an option for the authentication type, but this option will be removed at the start of the 2024-25 school year and is not recommended.
- Is Active (required): Indicates whether the Integration Access is active.
- Effective Date (required): The date from which the Integration Access becomes available to the third-party vendor.
- Expiration Date (optional): The date after which the Integration Access is no longer available to the third-party vendor. • NOTE: an Integration Access is only truly active if the “Is Active” checkbox is checked and if the current date falls after the Effective Date and before the Expiration Date. If no Expiration Date is provided, then the Integration Access will not expire, and will remain active as long as the “Is Active” box is checked, and the current date is after the Effective Date.
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.
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.
On the Add One Roster Configuration workflow, you will need to fill in several fields:
- One Roster Vendor (required): this is the name of the vendor as configured for the purposes of OneRoster communications. Click the arrow next to the selector to select the name of an existing vendor or click the Add One Roster Vendor button within the list to add a new vendor. The workflow for adding a new vendor contains a single field, which is the vendor’s name.
- Code (required): this is a generic code that can be used to identify the OneRoster configuration.
- Description (optional): this description allows you to provide additional context for the configuration, such as notes about a specific vendor or Integration.
- District (required): select your district from the list.
- Allow Grade Pass Back (optional): this option allows the third-party vendor’s Integration to write grade information back into Qmlativ. a. NOTE: Selecting this option requires additional licensing from Skyward for the grade pass back to function. If you are uncertain if your district has the appropriate licensing, you may look in Administrative Access > System > System Profile, then select the Products Owned tab and search for the “QM OneRoster API with writeback” product. If you do not have this products owned record available and would like to use the grade pass back option, please contact your Sales Representative.
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.
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.
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.
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.
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.
- Login to the HelloID Instance and open the provisioning interface
- Add Source System
- Search the catalog for Skyward and choose the appropriate Qmlativ connector (e.g. Students, Employees, Staff), then click “+ Create”
- Open the Source System, and go to the “Configuration” Tab
- Enter the necessary connection information
- Customer/tenant ID
- This is the URL to the instance, typically in this format
- https://.skyward.com/API
- Client ID
- Enter the Client Key from the Skyward integration Access Screen
- Client Key
- Enter the Client Secret from the Skyward Integration Access Screen
- Integration Key
- Please reach out to Tools4ever support (support@tools4ever.com) to obtain this key. This key is generated on a per customer basis for access to use the integration
- Entity ID
- Typically, this is going to be “1”. It is the ID of the District we’ll be connecting to for this instance. In cases where there are multiple districts under one instance, then a system per district is required.
- School Year ID
- This can remain blank and it will refer to the default active school year. Otherwise, you can specify a specific school year to target
- Fiscal Year ID
- This can remain blank and it will refer to the default active fiscal year. Otherwise, you can specify a specific fiscal year to target
- Customer/tenant ID
- Click Apply
- Go back to Systems Overview and click “Start Import”
The official HelloID documentation can be found at: https://docs.helloid.com/