In this chapter is described configuration instructions for connector to be able to connect to REST API. 

For configuring provisioning , you will need access to Platform configuration console.

1. Open the Administration area (a gear symbol).
2. Open Connectors view.
3. Choose "New connector" 

4. Select Data Source type to be Generic REST API

5. Give name for the connector and add connection settings:

• Connector name - give your connector a friendly name (name can be changed afterwards)
• Host url - base url for REST API. This can be used as prefix for final url to be called.
• REST Connector type - Generic or Google. For Google use Google, and for all other type of REST API's use General.

Select correct authentication method, based on system you are connecting

• Basic Auth - Basic authentication using username/password as base64 encoded authentication header
• Bearer Token - Using constant bearer token authentication header
• Disabled - For public API's without authentication (in 2025.3 release and newer)
• Auth Header - For constant secret header (in 2025.3 release and newer)
• Dynamic Token - For OAuth 2.0 Client Credentials flow and similar than it (in 2025.3 release and newer) 
  • Example of Dynamic Token configuration: https://docs.efecte.com/configure-connectors/ms-ado-connector
  • When you are using Dynamic Token authentication, you need to set your Login Content type also to header. For example if your Login Content type is application/json then you need to add to connector a header: 
    Content-Type application/json

Set correct pagination, based on the 3rd party system you are connecting with this connector. 

Generic REST API connector pagination supports 5 different types of pagination. These are used by scheduled tasks:

• Disabled - The API does not support pagination and returns all data in a single response.
• Start & Offset - The API uses start and offset parameters. On each request, connector automatically increases start by amount of offset until all data is retrieved.
• Page Increment - The API uses page numbering. On each request, connector automatically increments the page number by one until no more results are returned.
• Link Token - The response includes a URL for the next page. Connector automatically follows that URL until no next link is provided.
• Link Attribute Token - The response includes a next-page token. Connector automatically send that token as a query parameter in the next request. This is used for example by Google.

Fulfill WebAPI user information

• WebAPI user - select correct WebAPI user which is used when writing data from external system to Matrix42 Core, Pro and IGA solutions
• WebAPI password - password for the WebAPI user

7. Save connector information

8. Add external REST API systems root https certificate to be trusted by Connector management (EPE). This can be done only by Matrix42: Add certificate.

9. Matrix42 Core, Pro and IGA solution is now able to connect to external REST API

• Next step is to configure scheduled task for data read or event task for data writing and actions towards REST API. 

2025.3 version added support for reading data with scheduled tasks.

Generic REST API connector is used to read data from 3rd party solutions exposing REST API by creating scheduled-based provisioning task.   

How to create new task for Scheduled Provisioning

For configuring scheduled-based provisioning task, you will need access to Platform configuration console.

Note! If connector is not created, you have to create first “new connector” and after that you are able to create new tasks.

1. Open the Platform configuration view (a gear symbol).
2. Open Connectors view.
3. Choose connector for which scheduled-based task is configured
4. Select “new task” under the correct connector

5. Define scheduling for the task (if and how scheduled task should be run periodically). Choose scheduling sequence, which depends how much data is read to Matrix42 Core, Pro and IGA solution.

Recommended scheduling sequence, depends how much data is read from customers directory to the Matrix42 Core, Pro and IGA solution and is import partial or full load. 

Example scheduling for reading data. 

5.  Fill in task details

• Fill in unique task name for the scheduled-based task
• Task usage indicated that is the task used for reading data, writing data or to authentication. Note that If event type is changed afterwards it can break the workflows or integrations.
• Mappings type depends what type of information is read from the directory, only Generic is supported for Generic REST API connector
  • Generic (one template) - are used when a generic information is read from the directory

6. Fill in task parameters

• Query - actual API url endpoint to be called
• Sub Queries - optional. Can be used if there is a need to fetch data related to Query, from another API endpoint.
  Sub queries support only basic first level variable from main query resultset. Subqueries don't support jsonpath syntax.
  Example of supported subquery (this expects to have userid attribute on first level on json response): /groups/{userid}
  Example of NOT supported subquery which tries to use jsonpath syntax: /groups/{users[0].userid}
• Query headers - Custom headers added to final query during data extraction. 
  Connector management (EPE) adds these headers automatically, so no need to explicitly add these:
  “Content-Type”, “…”
"Authorization", “…”
• Value Marker - can be empty. Value depends on JSON data structure returned by Query API. For example if whole data is inside resultset json object, set this value marker to resultset.
• Error Marker - can be empty. Value depends on JSON error message structure returned by Query API. For example if whole error message is inside errors json object, set this value marker to errors.
• Safety Threshold for API calls - safety threshold to prevent infinite loops. Set this 2 times larger than current calls needed for this task to fetch all data. If fetching all your data by this task, e.g. 50 paginated calls are needed, set this value to 100.
• Unique attribute - set unique attribute name (case sensitive) from JSON resultset. Usually ID, id or guid etc. Every row must have unique value in this attribute. You also need to add this attribute to mapping table in the end of task configuration. Note! Scheduled task can't fetch data which doesn't contain this unique attribute for every object. 
   

7. Fill in failure information

Optional settings for failure handling, if scheduled task fails it can create data card to ESM that displays the error. If failure settings are defined, the administrator does not need to manually check the status of scheduled tasks.

• Failure template - Select a Template of datacard which will be created in case of any errors during provisioning (connection to data sources,timeouts,etc.)
• Failure folder - Select folder where failure data card is stored.
• Failure attribute - Select an attribute where in the Failure Template should the error information be stored in. Select text type attribute.

8. Add Generic mappings

In mappings section you configure which attribute from JSON message is read to which attribute on Matrix42 Core, Pro and IGA datacard.

• Target template - Select a template to define attribute mappings
• Target folder - Select a folder from a list of folders. The list is narrowed down to match compatibility with selected Template.
• Data Source Type mapping - optional. If it is set, it writes connectors type to that attribute.
• Task Id mapping - Task id number is written to this attribute.
• Set value to datacard fo object deleted from source system - This functionality is activated by setting checkbox on. When some object that was previously read from 3rd party system to solution is deleted from 3rd party system (meaning this task query doesn't return it anymore). This scheduled task notices that is was deleted and marks that datacard selected attribute with value you want. This can be for example used to set Status attribute to Deleted (as shown in below example screenshot).

• Attribute mappings
  1. External attribute - which attribute from the 3rd party system API is read from JSON body
  2. Local attribute - to which attribute in Matrix42 Core, Pro and IGA attribute is mapped to
• It is possible to set additional attributes to attribute mappings, by choosing New attribute
• JSONPath expressions supported and not supported on mappings table external attribute: 
  https://docs.efecte.com/configure-connectors/jsonpath-mappings-for-generic-rest-api-connector

9 Save provisioning task from the Save button. 

If some required attributes are missing the save button is displayed as grey and it will display what is missing from the settings.

10. You have now configured scheduled-based connector task for Generic REST API read

• You can now wait until task is started based on scheduling or
• Run task manually - by clicking the “Run Task” button on top of task edit window, task is configured to be scheduled to start immediately. Usually for test runs or if you don't want to change the schedule settings, but want to run the task now.   

Example of manual task run starting message:

If task is executed manually (run task) or it is run according to scheduling, task status can be reviewed from Scheduled tasks list manage column, by clicking “View history” button.

Event task is used when writing data (or making other event based REST API calls from Workflow) towards customers solution offering generic REST API. These Connector Management capabilities are available for all Matrix42 Core, Pro and IGA solutions.

Examples for event-based task usages:

• Add account
• Update person
• Activate account
• Create ticket
• Inactive device

All configuration related to Connector Management and event-based provisioning task are configured in Matrix42 Core, Pro or IGA Connectors view.

1. Open the Matrix42 Core, Pro or IGA configuration view (a gear symbol).

2. Open connectors view

3. Choose connector, which will use the event task

4. Select  “new task” under correct connector

5. Fill in task settings

• Task name - Give name name for the task, it will be displayed in connectors view.
  • It is good practice to name a task in a way that describes its purpose for example [Template name]:[Activity] IGA Service request: Add account
• Task usage indicated that is the task used for reading data or writing data. Can be changed afterwards, but it's not recommended if event task is in use. It will break workflows.
• Mappings type depends what type of information is read from the directory, identity mappings selections are displayed based on this setting.
  • Generic (one template) - is used when generic information is read from the directory. This can be any type of data. 

Warning about changing task usage or mappings type when event task in use:

6. Fill in task parameters

• Query - api endpoint which this task will call. This can be left empty and given in Workflow orchestration node. You can give full endpoint address like: https://apiurl.com/endpointtocall or just end of url. If you give just end of url for example endpointtocall, final url will be concatenated using all these: connector host url + task query + Orchestration node url.
• Query headers - Custom headers added to final query to REST API. See target/source system API documentation what headers it requires.
• Date Attribute formatter - used to format dates, when provisioning date type attribute to target system. You can select format from list or add your own custom format. Right side field shows example of formatted date.
• DateTime Attribute formatter - used to format datetimes, when provisioning datetime type attribute to target system. You can select format from list or add your own custom format. Right side field shows example of formatted datetime.

7. Define generic mappings

• Target template - Select a template to define attribute mappings
• Target folder - Select a folder from a list of folders. The list is narrowed down to match compatibility with selected Template.
• Attribute mappings (Note! In most cases there is no need to set these. Data used in event task is configured on Workflow Orchestration node).
  1. Efecte template attribute - to which attribute in Efecte directory attribute is mapped to.
  2. Directory attribute - which attribute from the directory is mapped to Efecte
• Add new attribute -  It is possible to set additional attributes, by choosing New attribute button.

8. Save task

Save provisioning task with “save” button

If any mandatory information is missing, you are not able to save the task and save button will show missing information. 

9. Configure Workflow to use this event-based task with Orchestration node

The next step is to configure the workflow to use this event-based task. 

From workflow engine in Platform, it is possible to execute provisioning activities towards customer directory services. This means that any of the available orchestration nodes activity can be run at any point of the workflow.

Workflow references are shown in the connector overview page (you can refresh workflow references with “Show Workflow references button”):

Generic REST call

Add Orchestration node to your workflow and configure following things.

Name - set descriptive name

Description - set descriptive description

Orchestrate - select Provisioning Engine

Data Source - select Generic REST API

Activity - select Generic REST call

Target - select your event-based task (you can use same task for many orchestration nodes)

Action - select action based on REST API you are calling (check API documentation for correct action). Supported actions are: POST, PUT, PATCH, DELETE and GET

REST URL - api endpoint you are calling. This can be full url or suffix of the url. If you use suffix, actual url to call will be concatenated using all these: connector host url + task query + Orchestration node url. You can use template attribute variables similarly than in email node, using dollar syntax like: $attribute_code$ and $reference:attribute_code$. 

Note! If you have spaces or $ signs in your url, remember to url encode those. So $ is %24 space is %20

Rest Body - json body for api call. Can be empty if API you are calling does not need body. See body details from API documentation. You can use template attribute variables similarly than in email node, using dollar syntax like: $attribute_code$ and $reference:attribute_code$. 

For example in this body we have two variables: $firstname$ and $lastname$
{"name": {
   "givenName": "$firstname$",
   "familyName": “$lastname$”}}

In case you need to create complicated json body for API call, you can construct that full json first to some datacard attribute. And then only have that attribute code in body, like this: $generated_json_body_attributecode$

import json

if onPremisesExtensionAttributes:
  _data = this.get("onPremisesExtensionAttributes")
  _obj = json.loads(_data)
  _value = _obj["extensionAttribute14"]
  this.set("extensionAttribute14code",_value)

Rest Response Attribute - resultset json of API call will be written to this attribute. Not all API's return any response json. See details from API documentation. Note! This doesn't contain actual http code e.g. 200, 401, 500 etc., this contains only resultset message if API returned any.

import json

if onPremisesExtensionAttributes:
  _data = this.get("onPremisesExtensionAttributes")
  _obj = json.loads(_data)
  _value = _obj["extensionAttribute14"]
  this.set("extensionAttribute14code",_value)

Provisioning exception - If there is an issue on REST API call, error will be written to this attribute.

Exception handling:

• Provisioning exception is an optional property on this workflow node. Admins can configure this property in use where exceptions can be written if any exceptions exists during the provisioning actions. 
• The result of a node will be in the “Completed” state if REST API http response code is 200 or over and under 400.
• Details about successfully/unsuccessful REST API calls can be found in logs.

Microsoft Azure DevOps: https://docs.efecte.com/configure-connectors/ms-ado-connector

Google: https://docs.efecte.com/configure-connectors/google-connector

Raynet: https://docs.efecte.com/configure-connectors/raynet-connector

Matrix42 Enterprise and Matrix42 Software Asset Management (SAM): https://docs.efecte.com/configure-connectors/m42enterprise-sam-connector

In this chapter are described troubleshooting options,

• In case failure template is used, check correct data card
• Check scheduled task history from connector management
• Check Native Connectors logs. From Connectors tab, left menu Logs. 
  • See mainly debug.log, *worker*.log and datapump.log  

Event-based tasks restrictions

• Emails are not supported
• Attachments are not supported

Scheduled tasks restrictions

• Date type attributes (you need to map those to string type attribute)
• DateTime type attributes (you need to map those to string type attribute)
• Emails are not supported
• Attachments are not supported