Connectors - Scripted API
Scripted API connectors are ICF connectors based on a proprietary connector called Scripted API. The Scripted API connector is a generic connector that provides utility functions that can be used in Groovy scripts to create specific ICF connectors. These connectors can be easily customized to meet the business needs of each organization. This can be done through a built-in graphical interface in RAC/M Identity.
Prerequisites
- RAC/M Identity 3.17 or newer
- A data repository accessible via an API (e.g., Workday)
Script Creation
This step involves creating a Groovy script that will be used by the Scripted API connector.
- In the menu bar, click CONFIGURATION > Script Files.
- Click on the script name corresponding to the desired connector, starting with "reference-scripts/scripted-api-". This will open the script. For example, to create a connector for Workday, select the script reference-scripts/scripted-api-1.0.0.1/workday.groovy. Choose the latest version available. If the connector does not already exist, you can create one based on the reference scripts.
- Click the Duplicate button in the bottom right corner of the screen to create a copy of the script. This will keep the reference script intact.
- In the window that appears, give the script an appropriate name and click Duplicate.
- (If needed) Modify it to meet your specific requirements. Make sure to regularly save your changes to avoid losing them.
- Click Save to save the script.
Connector Creation
This step involves creating a Scripted API connector that will use the script created earlier. First, follow the steps for creating a connector in the ICF Connector Configuration. Select Scripted API as the connector type. Use the same version as the one used for the script.
Connector Configuration
The following parameters are available for configuring the Scripted API connector.
Only fields marked with an asterisk are mandatory. However, some parameters may be required by your specific connector. Please refer to its documentation for more details.
| Configuration | Description |
|---|---|
| Script Path | Path to the Groovy script created earlier. |
| API URL | The URL of the API to connect to. |
| Timeout | Timeout in milliseconds. |
| Preferred Authentication Method | Authentication method to use ("password", "bearer", "userToken", or "oauth2"). |
| Authentication URL | The URL used for authentication. |
| Custom Config 1 to 5 | Custom configurations that can be used by the script/. |
| Username | The username to use for authentication. |
| Password | The password to use for authentication. |
| User Token | The user token to use for authentication. |
| Bearer Token | The bearer token to use for authentication. |
| Custom Secret 1 à 5 | Customized secrets that can be used by the script, encrypted and handled securely. |
| Thread Pool Size | The number of threads to be used for concurrent operations. Leave empty to use all available threads. |
| Time between retries | The waiting time before an HTTP request is retried. Leave empty to use 500ms. |
Troubleshooting
In the event of an error, check that the configuration is correct, that the script is valid and that the API is accessible. You can also consult the logs for more details on the error. (voir View log files).
Technical aspects
The best way to understand how the Scripted API connector works is to consult the reference scripts. These contain comments that explain how it works. Similarly, it's best to develop a new connector based on the reference scripts.
Data schema
The data schema used by Scripted API connectors consists of "ScriptedAPIObjectClass". Each "ScriptedAPIObjectClass" contains "ScriptedAPIAttribute" which are used to represent the attributes of an object. For example, a Workday user is represented by a "WorkerObjectClass" containing the attributes "EMPLOYEE_ID", "FIRST_NAME", "LAST_NAME", etc.
Functions
The Scripted API connector communicates with the Groovy script by calling certain functions by name. The script must therefore contain certain functions in order to function correctly.
The following functions must be implemented:
| Function | Description |
|---|---|
| test | Test connection. |
| schema | Returns the data schema. |
| search | Searchs for objects. |
| create | Creates an object. |
| update | Updates an object. |
| delete | Deletes an object. |
| addAttributeValues | Adds values to an object attribute. |
| removeAttributeValues | Deletes attribute values from an object. |
For parameters and examples of how to implement these functions, please refer to the reference scripts.
Librairies
The following libraries are included in the Scripted API connector and can be used by scripts:
| Librairie | Utilisation |
|---|---|
| connid-connector-framework | ICF connector framework. |
| okhttp | HTTP requests. |
| org.json | JSON Handling. |