# Using a payload-level custom script in services

## Introduction

This page explains how to [associate a payload-level custom script with a service](#associating-a-payload-level-script-with-a-service), then [run the service and check input and output payloads](#running-the-service-and-checking-payloads).

{% hint style="danger" %}
If this is the first time you are using this script, you are strongly advised to work with a test service and ensure everything syncs as expected before applying to live services.&#x20;

In Patchworks, a test service can be created by defining **test** (rather than **live**) source and destination connectors which point to sandbox URLs for the associated systems.
{% endhint %}

## Associating a payload-level script with a service

**Step 1**\
Use the **services** option to access an existing service that you'd like to [update](https://doc.wearepatchworks.com/product-documentation/patchworks-services/working-with-services/updating-a-service), or [add a new service](https://doc.wearepatchworks.com/product-documentation/patchworks-services/working-with-services/adding-a-patchworks-service): \
\
&#x20;![](https://content.gitbook.com/content/5mpqoXPMbUuPa8JpCLWe/blobs/DK6oqtjhL0MBQKN7onCW/services%20option.png)

**Step 2**\
If at least one **payload-level** custom script has been added, a **payload script** tab is available - select it:

<figure><img src="https://content.gitbook.com/content/5mpqoXPMbUuPa8JpCLWe/blobs/GvzEv0q3UG60XY135CuV/payload%20script%20tab.png" alt=""><figcaption></figcaption></figure>

**Step 3**\
Click the **select custom script** field and choose the script that you wish to associate with this service - for example:

<figure><img src="https://content.gitbook.com/content/5mpqoXPMbUuPa8JpCLWe/blobs/WfhMxHWMtLN3fKfM9r0G/choose%20script.png" alt=""><figcaption></figcaption></figure>

**Step 4**\
Details for the selected script are displayed:

<figure><img src="https://content.gitbook.com/content/5mpqoXPMbUuPa8JpCLWe/blobs/EnuyKTXFpndYTMOkZYBH/script%20details.png" alt=""><figcaption></figcaption></figure>

You don't need to do anything here - everything is ready to go. However, if you wish to update the script, click the **modify this script** button to edit the script in the [manage custom scripts](https://doc.wearepatchworks.com/product-documentation/patchworks-services/working-with-services/updating-a-service/broken-reference) area. &#x20;

{% hint style="info" %}
If a script is associated with a service and subsequently edited and saved, changes are applied to associated services automatically.
{% endhint %}

**Step 5**\
Use the **add script to service** button to apply changes.&#x20;

## Running the service & checking payloads

**Step 1**\
Select the **run service** tab:

<figure><img src="https://content.gitbook.com/content/5mpqoXPMbUuPa8JpCLWe/blobs/G4uXe8jBrpHklVXkLTkN/choose%20run%20service.png" alt=""><figcaption></figcaption></figure>

**Step 2**\
Scroll down to the **service options** section and toggle on the **store custom script payloads** setting: &#x20;

<figure><img src="https://content.gitbook.com/content/5mpqoXPMbUuPa8JpCLWe/blobs/YcbmSDxjtsWyLobEpFx8/store%20custom%20script%20payloads.png" alt=""><figcaption></figcaption></figure>

**Step 3**\
Set all other options as required and run the service:

<figure><img src="https://content.gitbook.com/content/5mpqoXPMbUuPa8JpCLWe/blobs/m15fXeRoap3g4FmI4c5O/run%20service%20with%20payload%20script.png" alt=""><figcaption></figcaption></figure>

**Step 4**\
As the service runs, custom script activity is displayed in the the **custom scripts logs** section of the service log - for example:

<figure><img src="https://content.gitbook.com/content/5mpqoXPMbUuPa8JpCLWe/blobs/ZQGopSJobmImeT5P3NTq/custom%20script%20logs%20from%20service.png" alt=""><figcaption></figcaption></figure>

**Step 5**\
When the service run is complete and you opted to download custom script payloads, you can download these files using buttons in the custom script payload panel:

<figure><img src="https://content.gitbook.com/content/5mpqoXPMbUuPa8JpCLWe/blobs/4v4mWDYhzyS1MmEbo1ju/download%20custom%20script%20payloads.png" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
If you forget to download files at this point, a download link will be available in the [service log](https://doc.wearepatchworks.com/product-documentation/patchworks-services/reporting-and-logging/service-sync-logs) for 24 hours. For example:

![](https://content.gitbook.com/content/5mpqoXPMbUuPa8JpCLWe/blobs/Oozt0uSpVnWqnFyAUE18/download%20payload%20example.png)
{% endhint %}

{% hint style="info" %}
When a **payload-level** custom script is associated with a service, an **edit script** option is available on the service canvas. For example:

![](https://content.gitbook.com/content/5mpqoXPMbUuPa8JpCLWe/blobs/fndJvC7KjMRR0f2Xh8u9/edit%20script%20-%20canvas.png)
{% endhint %}
