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 - select Generic
• Authentication method - Select Basic Authentication
• Basic User Name - username to M42 Enterprise / SAM
• Basic Password - password of previous field user

6. Set correct pagination

You can create 2 separate Connectors with identical settings, except this pagination setting is different. Create one connector for tasks where API supports pagination and another connector, for tasks where API doesn't support pagination.

A) Set pagination For Matrix42 Enterprise/SAM Connector (for tasks calling API's which does not support pagination)
Use disabled as dataquery API used in scheduled task example doesn't support pagination:

B) Set pagination For Matrix42 Enterprise/SAM Connector, for tasks calling API's which support pagination.

• Pagination type - Page Increment
• Pagination Page Attribute - pagenumber
• Pagination Page Start - 1
• Pagination Page Size Attribute - pagesize
• Pagination Page Size - set this according to your data. Check maximum value from Matrix42 Enterprise/SAM documentation or from consultants. This needs to be smaller than smallest amount of data returned by API you call. If you set this too high Matrix42 Enterprise or SAM doesn't return any data.

7. 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

8. Save connector information

9. Add external Matrix42 Enterprise or SAM systems root https certificate to be trusted by Connector management (EPE). This can be done only by Matrix42: Add certificate.

10. Matrix42 Core, Pro and IGA solution is now able to connect to Matrix42 Enterprise and Matrix42 SAM

• Next step is to configure scheduled task for data read or event task for data writing and actions towards Matrix42 Enterprise and SAM. 

1. Add Scheduled task under correct Connector, by clicking “New Task”

2. Set Task attributes

Scheduling - Set scheduling if needed

Task name - Set informative name

Task usage - Scheduled

Mapping type - Generic Template

Query - Query depends on what Matrix42 Enterprise or API endpoint you want to call, to fetch data. See Matrix42 Enterprise documentation for correct API url and parameters.
In this example: /data/fragments/SPSActivityClassBase?columns=ID,Subject,Description,TicketNumber

Sub Queries - You can add subqueries if you want to read more data related to resultset returned by actual Query. In this example we don't use that functionality.

Query headers - can be left empty

Value Marker - leave empty

Error Marker - leave empty

Safety threshold for API calls - suggested to be set twice as big as how many pages this API will return. If you leave it empty there is no safety threshold and then Connector can go to infinite loop if there is error in configuration.

Unique Attribute - Unique attribute on API resultset. Usually ID in Matrix42 Enterprise API's, but confirm it from documentation.

3. 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.

4. Fill in Generic mappings information

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 (in this example Ticket)
• Target folder - Select a folder from a list of folders. The list is narrowed down to match compatibility with selected Template. (in this example Tickets)
• 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. Correct attribute to choose depends on how your Template is configured.
• 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. 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 09 - Closed (as shown in below example screenshot). This Attribute name and Attribute value needs to be set based on how your Template is configured.

• Attribute mappings
  1. External attribute - which attribute from the Matrix42 Enterprise 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
• You need to add mapping also to Unique Attribute, in this example it is ID. That needs to be mapped to unique attribute on template, in this example text1.
• See supported mapping syntaxes: https://docs.efecte.com/configure-connectors/jsonpath-mappings-for-generic-rest-api-connector 

5. 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.

6. You have now configured scheduled-based connector task

• 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.

1. Add Scheduled task under correct Connector, by clicking “New Task”

2. Set Task attributes

Scheduling - Set scheduling if needed

Task name - Set informative name

Task usage - Scheduled

Mapping type - Generic Template

Query - Query depends on what Matrix42 SAM API endpoint you want to call, to fetch data. See Matrix42 SAM documentation for correct API url and parameters.
In this example: dataquery/aad704de-a242-c667-123b-08d45a5faa97

Note! If you use Matrix42 Enterprise/SAM dataquery API (like in this example), it returns by default only 10000 objects. Dataquery API doesn't support pagination. If you need to fetch more than 10000 objects, contact Matrix42 and ask to increase your environment limit. More info below:

“Data Query Response Records Count
The setting PDRDwpConfigurationClass.DataQueryMaxResponseRecords defines the maximum number of records returned by the "Data Query" Web Service.
Default Value: 10,000 records.”

Sub Queries - You can add subqueries if you want to read more data related to resultset returned by actual Query. In this example we don't use that functionality.

Query headers - can be left empty

Value Marker - leave empty

Error Marker - leave empty

Safety threshold for API calls - suggested to be set twice as big as how many pages this API will return. If you leave it empty there is no safety threshold and then Connector can go to infinite loop if there is error in configuration.

Unique Attribute - Unique attribute on API resultset. Usually Id in Matrix42 SAM API's, but confirm it from documentation.

3. 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.

4. Fill in Generic mappings information

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 (in this example Device)
• Target folder - Select a folder from a list of folders. The list is narrowed down to match compatibility with selected Template. (in this example Assets/Servers)
• 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. Correct attribute to choose depends on how your Template is configured.
• 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. 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. This Attribute name and Attribute value needs to be set based on how your Template is configured. In this example this functionality is not used.

• Attribute mappings
  1. External attribute - which attribute from the Matrix42 SAM 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
• You need to add mapping also to Unique Attribute, in this example it is Id. That needs to be mapped to unique attribute on template, in this example Intune id.
• See supported mapping syntaxes: https://docs.efecte.com/configure-connectors/jsonpath-mappings-for-generic-rest-api-connector 

5. 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.

6. You have now configured scheduled-based connector task

• 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.

Here is basic example of Event task and Orchestration node, which are used to create activitytype 6 tickets to Matrix42 enterprise. In production usage you need to design what type of tickets you want to create and what attributes are needed to be set to those.

1. Add Event-based task under correct Connector, by clicking “New Task”

2. Set attributes to task

Task name - descriptive unique name
Task usage - Event
Mappings type - Generic Template
Query - url for the API you want to call. In this example we create ticket, so we are using query: /ticket/ (final API url to call is constructed by concatenating connector url, this query url and orchestration node REST URL). You can also leave query empty and set your api url to Orchestration node REST URL attribute.

Date Attribute formatter - set correct format if you are provisioning date attributes

DateTime Attribute formatter - set correct format if you are provisioning datetime attributes

Set Generic Mappings

Target template - template from which Workflow you are going to call this task
Target folder - folder for your data

No not set attributes to mapping table (external attribute - local attribute). Attribute mapping is done on workflow orchestration node.

3. Save task

4. Create Orchestration node to your workflow, to call this event-based task

Orchestrate - Provisioning Engine
Data Source - Generic REST API
Activity - Generic REST call
Target - Create ticket as service request (your event-based task name)
Action - In this example POST as we are creating tickets with API that creates ticket.
REST URL - in this example create?activitytype=6 as we are creating tickets with activitytype 6
REST Body - you can generate API call body directly here. Or in more complicated cases generate it separately (in script node) to some attribute, and then us that attribute here. In this case body to create ticket is created directly here, using subject and details attribute code variables. 
Body what we use in this example has hard coded User (you might consider using some other logic for that), subject and description values are read from datacards subject and details attributes.
{
 "Subject": "$subject$",
 "Description": "$details$",
  "Priority": 0,
 "Impact": 0,
 "Urgency": 0,
 "User":"0e8aac28-b2df-ef11-58b1-005056905558"
}

REST Response attribute - response of API call will be stored to this attribute
Provisioning exception - if there is issue with API call, exception will be stored to this attribute

Finalize your workflow other nodes and flow

Save workflow and Publish it

5. Test Workflow and Event-based task

Restrictions

• More than 1 level of subqueries for scheduled tasks are not supported, for performance reasons.
• Sending or fetching attachments is not supported.
• Sending or fetching emails is not supported.
• Fetching Date type attributes (you need to map those to string type attribute)
• Fetching DateTime type attributes (you need to map those to string type attribute)