How to configure Matrix42 for integration with ONEiO

Introduction

This document provides guidance on making Matrix42 integration-ready with ONEiO. The default endpoint supports the integration of various objects, including:

• Incidents
• Changes
• Problems
• Service Requests
• Tickets
• Tasks

For any questions regarding the integration setup, please contact support@oneio.cloud.

You can sign up for a free trial of ONEiO using the following link: ONEiO Free Trial.

Sending Messages from ONEiO to Matrix42

To create and modify objects in Matrix42, ONEiO utilizes the native REST APIs available in your system.

Setup Requirements:

1. Generate an API token in Matrix42.
2. Insert the generated token in the "Token" field within the ONEiO app.
3. Use a dedicated integration user for best security practices.
4. Follow the Matrix42 API Token Creation Documentation for detailed instructions.

Sending Messages from Matrix42 to ONEiO

To extract and send data from Matrix42 to ONEiO, a combination of Compliance Rules and Workflows must be implemented.

For detailed information, refer to the official Matrix42 documentation on:

• Workflows
• Compliance Rules

Creating a Workflow

Step 1: Loop Through Compliance Rule Actions

1. Open Matrix42 Workflow Studio.

2. Drag and drop a ForEach activity.

3. Set the loop variable to singleob.

4. Ensure the source collection is ObjectContexts.

5. Inside the loop, add a Flowchart for structured processing.

Step 2: Retrieve Ticket Data

1. Add a Get Ticket Data activity inside the Flowchart.

2. Configure the properties:

• • Data Definition: SPSActivityClassBase
  • Where Expression: [Expression-ObjectID] = @ExpressionObjectID
  • Store results in:
    • ID → fragmentid
    • TypeID → typeid
    • ExpressionObjectID → expression_object_id

Step 3: Invoke PowerShell Script

1. Add an Invoke PowerShell activity.

2. Pass the following parameters:

• • TypeID (GUID)
  • ExpressionObjectID (GUID)

3. The PowerShell script will:

• • Construct a JSON payload.
  • Send a POST request to ONEiO’s endpoint using Invoke-RestMethod.

Example PowerShell Script

param(
    [Guid] $ExpressionObjectID,
    [Guid] $TypeID
)

# Define the target URI (auth_token value taken from ONEiO App)
$uri = "https://rest-receiver-test.service-flow.com/api?auth_token=xxx"

# Define the JSON payload
$data = @{ 
    TypeID = $TypeID.ToString()
    ExpressionObjectID = $ExpressionObjectID.ToString()
} | ConvertTo-Json -Depth 3

# Define headers
$headers = @{
    "Content-Type" = "application/json"
}

# Debugging: Log JSON payload before sending
Write-Host "Sending JSON payload: $data"

# Send the HTTP POST request
try {
    $response = Invoke-RestMethod -Uri $uri -Method Post -Headers $headers -Body $data
    Write-Host "Response from server: $($response | ConvertTo-Json -Depth 3)"
} catch {
    Write-Host "Error occurred: $_"
}

$ResponseContained = $false

Step 4: Decision Making (Optional)

1. Add a Decision activity to evaluate the API response.
2. Configure conditional branches to handle different responses:
   • Success
   • Failure
   • Retry Logic

Creating a Compliance Rule for Object Changes

Step 1: Creating a New Compliance Rule

1. Navigate to Compliance Rule section in Matrix42 ITSM.
2. Click New Rule.
3. Enter a Name (e.g., Ud_oneio_test_2).
4. Optionally, provide a Description.
5. Under Configuration Element, choose Data Definition.
6. Select Data Definition as Activity (SPSActivityClassBase).
7. Under Configuration Items, select relevant options:
   • Ticket (SPSActivityTypeTicket)
   • Service Request (SPSActivityTypeServiceRequest)
   • Problem (SPSActivityTypeGroupTicket)
   • Task (SPSActivityTypeBase)
   • Incident (SPSActivityTypeIncident)
   • Change (SVMChangeRequestType)
8. Click Save to proceed.

Step 2: Defining Rule Conditions

1. In Condition Type, select Change an Object.
2. Click Add Condition and define trigger conditions you are interested in:
   • Activity.Description – Changed
   • Activity.DescriptionHTML – Changed
   • Activity.Priority – Changed
   • Main Data Definition.State – Changed
3. Use Group option if necessary.
4. Click Save to continue.

Step 3: Configuring Processing Options

1. Choose Processing Method:
   • Process each compliance rule event for each object (Recommended for real-time updates)
   • Only process the last compliance rule event per object (Prevents duplicate messages)
   • Process compliance rule events for respective objects conjointly (Useful for bulk changes)
2. Choose Processing Time:
   • Immediately (Recommended for real-time processing)
   • Delayed (For scheduled execution)
3. Click Save.

Step 4: Setting the Subsequent Processing Action

1. Click Add Action under Set the subsequent activity for processing.
2. Select Start Workflow.
3. Assign an Order Number if needed.
4. Click Save.

Step 5: Linking to ONEiO Workflow

1. In the Add Compliance Rule Action window, select the Workflow to initiate (e.g., ONEiO Test).
2. Choose Previous Attributes if needed to retain "before" values in the workflow.
3. Click Save to finalize the configuration.

Creating a Compliance Rule for Journal Updates (also covers object Creation)

Step 1: Creating a New Compliance Rule

1. Navigate to Compliance Rule section in Matrix42 ITSM.
2. Click New Rule.
3. Enter a Name (e.g., Ud_oneio_test_2).
4. Optionally, provide a Description.
5. Under Configuration Element, choose Data Definition.
6. Select Data Definition as Journal Entry (SPSActivityClassUnitOfWork).
7. Under Configuration Items, select relevant options (same as object changes).
8. Click Save to proceed.

Step 2: Defining Rule Conditions

No specific conditions required except for the Condition Type which should be "Create an Object".

Step 3: Configuring Processing Options

Only process the last compliance rule event per object

Step 4: Setting the Subsequent Processing Action

Follow the same steps as in Object Changes above.

Step 5: Linking to ONEiO Workflow

Follow the same steps as in Object Changes above.

Conclusion

By following these steps, you can successfully integrate Matrix42 with ONEiO, enabling efficient communication between the two systems. If you encounter any issues, reach out to support@oneio.cloud for assistance.