The Microsoft Active Directory Integration App allows administrators to facilitate logins through Microsoft Active Directory in Incident IQ. This also allows districts to automatically populate and update user data in iiQ based on information from your local active directory server. The following guide provides an in-depth overview of how to manage the Microsoft AD App in iiQ.
Warning: This document contains instructions for adjusting synchronization settings that can adversely affect your device data, user data, and/or user mapping settings in Incident IQ. As such, only qualified personnel should proceed with making adjustments to the settings outlined in this document.
If the entire text is not visible when mapping, just hover over it to view it completely.
Accessing the Microsoft AD App Management
Navigate to the Apps Management page and select Options on the Microsoft AD App.
This will take you to the Microsoft AD App management page, where you will be able to select the following tabs:
Overview tab where you can view basic user and group data, reset your authentication status or run a manual sync with your active directory.
User Mappings tab where you can update your filter settings and email translations.
Location Mappings tab where you can change the default location users will automatically map to if they do not have an existing mapping in the system.
Role Mappings tab where you can change the role users will automatically map to if they do not have an existing mapping in the system.
User History tab where you can look up individual users data coming in from Microsoft AD.
Sync Executable tab allows you to set up, update, and download your sync executable file.
Overview Tab
This tab summarizes your current users, groups, and changes made to users in Incident IQ during the last sync with Microsoft AD.
In the General Settings tab, you may enable the following settings:
Enable User Login: This allows users to log into Incident IQ through the Microsoft AD. If this option is disabled, then all accounts authenticated through Microsoft AD will be unable to log in.
Enable User Sync: This option allows Incident IQ to update user accounts with data provided by the iiQconnectors app. Without this option, the ability to run nightly or manual user syncs will become disabled.
Also, you can force a manual sync with your Active Directory by selecting Start New Sync. This import will only update user data based on the last data sent to Incident IQ through the connectors app. If you run a manual sync during the day, you will first want to manually run the connectors app to send over a new batch of user data.
User Mappings Tab
From here, you can change your email filter and translation information, as well as your user creation, updating, and deletion settings.
Under the Filter section, you can select to include or exclude users being imported based on their email address, username, OU fragment(s), and group(s). Please note that you can only filter by one email address.
Example Email Filter: If you set a filter for “@iiq.k12.ga.us” in the email section, Incident IQ will automatically ignore these email addresses containing this string during a sync.
Example OU Filter: Setting an OU Filter of “OU=Guests” will ensure that all users that belong to this particular OU will not import during a sync.
Please Note: We suggest running a sync without the “create user” option turned on first. The filter options are not counteractive.
Next is the Mapping section. Here, you control how fields are populated in Incident IQ.
Translate Username: This enables Incident IQ to translate the username pulled from Microsoft AD into a uniform format when storing in iiQ.
Translate Email: This enables Incident IQ to translate email addresses pulled from Microsoft AD into a uniform format when storing in iiQ. This is useful and often necessary when using Incident IQ in conjunction with programs such as Infinite Campus.
Example: Setting a translation to find “@k12.us.com” and replacing it with “@iiq.k12.ga.us” will ensure that all “@k12.us.com” addresses are updated and stored as “@iiq.k12.ga.us” in iiQ only. This will not change the addresses stored within Microsoft AD itself.
Phone Number Mapping: select if you want to import phone numbers and the mapping process.
Control how users are populated in iiQ under the Import Handling section.
Create User: When this box is checked, a new user will be created in Incident IQ for any new users found during the initial import from Microsoft AD and any new users found when a sync is run.
Update User: When enabled, a user will be updated in Incident IQ when any changes are found during a sync. This will update custom fields as well.
Update Custom Fields: When enabled, only update custom fields for users when any changes are found during a sync.
Set to ‘No Access’: When enabled, if a user is removed or disabled in Microsoft AD, change their role to no access in Incident IQ.
The "Set to 'No Access'" field will override any locked user fields, as it indicates that you prefer for disabled or deleted users in SSO to also be disabled in iiQ.
The Map custom values section allows you to select additional values you want imported and map them to default or custom fields in iiQ. This will enable you to pull custom data fields and view column options. Click on the Add button.
Next, fill out the following field mapping options:
Please note that there may be pre-configured mapping and can not be changed.
Select the custom value
Select the iiQ field the custom value should map to. You can map to the default field or map to a custom field.
If you map to a Custom Field, you will need to set a field name, select a field type (text, number, or date), and set whether the field information needs to be searchable through filters.
Please note that any custom field added here must also be set up in the sync executable so Incident IQ can pull this data field during a sync. Please refer to the Sync Executable tab for additional information on making changes to the connector executable.
Under the Additional Options section, you can customize the Login Button Text.
The Grace period for re-linking to the existing iiQ account section inhibits the continuous creation of duplicate user accounts in iiQ. The grace period indicates the number of days that should pass before iiQ creates a new user account if a user with the same name and email appears in the SSO. By default, the grace period is set to 365 days. This setting is read-only for customers and editable by iiQ Admin Employees.
The last section is Field Mappings. Controls which fields this app should update.
Team Mappings Tab
The Group-to-Team mapping feature allows you to map groups of users to Teams.
Groups can only be mapped to one Team per product.
When mapping groups to a team, a team is automatically created within Incident IQ. It is not possible to manually map groups to pre-existing teams.
Navigate the Teams Mappings tab. There are instructions on how to create new group-to-Teams mappings from steps 1-4, as well as some rules for syncing.
An initial sync must be run to bring over Groups before assigning Group-to-Teams mappings.
In the Search field, the Groups can be selected in the drop-down menu that contains all groups set up in the system (excluding nested groups). As you search for a group, any groups matching the string of characters you have typed in will be populated in the drop-down selector below (wildcard search; characters entered do not necessarily have to be the first characters included in the name of the group). A scrollable list will expose the first 25 groups matching the search query.
When you select a group, a new row is automatically added. The Team Name is filled in with the name of the Group from your SSO, but you can modify it if needed.
Next (if you have multiple iiQ products), select which product this team should be created.
Only one of the same group to team mapping per product. However, if needed, the same group can be mapped to a team for different products/modules.
Example: Group Admin can be mapped to one team in the Ticketing module and mapped to one team in the Facilities module.
The team's name must be unique and cannot be the same as an existing team. An error message will appear if a duplicate name is entered.
Upon creating a mapping and clicking Save. Next, go to the Overview tab and select either:
Download Data from Google SSO (if your district is going through many group membership changes, for example, at the beginning of the year).
Re-Run Last Sync if there have been no changes in group membership since the last sync.
After the sync, a new team will be created using the name saved in the mapping and group membership data from the most recent sync. Users who are members of that group will be added to the Team.
Back on the Team Mappings tab, the Status column will show ‘Team Created.’
You can change the team’s name after the sync if needed. To save it, you will go through the sync process again by clicking Save and then Re-Run Last Sync.
A mapped group can be deleted by selecting the Trash Can icon on the left and confirming the deletion in the pop-up window.
The Team will also be deleted if a mapped group is removed from the district's SSO solution (or is no longer detected during syncs).
This will result in Admins reviewing any Rules created for that Team that got deleted and ensuring the new Teams are added to those Rules.
Upon detection after sync, users who are no longer members of a group will be removed from any Teams mapped to that group.
If a product or module is deactivated from the site, you will no longer see Teams mapped to that product.
Teams in Incident IQ are useful for assigning permission policies to users. Once Teams are created through the district's SSO integration, Admins can allocate specific permissions to those Teams. If a user is manually removed/added to a Team on the Teams page in the Product, their permissions will be removed or added accordingly. Similarly, if a user is removed/added to the distribution group, they will automatically be removed/added to the Team upon the next sync from the integration.
Location Mappings Tab
This tab allows you to select or modify your current location mappings between Incident IQ and Microsoft AD. The default location acts as a fallback for user accounts that do not match your other custom location mappings. Please note that if no custom role mappings are set, all users brought into the system will default to this location.
You may use groups, OU fragments, location names, or any combination of the three when mapping to locations. The custom mappings section allows you to specify your user groups or OUs you wish to utilize for mapping users to their respective locations. Please note, when using OUs, you will want to structure them in the same format as the examples below:
OU=Cold Harbor
OU=Class of 2024
OU=CHMS
When mapping, if the full name is not visible, simply hover over the name to view the complete name.
Role Mappings Tab
This tab allows you to select or modify which user groups are assigned to which role in Incident IQ. The default location is a fallback for user accounts that do not match your other custom role mappings. Please note that if no custom role mappings are set, all users brought into the system will default to this role.
SSO integration cannot downgrade user roles but can only elevate them. For example, a user assigned an Agent role cannot be downgraded to a requestor role (staff, faculty, student, etc.).
When mapping to locations, you may use groups, OU fragments, role names, or any combination. The custom mappings section allows you to specify your user groups or OUs you wish to utilize for mapping users to their respective locations. Please note, when using OUs, you will want to structure them in the same format as the examples below:
OU=Staff and Faculty
OU=Students
OU=IT Staff
Department Mappings Tab
This tab allows you to select or modify how users are mapped to the different departments in Incident IQ. You can use groups, OU fragments, or both when mapping to departments. Also, you can add one or multiple user groups or OUs to each department using the Custom Mapping section.
Employment Mappings Tab
This tab allows you to select or modify how users are mapped to the employments in Incident IQ. You can use groups, OU fragments, or both when mapping to employments. Also, you can add one or multiple user groups or OUs to each employment using the Custom Mapping section.
Sync History Tab
This tab lets you view your sync history between Microsoft AD and Incident IQ. Every sync is logged for reference purposes, whether completed successfully or not. Clicking on View Details will display the number of users that have been added, updated, not changed, or set to no access during that sync. To the right, you can Download SSO Data.
Also, you can filter the sync data under the Details Status section. Select the status you want to filter by and enter the user’s name or email address. Clicking on the user’s link will take you to the user history tab.
User History Tab
This tab allows you to search for any user’s Microsoft AD information. This includes their Microsoft AD ID, email addresses, Group Membership, and sync history. This information is helpful in quickly determining if the user is affected by any email translations, establishing their group mappings, and identifying if syncing between the systems is being suppressed.
Sync Executable Tab
This tab allows you to configure your sync executable file used to access and send data to Incident IQ. Please note that if you make any changes to this page after the initial setup, you will need to redownload a new executable file and replace your old one for these changes to take effect during syncs.
At least one profile should be set up on this page with the following data provided:
AD Username
AD Password
AD Domain
AD Server IP
You may also set up specific OUs to search for during syncs, so the system only pulls user data from those. However, we recommend leaving the filters blank.
Also, you may pull in additional attributes through the executable during syncs if needed. Please note, if you have any custom fields mapped in the Users Mapping tab, you will need to ensure they are properly set up here.
---
Hannah Bailey - Director, Customer Engagement