Adding & testing custom scripts

Introduction

This page explains how to add a custom script for payload transformations. You will create a new script, add your code using IntelliSense, and then save changes ready for testing. Adding a new custom script can be broken down into three distinct stages:

1. Create a new script

2. Add script code

3. Test script code

This page walks through creating and testing a new script. We'll be adding a Javascript (node 18) script to change email addresses in a given payload to [email protected]. If you'd like to try this yourself, our script and test payload are available below.

Sample script & test payload

Script code (javascript node 18)

module.exports = async function (data) {
    const payload = JSON. parse (data.payload);

   if (payload.customers) {
     payload.customers.forEach(customer => {
         customer.email = '[email protected]';
      })
    }

    return { "payload": JSON.stringify(payload) };
};

Test payload (customers)

[
    {
        "id": 1000000001,
        "first_name": "Britney",
        "last_name": "Spears",
        "email": "[email protected]"
    },
    {
        "id": 1000000002,
        "first_name": "Madonna",
        "last_name": "Ciccone",
        "email": "[email protected]"
    },
    {
        "id": 1000000003,
        "first_name": "Elvis",
        "last_name": "Presley",
        "email": "[email protected]"
    }
]

Need to know

• The maximum memory size for a custom script is 512MB

• The maximum size of a custom script is 4GB

Creating a new script

Follow the steps below:

Step 1 Log into the Patchworks dashboard and select scripts from the left-hand navigation bar.

If you use process flows to sync data, you'll find this option under process flows. If you use services to sync data, you'll find this option under services.

Step 2 Select the create script button from the scripts page:

Alternatively, you can click the title of an existing script in the upper 'installed' panel, to make changes to a script that you've already added or installed.

Step 3 Add a unique name and a description for your script, then choose your preferred coding language:

Script names must be unique - you can't add two scripts with exactly the same name.

Step 4 Click the create button. The new script is saved and you're now in edit mode, ready to add and test your code:

Adding your code

Follow the steps below:

Step 1 Move down to the code panel.

Step 2 Add your script code (remember that you can use IntelliSense for easy code entry) - for example:

Step 3 When you're ready to test the script, click the save and deploy button:

This saves the code and deploys it to Patchworks, ready for testing/use.

Testing your script

Follow the steps below:

Step 1 Move across to the test panel.

Step 2 Add/paste a payload that can be used to test your script - for example:

Step 3 If your script references variables or flow variables, you can also add variables for testing:

Step 4 Click the run button:

...the script runs against your test payload and results are displayed at the end - for example:

For more detailed information about a script test, you can get logs:

...current logs are displayed:

Step 5 Keep testing the script until you're satisfied that it's working as required.

Any time that you make a change to the script and want to test it, always save and deploy the code first. When you run a script, it always uses the last saved version.

Once these tests are complete, what you do next depends on whether you use process flows or services to sync data.

If you use process flows, you can:

• Apply a payload-level script to process flows via the script shape

• Apply a field-level custom script to field transformations via the map shape

If you use services, you can:

• Apply a payload-level script to services via the service payload script tab

• Apply a field-level custom script to field transformations via the service mapping tab