Skip to main content
The Matrix42 integration connects Serval workflows to the documented Enterprise Service Management server APIs: tickets, configuration items, data fragments and relations, workflow execution, access checks, configuration packages, and document generation. Generic data operations cover assets, users, knowledge articles, and custom records through their Matrix42 configuration item and data definition names.
This beta provides workflow API actions and a connection health check. Bidirectional ticket synchronization, inbound events, and automatic knowledge ingestion are not included.

​
Connect Matrix42

  1. In Matrix42, create a Web Service API Token for an account with the permissions your workflows need. Follow Matrix42’s authentication guide.
  2. In Serval, open Integrations, find Matrix42, and connect it.
  3. Enter your Instance host, such as matrix42.example.com, and API token. The host must use HTTPS on the default port, with the standard /m42Services service path. Do not include an API path in the host field.
  4. Run Validate Matrix42 API connection to check authentication and API reachability. An empty successful response does not establish record access.
  5. Run Read a Matrix42 activity to list and read one visible activity, and Read Matrix42 data schema to check field metadata access. An empty dataset leaves activity-read access unverified. These checks do not establish write, package-administration, workflow-execution, or document-generation permissions.
Serval stores the API token securely and exchanges it for an access token before each API call. Saving connection settings does not itself authenticate with Matrix42. Replacing the instance host requires entering a token again. Keep the token active and replace it in Serval when you rotate it in Matrix42. The instance must be reachable from Serval’s integration proxy. Private on-premises networking and direct worker routing need separate validation; this connector does not enable private-network access.

​
Build workflows

Use matrix42.apiRequest for JSON public API operations. The workflow context contains the connection ID and instance host; it contains no token. Pass language: "de" to request German data when the instance supports it.
List operations default to pageSize: 100 and accept page sizes from 1 to 1000. Use pageNumber to continue. The action returns one page; it does not automatically fetch every record. Confirm paging and custom field names against your instance’s Administration > Web Services > Public API documentation. The same view supplies ticket activityType values and required creation fields. Before updating, read the object or fragment and retain its TimeStamp values to detect concurrent edits. Object updates normally use full: false. full: true replaces supplied multi-fragment collections, so first read the complete object and preserve existing entries.
Closing tickets requires an explicit CloseRelatedIncidents value. Set it to false to close only the listed object IDs. Set notification flags explicitly when your workflow must avoid sending email; omitted flags inherit Matrix42 settings. Do not automatically retry a write whose outcome is unknown.

​
API coverage

For package uploads, call matrix42.installPackage({packageBase64, validateOnly}, ctx). The action requires an explicit validation/install choice. Package administration requires Matrix42 administrator permissions. Poll GET /wminstaller/api/installation for progress. Uninstallation uses GET /wminstaller/api/{packageId}/uninstall and changes system configuration. For documents, call matrix42.generateDocument({documentTemplateObjectId, body}, ctx). Its body contains Type (1–5), and optionally Lcid (1031 for German), Parameters, SkinId, and UserTimeZone. It returns {base64, contentType, size} so PDF bytes and text encodings are preserved. Package uploads and document responses are limited to 10 MiB. These file operations use dedicated actions instead of apiRequest. Pass document bytes to an upload or attachment action in the same workflow and return the destination’s URL or ID. Final workflow results are truncated at 1 MiB, so returning a large base64 document as the final result will not deliver the complete file. Keep the base64 value between workflow steps until it reaches its destination. Workflow resume and package uninstall are writes despite using HTTP GET. They require the same authorization and care as other mutating operations. Closing a change also requires an explicit CloseRelatedProblems choice. The website documents 29 supported server operations; it is not an exhaustive catalogue of every customer deployment. Use your instance’s Public API catalogue to identify version differences and additional custom endpoints. Matrix42’s browser-only Front End Public API and identity-provider login/logout flows are not workflow APIs; Serval handles server authentication with the API token.

​
Troubleshooting

  • Authentication fails: confirm the token belongs to this instance and is active. Enter the long-lived API token, not a temporary access token.
  • HTTP 403 or missing data: check the account’s data permissions and the API method’s audience restrictions. A null or empty read can mean access was denied, so it is not proof that the record does not exist.
  • Reads work but writes fail: check required attributes, references, and write permissions in the instance’s public API documentation.
  • Update conflict: read the latest object, reconcile the changes, and submit its current fragment timestamps.
  • Network or TLS failure: check DNS, firewall rules, and certificate trust. Token-service outages return HTTP 502 and token-service rate limits return HTTP 429 with a valid vendor Retry-After cooldown; explicit token rejection returns HTTP 401. HTTP endpoints, custom service paths, and nonstandard ports are unsupported.