Description
n8n-nodes-matrix42
This is an n8n community node that integrates with the Matrix42 ESMP Web Services API. It allows you to retrieve and work with Data Fragments from Matrix42 Data Definitions directly in your n8n workflows.
Matrix42’s ESMP API exposes CRUD‑style endpoints for data fragments, supporting OData‑like filtering, column selection, paging, sorting, and more.
n8n is a fair-code licensed workflow automation platform.
| Contents | |
| — | — |
| Installation | Install as an n8n community node |
| Operations | Every resource and operation of the Matrix42 node |
| Matrix42 Trigger | The polling trigger node and its events |
| Credentials | Webservice Token and Basic auth setup |
| Compatibility | Supported n8n, Node.js and Matrix42 versions |
| Resources | Documentation links |
| Version History | What changed in each release |
| Project | Contributing, code of conduct, security policy, releases |
| Legal & Disclaimer | Trademark and API-usage notes |
Installation
Follow the installation guide in the n8n community nodes documentation.
Operations
This node supports multiple operations across different resources:
Data Fragment
- Get Many (
getAll): Retrieve data fragments matching a search expression, with Return All / Limit paging. - Create (
create): Create a new data fragment in the specified Data Definition. - Update (
update): Update an existing data fragment. - Delete (
delete): Delete a data fragment by its ID. - Create (
create): Create a new object for a Configuration Item. - Get (
get): Retrieve a single object by its ID. - Update (
update): Update an existing object. - Delete (
delete): Delete an object by its ID. - Get Data (
getData): Read the list items of a data query, with Return All / paging (zero-based pages). Uses thePOSTvariant so a structured User Filters group (QueryFilterGroup) can be passed in the body for ad-hoc filtering. - Create (
create): Open a new ticket in the Service Desk (with a selectable initial State). - Close (
close): Close an Incident or Service Request. - Transform (
transform): Transform a ticket into another type. - Add Journal Entry (
addJournalEntry): Add a journal entry (comment) to a ticket. Creator is optional — left empty, the entry is attributed to the API user. Optional template Parameters are entered as Name/Value/Format rows; note that Matrix42 only renders such parameters through the localized templates of system-generated entry types, so they have no visible effect on a plain comment entry. - Upload (
upload): Upload a file and attach it to a Configuration Item. - Execute (
execute): Run a predefined import definition to ingest data. - Event
- Data Definition — the watched class, picked from the instance’s schema.
- Type Filter — optionally narrow to specific configuration-item types (e.g. only Incidents); filtered server-side, and the dropdown only offers types composed of the selected data definition.
- Additional fields — an ASQL filter (AND-ed server-side), extra output columns, a per-poll limit, and Fetch Full Object to attach the complete object (all fragments) to each result.
- Output rows always include the fragment
ID, the object ID asObjectID(what the ticket operations expect as EOID), the watermark attribute,DisplayStringandExpression-TypeID. - On activation the trigger baselines on the newest existing record — historic records never fire.
- The watermark comes from values the API itself returned (never the local clock), and boundary duplicates are deduplicated by ID, so events are neither lost nor duplicated — including rows created in the same millisecond and backlogs larger than the per-poll limit (they carry over to the next poll).
- “Fetch Test Event” in the editor returns the newest matching record without touching the trigger’s state.
- A failing configuration (e.g. a missing created-date attribute) fails visibly in the editor and on activation. On an active workflow, a failing poll produces a regular failed execution (feeding any configured error workflow) and polling simply continues — the trigger never dies silently.
- Known limitation: a row committed by a long-running database transaction (or written by a clock-skewed server) can become visible below an already-advanced watermark and is then not picked up. Under normal Service Desk load this does not occur; it can matter next to heavy concurrent imports.
- Exchanges the API Token for a short‑lived Bearer (JWT) access token via
GenerateAccessTokenFromApiTokenonce per workflow execution, caches it for the duration of the run, and re‑exchanges it automatically shortly before it expires or when the server rejects it (Matrix42 signals a rejected token with HTTP 406, which n8n’s built‑in credential refresh does not handle — the node therefore manages the exchange itself). - Uses the access token in the
Authorizationheader for all subsequent calls. - n8n: Node API version 1; built and tested against
n8n-workflow2.x. Requires n8n 1.85 or later (usesNodeConnectionTypes). Last tested with n8n 2.36.9. - Node.js: v22 or higher.
- Matrix42 ESMP API: Last tested against Matrix42 26.1.0.1390.
- n8n community nodes documentation
- CONTRIBUTING.md |
| Code of conduct | SECURITY.md |
| Releases | GitHub releases · published to npm from CI |Legal & Disclaimer
This project is an unofficial, community-maintained integration for the Matrix42 ESMP Public API.
It uses only documented, publicly available endpoints as described in the official
This Week's Favorites in automation
More in automation
Data Object
Data Query
Ticket
Storage
Import
Matrix42 Trigger
The package also ships a Matrix42 Trigger node — a polling trigger that starts a workflow when objects are created (or created/updated) in Matrix42. It works against any data definition, so “on new ticket” is just the default configuration (SPSActivityClassBase), and the same node covers users, assets, or custom classes.
– Ticket Created (default) — the common case as a preset: fires for every new Service Desk ticket (SPSActivityClassBase via CreatedDate, both hardcoded), leaving only the ticket-type filter and the additional fields to configure.
– Object Created — watches any data definition through a creation-date attribute (default CreatedDate; configurable, since not every class has one).
– Object Created or Updated — watches the universal TimeStamp rowversion column, which exists on every data definition and changes on every write. Exactly-once, no configuration needed.
Behavior notes:
Credentials
> Prerequisite: You must have access to a running Matrix42 instance with appropriate API permissions.
This node supports two authentication methods. Configure these under Workflow → Credentials.
Matrix42 Webservice Token Auth
1. Server URL — Your Matrix42 server URL (e.g. https://matrix42.example.com).
2. Webservice Token — Your Matrix42 API Token.
3. Ignore SSL Issues (Insecure) — Enable when the server uses a self‑signed certificate.
On execution, the node:
> Self‑signed certificates: enable Ignore SSL Issues (Insecure) on the credential, or add the server’s CA certificate to n8n’s trusted store (see https://docs.n8n.io/hosting/configuration/configuration-examples/custom-certificate-authority/).
Matrix42 Basic Auth
1. Server URL — As above.
2. User and Password — Your Matrix42 user credentials.
3. Ignore SSL Issues (Insecure) — As above.
