> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Matrix42

> Connect Matrix42 Enterprise Service Management to Serval workflows.

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.

> [!NOTE]
>
> 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](https://docs.matrix42.com/1074558_web-services/3463380_web-services-authentication-types).
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.

```typescript theme={null}
const activities = await matrix42.apiRequest(
  {
    method: "GET",
    path: "/m42Services/api/data/fragments/{ddName}",
    pathParams: { ddName: "SPSActivityClassBase" },
    query: { columns: "ID,Subject", pageSize: 50 },
    language: "de",
  },
  ctx,
);
```

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.

> [!WARNING]
>
> 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

| Area | Operations |
| - | - |
| Tickets | Create incidents/service requests; close incidents, service requests, tasks, problems, changes |
| Configuration items | Create, read, update, delete; check a user's access |
| Data fragments | Query, schema/localization, create, read, update, delete |
| Relations | Query, schema/localization, add, remove |
| Workflows | Start, resume, cancel, terminate; read asynchronous operation status |
| Configuration packages | Validate, install, read progress, uninstall |
| Documents | Generate text, compact text, HTML, PDF, JSON (Matrix42 26.1+) |

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.