Overview
Before starting, we recommend reading the Introduction to Custom Integration article
Kindly remember that custom integrations:
- Support syncing users, licenses, roles, and last used dates
- Cannot sync expenses, even if the integrated app contains expense data
- Work best for onboarding/offboarding/license optimization scenarios
To build your own integration and push user and license data into Torii you will need to follow the below 4 steps process.
Note, a developer is required to perform steps 3 & 4
IT - Setup/ Preparation
Developer - Use the API, upload and sync users
STEP 1 - Get Torii API Key
Prerequisite - Torii admin permission is required
- Go to Settings >> API Access
- Click on Generate API key
- In Generate API Key make sure you select the Full access option
- Copy and save! The API Key - You cannot repeat this action again!
-
Click Got it
STEP 2 - Create new Custom Integration
- Go to the Integrations page,
- Scroll down and click the ADD CUSTOM INTEGRATION tile
- Find the App you want to integrate
- Click Add integration
- Copy the App account ID and paste "in a safe place"
-
Close the window
STEP 3 - Upload the users file to Torii
Prerequisites - Generate a users file named ‘users_file.json’ in the working folder and the file comply with the "File schema"
Click here for Torii's full API documentation
3 parts to the upload
- Part 1 - Create a one-time URL upload link
- Part 2 - Upload the file to S3
- Part 3 - Update Torii with the upload information
Part 1 - Create a one-time URL upload link
-
Run the following command
curl -H "Authorization: Bearer API_KEY" https://api.toriihq.com/v1.0/files/url?name=FILE_NAME&type=customIntegrationData
-
Replace the API_KEY, and the S3_FILE_PATH with the filePath parameter, for example
You should get :
- URL - Required for step 2
- File path - Required for step 3
Note
- These parameters are embedded in the upload file parameters; consider it when
writing the code.
- The upload URL is valid for a short period of time, so make sure to upload the code
right after step 1
Part 2 - Upload the file to S3
-
Run the following command
curl -H "Content-Type: customIntegrationData" --data-binary @'LOCAL_FILE_PATH_AND_NAME' -X PUT S3_URL
-
Replace the LOCAL_FILE_PATH_AND_NAME with the file location and the S3_URL with the URL we got in the previous step
The result should look like the example below
Part 3 - Update Torii with the upload information
-
Run the following command
curl -d '{"path":"S3_FILE_PATH","type":"customIntegrationData"}' -H "Authorization: Bearer API_KEY" -H "Content-Type: application/json" https://api.toriihq.com/v1.0/files
-
Replace the API_KEY, and the S3_FILE_PATH with the filePath parameter we received in the first step; see the below example
The command result should be Torii upload ID like the below example
-
Save the id value for step 4
STEP 4 - Sync the uploaded file to Torii
-
Run the following command
curl -X PUT -d '{"idFile":"FILE_ID", "idAppAccount": "APP_ACCOUNT_ID"}' -H "Authorization: Bearer API_KEY" -H "Content-Type: application/json" https://api.toriihq.com/v1.0/services/sync/custom
-
Replace the API_KEY, FILE_ID from the previous step (Upload ID)
-
Replace the APP_ACCOUNT_ID you received from Torii in STEP 2 (add custom integration) like in the below example:
The command result should be a success like the below example
Error Message: Note, In case of an error, a relevant message like "Illegal file structure, Wrong file id, Wrong account", etc. will be displayed.
Last Notes:
- The syncs are NOT incremental, meaning that on each sync you must provide all the users you currently have in the systems (and not only new ones for example)
- It may take some time for the sync to complete.
To confirm a successful sync, Go to Integration window (1) and make sure the hourglass (2) disappeared and a green checkmark (3) is displayed.
Read our API documentation to find out more about Torii API capabilities.
Q & A
Q: Can I sync absolutely any app with Torii?
A: Yes. Torii can get data from any app.
You need to send it to the Torii API JSON file which is structured according to the Torii file schema.
Q: How often will data be pushed into Torii & Does Torii support date synchronization with custom integrations?
A: You can decide how often you want to push the data into Torii.
Some Admins push it every 5 minutes, and others do it once a day. We recommend pushing the data regularly, so it stays up to date.
When data has not been synced for more than 10 days, we show an alert in the UI.
Q: Can I perform workflow actions for a custom app?
A: Yes, through custom action configuration
Q: What happens when disconnecting custom integration?
A: App account ID is revoked, and no more syncs are possible.
Users can reconnect the same account later.
The data is never deleted, similar to native integrations
Q: How do I delete and update users?
A: Each time a new file is pushed, the old data is overwritten.
If users were removed from the file - they would be removed from the app in Torii.
If user attributes were updated in the file - they will be updated in Torii.
File schema
The file should include the following information. Note that fields must have the exact field name as shown in the following table:
Field Name |
Description |
Type |
Required |
users |
Users using the application |
User[] (see user object below) |
Yes |
licenses |
Licenses used in your org |
License[] (see license object below) |
No |
User
Field Name |
Description |
Type & Options |
Required |
Id |
Unique identifier of a user in the application |
String |
No |
|
Unique email |
String |
Yes |
firstName |
First name |
String |
No |
lastName |
Last name |
String |
No |
status |
The status of the user in Torii. Only active users are displayed as users of the application |
Enum (active/deleted) Default: active |
No |
externalStatus |
The status of the user as it appears on the application’s site |
String |
No |
roles |
Roles |
String[] |
No |
lastUsedDate |
Last date user used the application |
Date ISO 8601 (YYYY-MM-DD) |
No |
License
Field Name |
Description |
Type & Options |
Required |
name |
Unique name |
String |
Yes |
unassignedAmount |
Number of licenses that are not assigned to users |
Number |
No |
users |
Users under this license |
licenseUser[] (see licenseUser object below) |
No |
pricePerUser |
How much does it cost per user |
Number |
No |
License User
Field Name |
Description |
Type & Options |
Required |
|
User's email |
String |
Yes |
licenseStatus |
License status. If not provided, will be defined by user status |
Enum (active/inactive/deleted) |
No |
lastUsedDate |
Last date user used the license |
Date ISO 8601 (YYYY-MM-DD) |
No |