n8n-nodes-matrix42 0.1.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 S&S Technologies GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,111 @@
+# 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](https://n8n.io/) is a [fair-code licensed](https://docs.n8n.io/reference/license/) workflow automation platform.
+
+[Installation](#installation)  
+[Operations](#operations)  
+[Credentials](#credentials)
+[Compatibility](#compatibility)  
+[Resources](#resources)  
+[Version history](#version-history)  
+
+## Installation
+
+Follow the [installation guide](https://docs.n8n.io/integrations/community-nodes/installation/) in the n8n community nodes documentation.
+
+## Operations
+
+This node supports multiple operations across different resources:
+
+### Data Fragments (asql)
+
+-   **Get Fragments** (`getFragments`): Retrieve data fragments from a specified Data Definition.
+
+-   **Add Fragment** (`addFragment`): Create a new data fragment in the specified Data Definition.
+
+-   **Update Fragment** (`updateFragment`): Update an existing data fragment by its ID.
+
+-   **Delete Fragment** (`deleteFragment`): Remove a data fragment by its ID.
+
+
+### Data Objects (asql)
+
+-   **Add Object** (`addObject`): Create a new Data Object under a given fragment.
+
+-   **Get Object** (`getObject`): Retrieve a Data Object by its ID.
+
+-   **Update Object** (`updateObject`): Update an existing Data Object by its ID.
+
+-   **Delete Object** (`deleteObject`): Delete a Data Object by its ID.
+
+
+### Tickets
+
+-   **Create Ticket** (`createTicket`): Open a new ticket in the Service Desk.
+
+-   **Close Ticket** (`closeTicket`): Close an existing ticket by ID.
+
+-   **Transform Ticket** (`transformTicket`): Apply a transformation to a ticket.
+
+
+### Import
+
+-   **Execute Import Definition** (`executeImportDefinition`): Run a predefined import definition to ingest data.
+
+## 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 Token Auth
+
+1.  **API Token** — Your long‑lived Matrix42 API Token.
+
+2.  **Base URL** — Your Matrix42 server URL (e.g. `https://api.mycompany.com`).
+
+
+On execution, the node:
+
+-   Exchanges the API Token for a short‑lived Bearer (JWT) token via `GenerateAccessTokenFromApiToken`.
+
+-   Uses the Bearer token in the `Authorization` header for all subsequent calls.
+
+
+> **Self‑signed certificates**: If your Matrix42 server uses a self‑signed SSL certificate, you must add its CA certificate to n8n’s trusted certificate store. For details, see the n8n docs on adding self‑signed certificates: https://docs.n8n.io/hosting/configuration/configuration-examples/custom-certificate-authority/
+
+### Matrix42 Basic Auth
+
+1.  **Username** and **Password** — Your Matrix42 user credentials.
+
+2.  **Base URL** — As above.
+
+## Compatibility
+
+-   **n8n**: Tested with v1.100.1 and later.
+
+-   **Node.js**: v22.17.0 or higher.
+
+-   **Matrix42 ESMP API**: Tested with Matrix42 12.1.2.5325
+
+## Resources
+
+* [n8n community nodes documentation](https://docs.n8n.io/integrations/#community-nodes)
+* [Matrix42 Web Services](https://help.matrix42.com/030_ESMP/030_INT/Business_Processes_and_API_Integrations/Matrix42_Web_Services_API#Public_API)
+
+## Version History
+
+**0.1.0:**
+  - Initial release supporting operations across multiple resources:
+    -   Data Fragments: `getFragments`, `addFragment`, `updateFragment`, `deleteFragment`
+    -   Data Objects: `addObject`, `getObject`, `updateObject`, `deleteObject`
+    -   Tickets: `createTicket`, `closeTicket`, `transformTicket`
+    -   Import: `executeImportDefinition`
+
+  - Authentication methods:
+    -   Matrix42 Token API (API Token ↔︎ Bearer JWT exchange)
+    -   Matrix42 Basic API (HTTP Basic Authentication)

package/dist/credentials/Matrix42BasicApi.credentials.d.ts

@@ -0,0 +1,10 @@
+import { IAuthenticateGeneric, ICredentialTestRequest, ICredentialType, INodeProperties } from 'n8n-workflow';
+export declare class Matrix42BasicApi implements ICredentialType {
+    name: string;
+    extends: string[];
+    displayName: string;
+    documentationUrl: string;
+    properties: INodeProperties[];
+    authenticate: IAuthenticateGeneric;
+    test: ICredentialTestRequest;
+}

package/dist/credentials/Matrix42BasicApi.credentials.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Matrix42BasicApi = void 0;
+class Matrix42BasicApi {
+    constructor() {
+        this.name = 'matrix42BasicApi';
+        this.extends = ['httpBasicAuth'];
+        this.displayName = 'Matrix42 Basic Auth API';
+        this.documentationUrl = 'https://help.matrix42.com/030_ESMP/030_INT/Business_Processes_and_API_Integrations/Web_Services%3A_Authentication_types';
+        this.properties = [
+            {
+                displayName: 'Server URL',
+                name: 'serverUrl',
+                type: 'string',
+                default: '',
+                hint: 'The URL of the Matrix42 server. (https://www.example-matrix42.com)',
+                required: true,
+            },
+            {
+                displayName: 'User',
+                name: 'user',
+                type: 'string',
+                required: true,
+                default: '',
+            },
+            {
+                displayName: 'Password',
+                name: 'password',
+                type: 'string',
+                required: true,
+                typeOptions: {
+                    password: true,
+                },
+                default: '',
+            },
+        ];
+        this.authenticate = {
+            type: 'generic',
+            properties: {
+                auth: {
+                    username: '={{$credentials.user}}',
+                    password: '={{$credentials.password}}',
+                },
+            },
+        };
+        this.test = {
+            request: {
+                baseURL: '={{$credentials?.serverUrl}}',
+                url: '/m42Services/api/configuration/isdevelopermode',
+                skipSslCertificateValidation: true,
+            },
+        };
+    }
+}
+exports.Matrix42BasicApi = Matrix42BasicApi;
+//# sourceMappingURL=Matrix42BasicApi.credentials.js.map

package/dist/credentials/Matrix42BasicApi.credentials.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Matrix42BasicApi.credentials.js","sourceRoot":"","sources":["../../credentials/Matrix42BasicApi.credentials.ts"],"names":[],"mappings":";;;AAOA,MAAa,gBAAgB;IAA7B;QACC,SAAI,GAAG,kBAAkB,CAAC;QAE1B,YAAO,GAAG,CAAC,eAAe,CAAC,CAAC;QAE5B,gBAAW,GAAG,yBAAyB,CAAC;QAExC,qBAAgB,GAAG,yHAAyH,CAAC;QAE7I,eAAU,GAAsB;YAC/B;gBACC,WAAW,EAAE,YAAY;gBACzB,IAAI,EAAE,WAAW;gBACjB,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE,EAAE;gBACX,IAAI,EAAE,oEAAoE;gBAC1E,QAAQ,EAAE,IAAI;aACd;YACD;gBACC,WAAW,EAAE,MAAM;gBACnB,IAAI,EAAE,MAAM;gBACZ,IAAI,EAAE,QAAQ;gBACd,QAAQ,EAAE,IAAI;gBACd,OAAO,EAAE,EAAE;aACX;YACD;gBACC,WAAW,EAAE,UAAU;gBACvB,IAAI,EAAE,UAAU;gBAChB,IAAI,EAAE,QAAQ;gBACd,QAAQ,EAAE,IAAI;gBACd,WAAW,EAAE;oBACZ,QAAQ,EAAE,IAAI;iBACd;gBACD,OAAO,EAAE,EAAE;aACX;SACD,CAAC;QAEF,iBAAY,GAAyB;YACpC,IAAI,EAAE,SAAS;YACf,UAAU,EAAE;gBACX,IAAI,EAAE;oBACL,QAAQ,EAAE,wBAAwB;oBAClC,QAAQ,EAAE,4BAA4B;iBACtC;aACD;SACD,CAAC;QAEF,SAAI,GAA2B;YAC9B,OAAO,EAAE;gBACR,OAAO,EAAE,8BAA8B;gBACvC,GAAG,EAAE,gDAAgD;gBACrD,4BAA4B,EAAE,IAAI;aAClC;SACD,CAAC;IACH,CAAC;CAAA;AAtDD,4CAsDC"}

package/dist/credentials/Matrix42TokenApi.credentials.d.ts

@@ -0,0 +1,12 @@
+import { IAuthenticateGeneric, ICredentialDataDecryptedObject, ICredentialTestRequest, ICredentialType, IHttpRequestHelper, INodeProperties } from 'n8n-workflow';
+export declare class Matrix42TokenApi implements ICredentialType {
+    name: string;
+    displayName: string;
+    documentationUrl: string;
+    properties: INodeProperties[];
+    preAuthentication(this: IHttpRequestHelper, credentials: ICredentialDataDecryptedObject): Promise<{
+        accessToken: string;
+    }>;
+    authenticate: IAuthenticateGeneric;
+    test: ICredentialTestRequest;
+}

package/dist/credentials/Matrix42TokenApi.credentials.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Matrix42TokenApi = void 0;
+class Matrix42TokenApi {
+    constructor() {
+        this.name = 'matrix42TokenApi';
+        this.displayName = 'Matrix42 Webservice Token Auth API';
+        this.documentationUrl = 'https://help.matrix42.com/030_ESMP/030_INT/Business_Processes_and_API_Integrations/Web_Services%3A_Authentication_types';
+        this.properties = [
+            {
+                displayName: 'Access Token',
+                name: 'accessToken',
+                type: 'hidden',
+                typeOptions: {
+                    expirable: true,
+                    password: true,
+                },
+                default: '',
+            },
+            {
+                displayName: 'Server URL',
+                name: 'serverUrl',
+                type: 'string',
+                default: '',
+                hint: 'The URL of the Matrix42 server. (https://www.example-matrix42.com)',
+                required: true,
+            },
+            {
+                displayName: 'Webservice Token',
+                name: 'webserviceToken',
+                type: 'string',
+                typeOptions: {
+                    password: true
+                },
+                default: '',
+                hint: 'The Webservice token of the Matrix42 server.',
+                required: true,
+            },
+        ];
+        this.authenticate = {
+            type: 'generic',
+            properties: {
+                headers: {
+                    Authorization: '=Bearer {{$credentials.accessToken}}',
+                },
+            },
+        };
+        this.test = {
+            request: {
+                method: "GET",
+                baseURL: '={{$credentials?.serverUrl}}',
+                url: '/m42Services/api/configuration/isdevelopermode',
+                skipSslCertificateValidation: true
+            },
+        };
+    }
+    async preAuthentication(credentials) {
+        const { RawToken } = (await this.helpers.httpRequest({
+            method: 'POST',
+            url: `${credentials.serverUrl}/m42Services/api/ApiToken/GenerateAccessTokenFromApiToken`,
+            skipSslCertificateValidation: true,
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${credentials.webserviceToken}`,
+            },
+        }));
+        return { accessToken: RawToken };
+    }
+}
+exports.Matrix42TokenApi = Matrix42TokenApi;
+//# sourceMappingURL=Matrix42TokenApi.credentials.js.map

package/dist/credentials/Matrix42TokenApi.credentials.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Matrix42TokenApi.credentials.js","sourceRoot":"","sources":["../../credentials/Matrix42TokenApi.credentials.ts"],"names":[],"mappings":";;;AAOA,MAAa,gBAAgB;IAA7B;QACC,SAAI,GAAG,kBAAkB,CAAC;QAE1B,gBAAW,GAAG,oCAAoC,CAAC;QAEnD,qBAAgB,GAAG,yHAAyH,CAAC;QAE7I,eAAU,GAAsB;YAC/B;gBACC,WAAW,EAAE,cAAc;gBAC3B,IAAI,EAAE,aAAa;gBACnB,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE;oBACZ,SAAS,EAAE,IAAI;oBACf,QAAQ,EAAE,IAAI;iBACd;gBACD,OAAO,EAAE,EAAE;aACX;YACD;gBACC,WAAW,EAAE,YAAY;gBACzB,IAAI,EAAE,WAAW;gBACjB,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE,EAAE;gBACX,IAAI,EAAE,oEAAoE;gBAC1E,QAAQ,EAAE,IAAI;aACd;YACD;gBACC,WAAW,EAAE,kBAAkB;gBAC/B,IAAI,EAAE,iBAAiB;gBACvB,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE;oBACZ,QAAQ,EAAE,IAAI;iBACd;gBACD,OAAO,EAAE,EAAE;gBACX,IAAI,EAAE,8CAA8C;gBACpD,QAAQ,EAAE,IAAI;aACd;SACD,CAAC;QAeF,iBAAY,GAA0B;YACrC,IAAI,EAAE,SAAS;YACf,UAAU,EAAE;gBACX,OAAO,EAAE;oBACR,aAAa,EAAE,sCAAsC;iBACrD;aACD;SACD,CAAC;QAEF,SAAI,GAA2B;YAC9B,OAAO,EAAE;gBACR,MAAM,EAAE,KAAK;gBACb,OAAO,EAAE,8BAA8B;gBACvC,GAAG,EAAE,gDAAgD;gBACrD,4BAA4B,EAAE,IAAI;aAClC;SACD,CAAC;IACH,CAAC;IA9BA,KAAK,CAAC,iBAAiB,CAA2B,WAA2C;QAC5F,MAAM,EAAE,QAAQ,EAAE,GAAG,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC;YACpD,MAAM,EAAE,MAAM;YACd,GAAG,EAAE,GAAG,WAAW,CAAC,SAAS,2DAA2D;YACxF,4BAA4B,EAAE,IAAI;YAClC,OAAO,EAAE;gBACR,cAAc,EAAE,kBAAkB;gBAClC,eAAe,EAAE,UAAU,WAAW,CAAC,eAAe,EAAE;aACxD;SACD,CAAC,CAAyB,CAAC;QAC5B,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,CAAC;IAClC,CAAC;CAmBD;AArED,4CAqEC"}

package/dist/nodes/Matrix42/GenericFunctions.d.ts

@@ -0,0 +1,3 @@
+import { IDataObject, IExecuteFunctions, IHookFunctions, IHttpRequestMethods, ILoadOptionsFunctions } from 'n8n-workflow';
+export declare function matrix42ApiRequest(this: IHookFunctions | IExecuteFunctions | ILoadOptionsFunctions, method: IHttpRequestMethods, endpoint: `/${string}`, body: object, query?: IDataObject, uri?: string): Promise<any>;
+export declare function uuidv4(): string;

package/dist/nodes/Matrix42/GenericFunctions.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.matrix42ApiRequest = matrix42ApiRequest;
+exports.uuidv4 = uuidv4;
+async function matrix42ApiRequest(method, endpoint, body, query, uri) {
+    const authenticationMethod = this.getNodeParameter('authentication', 0);
+    const credentialType = authenticationMethod === 'basic' ? 'matrix42BasicApi' : 'matrix42TokenApi';
+    const { serverUrl } = await this.getCredentials(credentialType);
+    const options = {
+        headers: {},
+        method,
+        body: method === 'GET' || method === 'HEAD' || method === 'DELETE' ? null : body,
+        qs: query,
+        url: uri || `${serverUrl}/m42Services/api${endpoint}`,
+        json: true,
+        skipSslCertificateValidation: true
+    };
+    if (options.body === null) {
+        delete options.body;
+    }
+    return await this.helpers.requestWithAuthentication.call(this, credentialType, options);
+}
+function uuidv4() {
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, c => {
+        const r = (Math.random() * 16) | 0;
+        const v = c === 'x' ? r : (r & 0x3) | 0x8;
+        return v.toString(16);
+    });
+}
+//# sourceMappingURL=GenericFunctions.js.map

package/dist/nodes/Matrix42/GenericFunctions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GenericFunctions.js","sourceRoot":"","sources":["../../../nodes/Matrix42/GenericFunctions.ts"],"names":[],"mappings":";;AAOA,gDA4BC;AAED,wBAMC;AApCM,KAAK,UAAU,kBAAkB,CAEvC,MAA2B,EAC3B,QAAsB,EACtB,IAAY,EACZ,KAAmB,EACnB,GAAY;IAGZ,MAAM,oBAAoB,GAAG,IAAI,CAAC,gBAAgB,CAAC,gBAAgB,EAAE,CAAC,CAAW,CAAC;IAClF,MAAM,cAAc,GAAG,oBAAoB,KAAK,OAAO,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC,CAAC,kBAAkB,CAAC;IAClG,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,IAAI,CAAC,cAAc,CAAwB,cAAc,CAAC,CAAC;IAEvF,MAAM,OAAO,GAAwB;QACpC,OAAO,EAAE,EAAE;QACX,MAAM;QACN,IAAI,EAAE,MAAM,KAAK,KAAK,IAAI,MAAM,KAAK,MAAM,IAAI,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI;QAChF,EAAE,EAAE,KAAK;QACT,GAAG,EAAE,GAAG,IAAI,GAAG,SAAS,mBAAmB,QAAQ,EAAE;QACrD,IAAI,EAAE,IAAI;QACV,4BAA4B,EAAE,IAAI;KAClC,CAAC;IAEF,IAAI,OAAO,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;QAC3B,OAAO,OAAO,CAAC,IAAI,CAAC;IACrB,CAAC;IAEA,OAAO,MAAM,IAAI,CAAC,OAAO,CAAC,yBAAyB,CAAC,IAAI,CAAC,IAAI,EAAE,cAAc,EAAE,OAAO,CAAC,CAAC;AAC1F,CAAC;AAED,SAAgB,MAAM;IACrB,OAAO,sCAAsC,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE;QAClE,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC;QACnC,MAAM,CAAC,GAAG,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC;QAC1C,OAAO,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IACvB,CAAC,CAAC,CAAC;AACJ,CAAC"}

package/dist/nodes/Matrix42/Matrix42.node.d.ts

@@ -0,0 +1,19 @@
+import { IExecuteFunctions, ILoadOptionsFunctions, INodeExecutionData, INodePropertyOptions, INodeType, INodeTypeDescription } from 'n8n-workflow';
+export declare class Matrix42 implements INodeType {
+    description: INodeTypeDescription;
+    methods: {
+        loadOptions: {
+            getUsers(this: ILoadOptionsFunctions): Promise<INodePropertyOptions[]>;
+            getTicketUrgencies(this: ILoadOptionsFunctions): Promise<INodePropertyOptions[]>;
+            getTicketImpacts(this: ILoadOptionsFunctions): Promise<INodePropertyOptions[]>;
+            getTicketCategories(this: ILoadOptionsFunctions): Promise<INodePropertyOptions[]>;
+            getTicketRoles(this: ILoadOptionsFunctions): Promise<INodePropertyOptions[]>;
+            getTicketSlas(this: ILoadOptionsFunctions): Promise<INodePropertyOptions[]>;
+            getTicketOlas(this: ILoadOptionsFunctions): Promise<INodePropertyOptions[]>;
+            getTicketCloseReasons(this: ILoadOptionsFunctions): Promise<INodePropertyOptions[]>;
+            getTicketCloseErrorTypes(this: ILoadOptionsFunctions): Promise<INodePropertyOptions[]>;
+            getImportDefinitions(this: ILoadOptionsFunctions): Promise<INodePropertyOptions[]>;
+        };
+    };
+    execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]>;
+}