Scripted API
Scripted API Connectors are ICF connectors based on a proprietary connector named Scripted API. This generic connector provides utility functions that can be used in Groovy scripts to create specific ICF connectors. These connectors can then be easily customized to meet the business needs of each organization. Customization is facilitated through a graphical interface integrated within RAC/M Identity.
Prerequisites
- RAC/M Identity 3.17 or later
- A data repository accessible via an API (e.g., Workday)
Script creation
This step involves creating a Groovy script to be used by the Scripted API connector.
- In the menu bar, navigate to Configuration > Script Files.
- Select the script corresponding to the desired connector, starting with
reference-scripts/scripted-api-.
For example, to create a connector for Workday, select:reference-scripts/scripted-api-19.0.0.0/workday.groovy.
Select the latest version.
If the connector doesn't already exist, you can create one based on reference scripts. - Click the Duplicate button at the bottom-right of the screen to create a copy of the script. This ensures the reference script remains intact.
- In the dialog that appears, give the script an appropriate name and click Duplicate.
- (If necessary) Edit the script to meet your specific needs. Be sure to save your changes regularly to avoid losing progress.
- Click Save to store the script.
Connector creation
This step involves creating a Scripted API connector that will use the script created earlier. Follow the steps for creating a connector as described in Configuring an ICF Connector. Select Scripted API as the connector type. Use the same version as the one used for the script.
Configuration as a Target System
The following parameters are required:
| Configuration | Description |
|---|---|
| Script Path | Path to the previously created Groovy script. |
| API URL | URL of the API to connect to. |
| Preferred Authentication Method | Authentication method to use (password, bearer, userToken, or oauth2). |
| Authentication URL | URL for authentication. |
| Custom Config 1 to 5 | Custom configurations that can be used by the script. |
| Username | Username to use for authentication. |
| Password | Password to use for authentication. |
| User Token | User token to use for authentication. |
| Bearer Token | Bearer token to use for authentication. |
| Custom Secret 1 to 5 | Custom secrets that can be used by the script, securely encrypted and managed. |
Advanced Configuration
The following parameters are required:
| Configuration | Description |
|---|---|
| Timeout | Timeout in milliseconds. |
| Time between retries | Time to wait before retrying an HTTP request. Leave blank to use the default 500 ms. |
| Thread Pool Size | Number of threads to use for concurrent operations. Leave blank to use all available threads. |
Authentication (OAuth2)
The connector can use the OAuth2 protocol to authenticate with the API. This requires additional configuration properties to enable the authentication flow:
| Configuration | Required Value |
|---|---|
| Custom Config 1 | The grant_type. |
| Custom Config 2 | The client_id. |
| Custom Secret 1 | The client_secret. |
| Preferred Authentication Method | oauth2 |
| Authentication URL | URL for authentication. |
Authentification (saml2)
Le connecteur peut utilisé le protocole OAuth2 saml2 pour s'authentifier auprès de l'API. Cela implique que la configuration nécessite quelques propriétés supplémentaires afin de permettre au flux d'authentification de se dérouler correctement :
| Configuration | Required Value |
|---|---|
| Script Path | Path to the previously created Groovy script. |
| API URL | scim https://<api?>.sapsf.com/rest/iam/scim/v2 |
| Preferred Authentication Method | saml2 |
| Authentication URL | L'URL servant à l'authentification. |
| Custom Config 1 | The grant_type urn:ietf:params:oauth:grant-type:saml2-bearer |
| Custom Config 2 | The client_id. |
| Custom Config 3 | The company_id |
| Custom Config 4 | The token_url https://<api?>.sapsf.com/oauth/token |
| Username | The user_id |
| Custom Secret 1 | The private_key |
Authentication (Bearer)
| Configuration | Required Value |
|---|---|
| Bearer Token | The "Access Token". |
| API URL | URL of the API to connect to. |
| Preferred Authentication Method | Bearer. |
Authentication (Password)
| Configuration | Description |
|---|---|
| API URL | URL of the API to connect to. |
| Authentication method | password. |
| Username | Username to connect to the API. |
| Password | Password to connect to the API. |
Authentication (User Token)
| Configuration | Description |
|---|---|
| Authentication method | userToken. |
| User Token | User token used to connect to the API. |
Troubleshooting
In case of errors, ensure that the configuration is correct, the script is valid, and the API is accessible. You can also check logs for more details on the error (see Viewing Logs).
Technical Details
To better understand how the Scripted API connector works, refer to the reference scripts. These include comments explaining their functionality. It is recommended to develop a new connector based on these reference scripts.
Data Schema
The data schema used by Scripted API connectors is composed of ScriptedAPIObjectClass.
Each ScriptedAPIObjectClass contains ScriptedAPIAttribute used to represent object attributes. For instance, a Workday user is represented by a WorkerObjectClass containing attributes like EMPLOYEE_ID, FIRST_NAME, LAST_NAME, etc.
Functions
The Scripted API connector communicates with the Groovy script by calling certain functions by name.
The following functions must be implemented:
| Function | Description |
|---|---|
| test | Tests the connection. |
| schema | Returns the data schema. |
| search | Searches for objects. |
| create | Creates an object. |
| update | Updates an object. |
| delete | Deletes an object. |
| addAttributeValues | Adds values to an object's attribute. |
| removeAttributeValues | Removes values from an object's attribute. |
Refer to the reference scripts for parameters and implementation examples for these functions.
Libraries
The following libraries are included in the Scripted API connector and can be used in scripts:
| Library | Purpose |
|---|---|
| connid-connector-framework | ICF Connector Framework |
| okhttp | HTTP Requests |
| org.json | JSON Manipulation |
Threads
The Scrited API connector supports concurrent operations. To do this, it uses a thread pool. This allows multiple API calls to be made in parallel to increase performance. This is especially useful when importing a large number of users. The number of threads to use can be configured through the "Thread Pool Size" parameter. Leave this parameter empty to use all available threads.