Nodejs22

This feature is only enabled on certain environments and tenants. Contact support for more information about this feature.

With this transform type, you can customize the request and response with access to Node.js v22 to program actions for each call to the transform endpoint in JavaScript.

We recommend this transform type if you have complex requirements involving multiple API calls. Some examples of how this could be used include:

• Combine multiple Execute API calls together.

• Apply JSONtransforms for multiple API calls.

• Orchestrate other Spark APIs to facilitate data transformation and processing.

• Make external API calls.

• Develop tools that are not even Spark related.

For this particular transform type, the npm packages for fast-xml-parser and jsonata are available for enhanced JSON and XML parsing and composition.

Transform document

Transform documents are used to define the code relating to a transform. For Nodejs22, the transform document is a JSON document defined by the following objects:

Key	Value
transform_type	Nodejs22_v1.0.0
transform_code	Single string containing the code for the transform code. The code must contain the function async function handler(event) {}. When the transform is invoked, this function is called. Parameters from the transform request are passed into the event parameter as an object. This function should return: http_status_code for the HTTP status code. headers for response headers. body for the response body. This design pattern follows the AWS Lambda Define Lambda function handler in Node.js.
transform_log_level	Optional parameter. This controls the level of logging that will be recorded during the execution. This can take the values of TRACE, DEBUG, INFO, WARN, ERROR.
transform_log_visible	NOTE: This configuration is not available yet. Optional parameter. This controls whether the execution logs will be made available in a link through the response headers. These can be used for reviewing the execution and debugging. If omitted, the default is false.
transform_allowed_external_domains	Optional parameter. Array containing a list of external domains that the transform is allowed to access during the course of execution. These domains must be resolvable using NsLookup.

Create the transform document

The transform document can be manually created and uploaded to Spark using the New transforms feature.

1. The transform_type is Nodejs22_v1.0.0.

2. The transform_code must be a single string containing the code for the transform.

   1. If you are using either fast-xml-parser or jsonata, make sure to include the require() statements to import the modules the respective modules.

   2. Remove any lines containing comments.

   3. Any double quotation marks " need to be escaped where " is replaced with \".

      • Note that JavaScript allows for single quotation marks ' to be interchanged with double quotation marks ". If ' are used exclusively in lieu of ", then the escape character is not needed.

   4. If you are using Visual Studio Code, you can use the Join lines feature to make it easy to combine multiple lines into a single string.

      1. Select the transform text that you would like to combine onto a single line.

         1. Access the Command Palette with the keyboard shortcut F1 or Ctrl+Shift+P on Windows or Shift+⌘+P on Mac.

         2. Type in the command Join lines and select it.

   5. As an alternative to Join lines, line breaks Ctrl+Enter can be replaced with the new line character \n.

3. Save the document as a JSON file. The filename must end with _transform.json.

4. Follow the instructions in Folder overview to upload the transform document to Spark.

Sample transform document

{
  "transform_type": "Nodejs22_v1.0.0",
  "transform_code": "async function handler(event) { return { http_status_code: 200, headers: { \"Content-Type\": \"application/json\", myresponseheader: \"Hello, World!\", }, body: { myresponsebody: \"Hello, World!\", }, } }"
}

Transforms API

# Transform document applies to a specific Spark service
POST /{tenant}/api/v4/transforms/{transform_folder}/{transform}/for/{folder}/{service}
# Transform document does not apply to a specific Spark service
POST /{tenant}/api/v4/transforms/{transform_folder}/{transform}/run

Authorization

• Bearer {token} accessible from Authorization - Bearer token or systematically via Client credentials.

  • The request headers should include a key for Authorization with the value Bearer {token}.

• API key created from Authorization - API keys.

  • The request headers should include the keys x-synthetic-key and x-tenant-name with the values of the API key and tenant name respectively.

Note that the authorization must include permissions that can access:

• The requested Spark service.

• The requested transform.

  • Either the folder that the transform is stored OR

  • If the transform is in the apps/transforms folder. This would typically require user:pf or supervisor:pf.

Path parameters

Key	Value
tenant *	Tenant is part of your sign-in URL and also available in the User menu.
transform_folder *	Folder associated with the transform document of the request.
transform *	Transform document associated with the transform document of the request (without _transform.json).
folder *	Folder associated with the Spark service of the request.
service *	Service associated with the Spark service of the request.

Request headers

Key	Value
x-meta or x-request-meta	Optional parameter. This can be used to introduce key-value pairs into the event.context parameter object. See Examine the event parameter objectfor more details. Example: "{\"call_purpose\":\"Transform mainframe request\"}"
Content-Type	application/json, application/xml, or text/xml
+ any other request headers...	These will be passed into event.request.headers as key-value pairs. See Examine the event parameter objectfor more details.

Request body

Content-Type: application/json or Content-Type: application/xml

HTTP status code

This is determined by the handler() function return{} of http_status_code object.

This can also be defined with a response header x-spark-transform-response-httpstatuscode .

Response headers

This is determined by the handler() function return{} of the headers() object. We would suggest at the minimum to return the appropriate Content-Type for your response data.

Response body

This is determined by the handler() function return{} of the body() object.

Limitations

• The API call has a maximum lifetime of 120 s.

• API calls can only be made to the coherent.global domain unless defined by transform_allowed_external_domains.

Restricted Node.js v22 modules

Restricted module	Restricted functionality
fs	Read/write access to the file system.
child_process	Run arbitrary system commands (exec, spawn, etc.).
net / dgram	Create raw TCP/UDP sockets.
http, https	Make network requests. Use fetch instead.
vm	Create a nested sandbox.
process	Access environment variables or exit the process.
os	Access system information.
cluster	Fork additional worker processes.
worker_threads	Run threads outside of the memory or sandbox space.
require (general)	Loading of unsupported modules.

Known errors

Sometimes code will work locally but fail to run on Spark. Some examples where this may occur:

• If you try to return all of the headers from the /execute API call Emulate a passthrough to the Execute API (v3) to the /transforms response headers, it may fail due to content encoding discrepancies.

Examples

Start with a Hello, World! transform

The response includes a custom header and response body with the message Hello, World!.

JavaScript

async function handler(event) {
    return {
        http_status_code: 200,
        headers: {
            "Content-Type": "application/json",
            myresponseheader: "Hello, World!",
        },
        body:
            {
                myresponsebody: "Hello, World!",
            },
    }
}

Transform document

{
  "transform_type": "Nodejs22_v1.0.0",
  "transform_code": "async function handler(event) { return { http_status_code: 200, headers: { \"Content-Type\": \"application/json\", myresponseheader: \"Hello, World!\", }, body: { myresponsebody: \"Hello, World!\", }, } }"
}

HelloWorld_transform.json

269B

Open

Sample request

• The request is made to the transform mytransformsfolder/HelloWorld.

• The /run endpoint is called because this does not relate to a particular service.

curl --location 'https://excel.myenvironment.coherent.global/mytenant/api/v4/transforms/mytransformsfolder/HelloWorld/run' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {token}' \
--data ''

Sample response

HTTP 200 OK Content-Type: application/json

{
    "myresponsebody": "Hello, World!"
}

Examine the event parameter object

When the handler() function is called, the event parameter is used to get information about the request details. These can be used as inputs for the program.

JavaScript

async function handler(event) {
    return {
        http_status_code: 200,
        headers: { "Content-Type": "application/json" },
        body: { event }
    };
}

Transform document

{
  "transform_type": "Nodejs22_v1.0.0",
  "transform_code": "async function handler(event) { return { http_status_code: 200, headers: { \"Content-Type\": \"application/json\" }, body: { event } }; }"
}

EventViewer_transform.json

202B

Open

Sample request

• The request is made to the transform mytransformsfolder/EventViewer.

• The /run endpoint is called because this does not relate to a particular service.

curl --location 'https://excel.myenvironment.coherent.global/mytenant/api/v4/transforms/mytransformsfolder/EventViewer/for/myfolder/myservice' \
--header 'Content-Type: application/json' \
--header 'myrequestheaderkey: myrequestheadervalue' \
--header 'x-meta: "{\"call_purpose\":\"Event viewer\"}"' \
--header 'Authorization: Bearer {Token}' \
--data '{
    "request_data": {
        "inputs": {
            "A": 1,
            "B": 2
        }
    }
}'

Sample response

HTTP 200 OK Content-Type: application/json

{
    "event": {
        "request": {
            "body": {
                "request_data": {
                    "inputs": {
                        "A": 1,
                        "B": 2
                    }
                }
            },
            "headers": {
                "Accept": "*/*",
                "Host": "excel.myenvironment.coherent.global",
                "User-Agent": "curl/7.88.1",
                "Accept-Encoding": "gzip, deflate, br",
                "Authorization": "Bearer {Token}",
                "Content-Type": "application/json",
                "Content-Length": 107,
                "X-Forwarded-For": "129.6.15.28",
                "X-Forwarded-Proto": "https",
                "X-Forwarded-Port": 443,
                "X-Trace-Id": "Root=1-6839b403-09c360963bf7aec943477e9g",
                "myrequestheaderkey": "myrequestheadervalue",
                "x-meta": "{\"call_purpose\":\"Event viewer\",\"correlation_id\":\"91496134-6357-4bc7-a230-f9ad31855254\"}"
            }
        },
        "whitelisted_domains": [
            "*.coherent.global"
        ],
        "total_allowed_run_time_ms": 60000,
        "context": {
            "tenant": "coherent",
            "service_uri": "/folders/myfolder/services/myservice",
            "call_purpose": "Event viewer",
            "correlation_id": "91496134-6357-4bc7-a230-f9ad31855254",
            "spark_url": "https://excel.myenvironment.coherent.global",
            "log_level": ""
        },
        "secrets": {
            "authorization": "Bearer {Token}"
        }
    }
}

Emulate a passthrough to the Execute API (v3)

The transform endpoint acts as a passthrough to send inputs to the Execute API (v3). USe this to build transforms that make API calls to Spark.

JavaScript

• Note the encodeURI() function that is used in the fetchResource declaration. This is needed because folders or services that contain a space in the name need to be encoded to %20 in order for fetch() to work.

• The Authorization to the /execute API call is handled by using the token available in event.secrets.authorization.

• Trying to return all of the headers from the /execute call may lead to errors. See Known errors.

async function handler(event) {

    const fetchResource = `${event.context.spark_url}/${event.context.tenant}/api/v3${encodeURI(event.context.service_uri)}/execute`;

    const fetchOptions = {
        method: "POST",
        headers: {
            Authorization: event.secrets.authorization,
            "Content-Type": "application/json",
            "x-tenant-name": event.context.tenant,
        },
        body: JSON.stringify(event.request.body),
    };

    const response = await fetch(fetchResource, fetchOptions);
    const responseBody = await response.json();

    return {
        http_status_code: response.status,
        headers: { "Content-Type": response.headers.get("content-type") },
        body: responseBody,
    };
}

Transform document

{
  "transform_type": "Nodejs22_v1.0.0",
  "transform_code": "async function handler(event) { const fetchResource = `${event.context.spark_url}/${event.context.tenant}/api/v3${encodeURI(event.context.service_uri)}/execute`; const fetchOptions = { method: \"POST\", headers: { Authorization: event.secrets.authorization, \"Content-Type\": \"application/json\", \"x-tenant-name\": event.context.tenant, }, body: JSON.stringify(event.request.body), }; const response = await fetch(fetchResource, fetchOptions); const responseBody = await response.json(); return { http_status_code: response.status, headers: { \"Content-Type\": response.headers.get(\"content-type\") }, body: responseBody, }; }"
}

v3Execute_transform.json

694B

Open

Sample request

• The request is made to the transform mytransformsfolder/EventViewer and the service myfoldername/AplusB.

• The endpoint includes a reference to myfolder/myservice which will be the target for this API call.

curl --location 'https://excel.myenvironment.coherent.global/mytenant/api/v4/transforms/mytransformsfolder/v3Execute/for/myfolder/myservice' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {token}' \
--data '{
    "request_data": {
        "inputs": {
            "A": 1,
            "B": 2
        }
    }
}'

Sample response

HTTP 200 OK Content-Type: application/json

{
    "status": "Success",
    "response_data": {
        "outputs": {
            "AplusB": 3
        },
        "warnings": null,
        "errors": null,
        "service_chain": null
    },
    "response_meta": {
        "service_id": "8b750c74-9e33-470f-8c2c-4173970112c7",
        "version_id": "cb577a09-12a6-412d-99d5-2b6a6aba794c",
        "version": "0.3.0",
        "process_time": 1,
        "call_id": "6798bf8e-1827-4cfd-ab0f-b3bef11adf02",
        "compiler_type": "Neuron",
        "compiler_version": "1.22.8",
        "source_hash": null,
        "engine_id": "C70FF0EF6EF466B551756ADE3289475B",
        "correlation_id": "",
        "parameterset_version_id": null,
        "system": "SPARK",
        "request_timestamp": "2025-05-29T11:07:51.132Z"
    },
    "error": null
}

Transform JSON with JSONata

JSONata is a "lightweight query and transformation language for JSON data". You can test your JSONata transforms in the JSONata Exerciser.

The jsonata package is included with the Nodejs22 transform to enable extensive JSON parsing capabilities. Note the jsonata package version used in Update roadmap.

Example is based on Example nodejs application.

JavaScript

const jsonata = require("jsonata");

async function handler(event) {
    const data = {
        example: [
            { value: 4 },
            { value: 7 },
            { value: 13 }
        ]
    };
    const expression = jsonata("$sum(example.value)");
    const result = await expression.evaluate(data);
    return { http_status_code: 200, headers: { "Content-Type": "application/json" }, body: { sum: result } };
}

Transform document

{
  "transform_type": "Nodejs22_v1.0.0",
  "transform_code": "const jsonata = require(\"jsonata\"); async function handler(event) { const data = { example: [ { value: 4 }, { value: 7 }, { value: 13 } ] }; const expression = jsonata(\"$sum(example.value)\"); const result = await expression.evaluate(data); return { http_status_code: 200, headers: { \"Content-Type\": \"application/json\" }, body: { sum: result } }; }"
}

jsonata_transform.json

420B

Open

Sample request

• The request is made to the transform mytransformsfolder/JSONata.

• The /run endpoint is called because this does not relate to a particular service.

curl --location 'https://excel.myenvironment.coherent.global/mytenant/api/v4/transforms/mytransformsfolder/JSONata/run' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {token}' \
--data ''

Sample response

HTTP 200 OK Content-Type: application/json

{
    "sum": 24
}

Transform XML with fast-xml-parser

fast-xml-parser is the most popular package to manipulate XML in JavaScript.

The package is included with the Nodejs22 transform to enable XML parsing capabilities. Note the fast-xml-parser package version used in Update roadmap.

This example is based on Builder_v1.md.

JavaScript

const fastXmlParser = require("fast-xml-parser");

async function handler(event) {
    const { XMLBuilder } = require("fast-xml-parser");

    const XmlBuilderOptions = {
        ignoreAttributes: false,
        format: true,
        arrayNodeName: "car"
    };

    const cars = [
        {
            "color": "purple",
            "type": "minivan",
            "registration": "2020-02-03",
            "capacity": 7
        },
        {
            "color": "orange",
            "type": "SUV",
            "registration": "2021-05-17",
            "capacity": 4
        },
    ];

    const builder = new XMLBuilder(XmlBuilderOptions);
    const output = builder.build(cars);

    return {
        http_status_code: 200,
        headers: {
            'Content-Type': 'application/xml'
        },
        body: output,
    };
}

Transform document

{
  "transform_type": "Nodejs22_v1.0.0",
  "transform_code": "const fastXmlParser = require(\"fast-xml-parser\"); async function handler(event) { const { XMLBuilder } = require(\"fast-xml-parser\"); const XmlBuilderOptions = { ignoreAttributes: false, format: false, arrayNodeName: \"car\" }; const cars = [ { \"color\": \"purple\", \"type\": \"minivan\", \"registration\": \"2020-02-03\", \"capacity\": 7 }, { \"color\": \"orange\", \"type\": \"SUV\", \"registration\": \"2021-05-17\", \"capacity\": 4 }, ]; const builder = new XMLBuilder(XmlBuilderOptions); const output = builder.build(cars); return { http_status_code: 200, headers: { 'Content-Type': 'application/xml' }, body: output, }; }"
}

XML_transform.json

697B

Open

Sample request

• The request is made to the transform mytransformsfolder/XML.

• The /run endpoint is called because this does not relate to a particular service.

curl --location 'https://excel.myenvironment.coherent.global/mytenant/api/v4/transforms/mytransformsfolder/XML/run' \
--header 'Content-Type: application/xml' \
--header 'Authorization: Bearer {token}' \
--data ''

Sample response

HTTP 200 OK Content-Type: application/xml

<car>
    <color>purple</color>
    <type>minivan</type>
    <registration>2020-02-03</registration>
    <capacity>7</capacity>
</car>
<car>
    <color>orange</color>
    <type>SUV</type>
    <registration>2021-05-17</registration>
    <capacity>4</capacity>
</car>

Make an external API call

Extract the contents from the www.google.com homepage.

JavaScript

async function handler(event) {

    const fetchResource = "https://www.google.com";
    const fetchOptions = {method: "GET"};

    const response = await fetch(fetchResource, fetchOptions);
    const responseText = await response.text();
    const responseBody = {outputs: { page_content: responseText } };
    return {
        http_status_code: response.status,
        headers: { "content-type": "application/json" },
        body: responseBody,
    };
}

Transform document

{
  "transform_type": "Nodejs22_v1.0.0",
  "transform_code": "async function handler(event) { const fetchResource = \"https://www.google.com\"; const fetchOptions = {method: \"GET\"}; const response = await fetch(fetchResource, fetchOptions); const responseText = await response.text(); const responseBody = {outputs: { page_content: responseText } }; return { http_status_code: response.status, headers: { \"content-type\": \"application/json\" }, body: responseBody, }; }",
  "transform_allowed_external_domains": ["www.google.com"]
}

HeyGoogle_transform.json

536B

Open

Sample request

• The request is made to the transform mytransformsfolder/HeyGoogle.

• The /run endpoint is called because this does not relate to a particular service.

curl --location 'https://excel.myenvironment.coherent.global/mytenant/api/v4/transforms/mytransformsfolder/HeyGoogle/run' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {token}' \
--data ''

Sample response

HTTP 200 OK Content-Type: application/json

{
    "outputs": {
        "page_content":"<!doctype html><html itemscope=\"\" itemtype=\"http://schema.org/WebPage\" lang=\"en-SG\"></html>"
    }
}

Developer tools

JavaScript developers can use the Node Transform Document Builder which facilitates the build and validation of transform documents.

Alternatively, you can use this method to run code locally if you have Node.js installed. This process similar to Building Lambda functions with Node.js.

1. Decide how you would like to construct the request to the /transforms endpoint, including the structure of the request line, as well as request and response headers and body.

2. Create the transform described in Examine the event parameter object. Run the proposed /transforms request against it and from the response copy the event object.

3. Test your script locally using the runHandler.js script below.

   1. Paste in the event object from above into TEST_EVENT of runHandler.js.

   2. Work on the handler() function in runHandler.js.

   3. If your script calls other Spark APIs, your Authorization may expire as you develop the program. You may need to update your event object periodically with a new bearer token.

   4. Test your script in your terminal using the command node runHandler.js. It will print the handler() function return.

4. Compose and upload the transform document using the directions in Transform document.

5. Test API calls against the /transforms endpoint to make sure you are getting the same result as the runHandler.js script.

runHandler.zip

archive · 1KB

Open