🚧

Preferred Method SCIM v2.0

SCIM v2.0 provides improved real-time user de/provisioning capabilities with improved field mapping experiences. Customers are strongly recommended to use SCIM v2.0 over General Profile Sources.

What is a General Profile Source?

There are two services available in Interact related to the synchronization of user data from external sources:

1. UMI Connector Service: uses pre-defined Connectors to query a specific source, such as Azure Active Directory, and creates import data in the form of a specially structured XML file.
2. UMI Processor Service: processes files of the aforementioned structure and imports the User information into Interact.

In some cases, Customers may not be able or may not want to use any of the pre-defined Connectors as a source for their User data. They are therefore able to define a General Profile Source which enables the Customer to provide their own XML file for import. Providing that the file is structured correctly, and delivered to the correct place in the infrastructure, the Umi Processor Service will handle the file and User data will be imported.

The General Profile Source facilitates this approach. Thus, data from external systems such as ADP, Okta, iTrent, Peoplesoft, or even an Excel spreadsheet can be assembled by the Customer into a valid XML file.

How does it work?

1. The Customer creates a General Profile Source in Interact to handle the process. This will generate an API endpoint that you will utilize in step 3.
2. The Customer develops an approach to generate an XML file containing the User data that conforms to the Schema. This could be their own application, a PowerShell script, or any other method that can create the XML file from their intended source.
3. The completed XML is then posted to the correct API endpoint. The XML data will then be processed by the Umi Processor Service.

General Profile Source Walkthrough

Step 1. Create a General Profile Source

To create a general profile source, log in to Interact as a Power User and navigate to Application Settings > Manage People > Manage Profile Sources > Other Source. If you don't have a Power User profile for the site yet, work with your organization's intranet administrator to set this up.

The new Source requires two fields:

1. Name
2. Authorisation Token

The Name should be a unique name for recognition of the Source. This will be referenced in the "domain" attribute of the syncoptions element in the incoming XML file.

The Authorisation Token will be used to verify incoming data files against the Source when the API is used.

📘

Note

If you are creating a General Profile Source as part of the Expertise and Interests guide, you can now return to that guide provided that you have saved your newly created profile source.

https://developer.interactsoftware.com/docs/expertise-and-interests

📘

Note

The sync options defined in the incoming file will take priority. If these are undefined, then the source can be customized via the Profile Options tab.

This can define the default Department, Location, and Company for incoming Users:

The drop-down lists will populate with data from the Interact instance.

The Source holds the definition of actions for handling Disabled and Missing users

The options are to Disable and Archive Users, or to only Disable Users, for either of the cases.

The Source details whether parts of the data are to be synchronized with the existing database or not.

Each checkbox setting governs whether the Processor will attempt to synchronize that type of data

Step 2. Generate User Profile Data

The UMI Processor Service can process any XML file, irrespective of the source, providing that the structure of the file adheres to the definition required. Refer to the following pages for more documentation on generating a valid file:

• The XSD Schema is a fully documented XML schema detailing the elements and attributes, required and optional, that are expected in a valid file containing User profiles.
• The Sample XML File file contains example User and Group data to help visualize how the file is expected to look by the Processor.
• The Guide to Generating an XML file from an Excel Spreadsheet provides a sample PowerShell script that can be customized to generate and upload/post a valid file from a standard Excel spreadsheet.

Step 3. Post the data to the API Endpoint

After creating the source in Interact, an API endpoint is available for posting the User Profile Data. This will be delivered to the appropriate Drop area within the Interact structure.

Endpoint Format: the endpoint has the format https://{{your_intranet_url}}/api/umi/N/upload where "N" is the unique Id of the Source (source/Ldap ID). The API Url Suffix is displayed when the Profile Source is saved to assist the construction of the API URL.

Example Script

An example script to transfer a file might look like the following:

$endpoint = "https://{{intranet_url}}/api/umi/{{source_id}}/upload"
$xmlPath = "C:\{{path_to_XML}}"
$authToken = "{{auth_token}}"

Invoke-RestMethod -Uri $endpoint -Method Post -InFile $xmlPath -ContentType "multipart/form-data" -Headers @{'X-ApiKey'= $authToken; }

curl --request POST "https://{{your_intranet_url}}/api/umi/{{source_id}}/upload" \ --header "X-ApiKey: {{your_profile_source_auth_token}}" \ --header "Content-Type: application/xml" \ --data-binary "@{{XML_filepath}}"

📘

Note

The value supplied to the X-ApiKey header is the value entered in the "Authorisation Token" field during the creation of the Profile Source in Step 1.

👍

Security Note

The API request uses HTTPS and therefore provides secure encryption during transport.

The API endpoint can be called however suits the Customer best, whether that is via a PowerShell script as in the example, or through another application. When the endpoint is hit, the XML file that is attached to the request is validated against the schema as it is transferred to the Drop area. A response will detail any issues found during this process.

Once the XML data has been delivered to the API Endpoint, it will be processed by the Umi Processor Service. The resulting Log file and the Archived data file will be accessible through the interface from the list of Profile Sources.