Introduction

The first stage of adding a new system is to provide basic details - these determine how your system will be presented throughout Patchworks,

What you need to do

Step 1 Having launched the connector builder, the basic details page is displayed - this is where you provide a name and other general details for your new connector:

Complete fields on this page using the table below as a guide:

Step 2 Having entered all required details, click the next step button for connector variables.

Introduction

With Patchworks, you can install and then use instances of prebuilt connectors, which are available from the Patchworks marketplace.

But what if there is no prebuilt connector for a business application that you want to integrate? Maybe you have a bespoke, in-house system - or perhaps you want to connect an application that's completely outside of the eCommerce arena.

The Patchworks connector builder enables you to build your own connectors, which can then be used in exactly the same way as the prebuilt connectors found in the Patchworks marketplace.

Who is it for?

The connector builder is designed to take away as much of the heavy lifting required to integrate systems from scratch, as possible - no coding is required!

If you're comfortable working with APIs and data structures, you can use the connector builder to integrate any application with an API.

In this section

• Accessing the connector builder

• Building your own connector

• Maintaining your own connectors

Introduction

The connector builder walks you through a series of configuration pages so you can complete all required setup that's needed to make your connector available in Patchworks.

Once your connector is built, it is displayed in the Patchworks marketplace, so users associated with your company profile can add instances of it.

Preparation

Before you start work with the connector builder, make sure that you have the API documentation to hand for whichever third-party application you're building.

We also recommend that you fire up Postman, so you can test any API requests that you're adding to the connector builder.

Required setup

As you step through the connector builder, you are prompted to complete the following configuration steps.

Introduction

The Patchworks marketplace includes a curated range of prebuilt connectors for you to browse, install and update. If the system that you need to integrate isn't listed, you can access the connector builder from here.

The steps

Step 1 Log into Patchworks and select connectors & instances from the left-hand navigation menu.

Step 2 Select the add new connector button at the top of the page:

Step 3 The connector builder is launched, ready for you to get started!

Introduction

We need to tell Patchworks what authentication methods can be used when someone chooses to , for use in .

Any authentication methods added here will be available to users when they choose to add an instance of this connector - for example:

Supported authentication types

Patchworks supports the following authentication types:

Working with authentication methods

In this section

• Authentication variables

• Connector variables

• URL parameters

• Header

• Body

• Pre-request script

• Post-request script

Introduction

URL parameters are used to apply queries/filters to the authentication request URL:

Any parameters added here are appended to the authentication URL as a query.

Using URL parameters in authentication requests

In reality, it's unlikely that URL parameters will be commonly used when defining authentication methods however, you can absolutely add them if needed.

URL parameters are added as 'key pairs' - so you specify a 'key' (a valid field name for this API) and then the required value.

Static values

A URL parameter value can be static - for example:

In this case, the value would be appended to the request endpoint as a URL query with the value exactly as it is defined - for example:

https://rest.storefeeder.com/warehouses/?warehouseID=0000001

Dynamic values

A URL parameter value can be dynamic, using auth variables that you've previously defined for the authentication method. In the example below, we have an auth variable named warehouseID:

So, when a user adds an instance of this connector, they are asked to provide a value for this field - for example:

...and when a process flow runs for this connector, associated API requests are injected with this value wherever a {{warehouseID}} variable is found. So, if we've added this variable in a URL parameter, as below:

...the resulting API request would include a parameter for whatever Warehouse ID the user entered when the instance being used was created.

Adding URL parameters

URL parameters are added as key pairs. To add a URL parameter, follow the steps below:

Step 1: Click the add new parameter button:

Step 2: Complete key pair details as required:

Step 3 Click the save button.

Editing & removing URL parameters

URL parameters are standard key pairs - techniques for working with these parameters are the same as those for working with header parameters, body parameters, etc. For more information about these techniques, please see the Working with parameters page.

Introduction

The connector builder supports a range of authentication types. Before a connector can be used (i.e. before instances of it can be added for use in process flows) you must add at least one authentication method for your connector.

The steps and settings required will vary depending on which authentication type you choose to configure, but the general process is straightforward.

What you need to do

General steps are provided below, with links to detailed guidance for each of our supported authentication types.

Step 1 Click the add new authentication method button:

Step 2 You're prompted to enter some basic details for this authentication method:

Complete these details using the table below as a guide:

Step 3 Click the create button to confirm your updates. Basic details are saved and additional setup options are displayed over a series of 'metro stop' tabs - for example:

Step 4 Step through each tab and set configuration options as appropriate for your chosen authentication method.

Configuring an authentication method

For any authentication method, the following configuration options are available:

Introduction

The auth variables tab is used to define authentication variables for any values that you need users to provide when they choose to add an instance of this connector, for use in process flows:

Here, you define what fields a user will be asked to complete when they choose to add an instance, select and authentication method, and provide credentials. For example:

You also define how any provided values are passed in authentication requests - i.e. are they included in the API request URL, the header, or the body?

Default auth variables

Having chosen an authentication method to configure, any required variables for that method are listed by default - for example:

These are variables that are always required to authenticate using this authentication method. You can't remove or change the behaviour of these variables, but you can change the display name if required.

Default auth variables are pre-configured to be passed into API requests as needed. For example, token-based authentication has one default parameter, which is pre-configured on the header tab. If your requirements are different, you can change how/where these variables are used.

Adding auth variables

To add an auth variable, follow the steps below:

Step 1 Start by selecting the connector variables tab to check if there are any instance-level variables for this connector that you want to include. Any variables defined for the instance as a whole are shown here - click the use button for any that you wish to include as an auth variable - for example:

When you choose to use a connector variable, you'll see that it gets added to the auth variables tab - for example:

Step 2 Back in the auth variables tab, you can now add any other variables for information that you need to provide when they add an instance of this connector with this authentication method. To do this, click the add variable button:

Step 3 Complete details and set options on the add variable page:

The add variables page is the same for all types of variables that you may encounter in the connector builder (for information about these options please see the Working with variables page). However, it's worth noting the effect of setting required and configurable by user options in the context of auth variables:

• When you add an auth variable and choose to make it required, you are effectively saying: 'When a user adds an instance of this connector, do not allow them to proceed without providing a value for this variable'.

• When you add an auth variable and choose to make it only configurable by users, you are effectively saying: 'When a user adds an instance of this connector, allow them to provide a value for this variable if they have one but if they don't, let them proceed'.

Step 4: Click the save button.

Step 5 Having added a variable, make sure that you go on to define how any values captured for it should be passed in API requests. Typically, any user-provided variable that you define here would then be added to the authentication request URL path, authentication request URL parameters, the authentication request header, or the authentication request body for the authentication method.

Introduction

The connector variables tab displays any i that you defined in - for example:

Using a connector variable in your authentication method

If you want to use any of these variables in this authentication method, click the use button:

This copies the variable into the auth variables tab - for example:

Removing a connector variable from auth variables

If you choose to use a connector variable- i.e. to copy it to the auth variables tab - but later change your mind - you can remove it by clicking the associated trash icon on the auth variables tab - for example:

This clears the connector variable from the auth variables tab but the original 'shared' connector variable remains available for future use.

Introduction

Any key pairs added to the body tab are passed into the request body for authentication requests - for example:

By adding these as key pairs to the body, we pass any values provided for these fields in the authentication request body.

Adding body parameters

Body parameters are added as key pairs. To add a body parameter, follow the steps below:

Step 1: Click the add new required body parameter button.

Step 2: Complete key pair details as required and save changes - for example:

Editing & removing body parameters

Introduction

Any key pairs added to the header tab are passed into authentication request headers - for example:

By adding these as key pairs to the header, we pass any values provided for these fields in the authentication request headers.

You should refer to the authentication section of your your API documentation for specific guidance about what (if any) values need to be passed in authentication request headers. For example, in Shopify, it's noted that we need to send two values in the request header - Content-Type and Shopify-Access-Token:

Adding header parameters

Header parameters are added as key pairs. To add a header parameter, follow the steps below:

Step 1: Click the add new header button:

Step 2: Complete key pair details as required and save changes:

Editing & removing header parameters

In this section

• Basic authentication

• Token-based authentication

• OAuth 2 (client credentials)

• OAuth 2 (authorisation code)

• OAuth 1

• DB user pass

• No auth

Introduction

Pre-request scripts allow you to modify authentication request parameters before sending the actual request. You can set dynamic values, compute signatures, or add headers based on specific conditions.

For example, you may have a third-party application which only accepts user passwords which are base 64 encoded. Expecting your users to know how to encode their password when they need to add connector instance for this application isn't always realistic, so a pre-request script can take care of this automatically.

How it works

Let's use the example scenario above to break down how pre-request scripts work:

1. A custom script should be created which takes a given password and performs base 64 encoding.

2. This script is applied to the pre-request script tab for the appropriate authentication method.

3. A user chooses to add an instance using this authentication method, and enters their username and password. Typically, an authentication request would be sent at this point - but NOT if a pre-request script is associated with the authentication method.

4. The pre-request script defined for this authentication method runs - any required values from authentication variables provided by the user are taken to manipulate the authentication request body as needed.

5. The authentication request is sent to to the given endpoint, including the manipulated body content.

6. Once the script has run, the authentication request is made, including the encoded password.

Applying a pre-request script

Step 1 Select the pre-request script tab for your authentication method:

Step 2 Click in the select a script field and choose the script that you want to use - for example:

Step 3 Choose the script version that you want to use:

Step 4 Now you can review the script code to be applied and save changes:

Introduction

Post-request scripts are useful for manipulating the response data before displaying or using it. You can extract specific values, format data, or even perform calculations. This helps in preparing the response data for further requests, or for displaying in a more user-friendly manner.

For example, we might have a connector which expects API requests to be authenticated with a {{token}} value received in response to an authentication request. However, suppose that the authentication request response includes the required token value AND a client_id value in the same detail field - somehow we need to ensure that only the token element is injected into a {{token}} variable, to be used for authenticating subsequent API requests.

To achieve this, we could create a custom script to extract the the token element from the detail field and then apply this to the post-request script tab for the required authentication method.

How it works

Let's use the example scenario above to break down how post-request scripts work:

1. A custom script should be created which extracts the token element of the detail field and applies this as the {{variable}} value.

2. This script is applied to the post-request script tab for the appropriate authentication method.

3. A user adds an instance using this authentication method, and enters their username and password.

4. The authentication request is sent and a successful response is returned, with client id and token values in the same detail field.

5. The post-request script defined for this authentication method runs, extracting the token element from the detail field and injecting it into the {{token}} variable for the authentication method.

Applying a post-request script

Step 1 Select the post-request script tab for your authentication method:

Step 2 Click in the select a script field and choose the script that you want to use - for example:

Step 3 Choose the script version that you want to use:

Step 4 Now you can review the script code to be applied and save changes:

Introduction

Basic authentication is the simplest (though not the strongest) method for authenticating API requests.

With basic authentication, a username and password are sent in the HTTP header of each API request, to authenticate a client application (in this case, Patchworks) and grant access to the associated resource.

How it works

Here's how basic authentication works:

1. The client-server (i.e. Patchworks) sends an API request to the required third-party application server (e.g. Shopify). The request includes username and password authentication credentials in the HTTP header of the request, encoded in Base64 format.

2. Upon receipt of the request, the third-party application server extracts authentication credentials from the header. It then validates these credentials by comparing them with the stored user credentials in its own system/database.

3. If the credentials provided are valid, the third-party application server grants access to the requested resource. If the credentials are invalid or missing, the third-party application server denies access and returns an appropriate error response.

User experience of basic authentication

When a Patchworks user adds an instance of a connector and chooses to authenticate with basic authentication, they will see something similar to the example below:

Basic authentication examples

It can be useful to compare how existing connectors have been configured for token-based authentication. The Patchworks marketplace includes many connectors that are configured to use this authentication type - a few examples are linked below:

You can install any of these for comparison.

Related information

• Configuring basic authentication

Introduction

This page walks through the steps required to configure token authentication for a connector.

Here, we're using Shopify as an example. General principles will be the same for any system that supports this authentication method but please refer to your own API documentation for specific setup requirements.

Preparation

• For this task, we'll be using techniques described in previous connector variables and authentication method options sections - we advise getting familiar with these before attempting the steps detailed here.

• Ensure that you have API documentation to hand, for your third-party application (we're using Shopify as an example).

• Ensure that you have all the required credentials for testing.

• We recommend using Postman to test any authentication methods that you're adding for a connector.

The Steps

Step 1 Check the API documentation for the third-party application that you're using - confirm that token authentication is supported and for any special requirements. Looking at the authentication section in Shopify's API documentation, there are three key points to note:

1. Whilst OAuth is the authentication method used to generate tokens when Shopify custom apps are installed, we've retrieved our generated token from the Shopify admin portal and will use this to set up token-based authentication.

2. We must pass our token into request headers, via a parameter called X-Shopify-Access-Token .

3. All requests must include a store_name value.

Step 2 Log in to the Patchworks dashboard and navigate to process flows > connectors & instances, where all your installed connectors are shown. From here, access settings for the connector that you need to update with a new authentication method - for example:

Step 3 Access authentication details:

Step 4 Click the add new authentication method button:

Step 5 Complete basic details for this authentication method - ensure that you set the authentication type to token-based and enter the required URL from your API documentation. Click the create button when you've finished, for more configuration options - for example:

Step 6 By default, the token-based authentication type includes one required auth variable - token:

If required, you can add more auth variables here.

Step 7 Now we need to define where information that users provide for these fields should be injected into the authentication requests.

Commonly, tokens are passed into request headers - as such, a default authorisation option is ready to use:

You can edit this option as needed - or remove it from the header altogether if your API documentation requires an alternative approach for passing in tokens.

At the very start of this exercise, we noted that our Shopify token must be passed into request headers via a parameter called X-Shopify-Access-Token . So, we can edit the default authorisation option to reflect this:

We leave the value set to {{token}}, so when a user adds an instance of this connector using token-based authentication and provides a valid token, the value they provide will be injected into this variable and passed in the request header:

Don't forget to save any changes that you make.

Step 8 Remember that at the very start of this exercise, we noted that a store_name value must be passed in the URL for all Shopify API requests. To achieve this, we need to ask users to provide a store_name value when they add an instance of this connector using token-based authentication (in addition to the token value we defined earlier).

We already have a store_name connector variable defined, so we can choose to 'use' it as an auth variable for token-based authentication:

To do this:

1. Click the connector variables tab.

2. Click the use button associated with the variable we want to use for our new authentication method.

3. That variable is added to token-based authentication as an auth variable.

Step 9 This completes our setup for token-based authentication. Now, when a user adds an instance of this connector and chooses to use this authentication method, they are prompted to provide all required/configurable authentication variables (in our example, store name and token).

Next steps

When configuring a process flow connection shape to use a given instance, you can choose from a list of available endpoints. For example:

This list will only include endpoints for which the same authentication method is enabled, as was used to add/authenticate the selected instance.

So, having added a new authentication method, you must enable it for any connector endpoints that you might want to use with instances that are added using this authentication method.

Introduction

A variable is a value that can change, depending on conditions or information supplied by the user. Using the Patchworks connector builder, variables can be defined at different levels:

About connector instance variables

The variables tab for a connector is used to define connector instance-level variables :

Users are prompted to provide values for these variables when they add and authenticate an instance of this connector. These values are then applied wherever this instance is used in process flows.

How it works

Any variables defined here are available for use when you move on to define authentication methods for your connector.

If you choose to use one of these variables in an authentication method, the result will be that your users are asked to provide a value for this field when they add an instance of this connector, with the associated authentication method.

Any value that the user provides during instance creation will be used whenever this instance is selected for use in process flows.

When a process flow runs (i.e. when API calls associated with selected endpoints for this instance are made), Patchworks grabs all defined variables and then injects them where a corresponding {{variable}} is found.

Example

A great example of where defining an connector instance-level variable here is useful, can be found in the Shopify API. For any API request, Shopify requires a given store_name - for example:

https://{{store_name}}.myshopify.com/admin/api/2023-04/customers.json

All API calls that users might want to use in process flows are added to the Shopify connector as endpoints. So, when a user configures a connection shape in a process flow and selects a connector instance to use, they will have a list of endpoints associated with the selected instance to choose from - for example:

Whilst you COULD ask your users to enter the appropriate store name whenever they select an endpoint (via an endpoint variable), this would be inefficient, and open to error.

A more efficient, reliable approach is to define a required {{store_name}} variable at the instance level. In doing so, the appropriate store name would be entered just once when an instance of this connector is added - for example:

The value provided here is injected into any {{store_name}} variables found when this instance is used subsequently, in process flows.

Precedence

If two variables with the same key are defined in two different places, we also prioritise them in connector -> connector instance -> endpoint order.

For example, if you define a {{store_name}} variable in an authentication method for a connector and then another {{store_name}} variable on an endpoint, the endpoint value would take precedence.

What you need to do

To add new system variables, follow the steps below:

Step 1 Click the add new system variable button:

Step 2 Complete fields on the add variable page - for example:

Step 3 Click save to add this variable to the variables list - for example:

Step 4 Repeat steps 2 and 3 for all required variables.

Step 5 Click next for authentication methods, where you can choose to use these variables, if needed.

Introduction

Token-based authentication allows users to verify their identity with a third-party server using a token. This is a more secure approach than basic authentication because username and password credentials are never passed in API requests.

How it works

Token-based authentication works by authenticating with a token that you already have available - perhaps it was given to you by a third-party application provider, or you have generated a token from the API - it doesn't matter how you obtain the token.

User experience of token authentication

When a Patchworks user adds an instance of a connector and chooses to authenticate with token-based authentication, they will see something similar to the example below:

Token-based authentication examples

It can be useful to compare how existing connectors have been configured for token-based authentication. The Patchworks marketplace includes many connectors that are configured to use this authentication type - a few examples are linked below:

You can install any of these for comparison.

Related information

• Configuring token-based authentication

Introduction

This page walks through the steps required to configure basic authentication for a connector.

Here, we're using as an example. General principles will be the same for any system that supports this authentication method but please refer to your own API documentation for specific setup requirements.

Preparation

• For this task, we'll be using techniques described in previous and sections - we advise getting familiar with these before attempting steps detailed here.

• Ensure that you have API documentation to hand, for your third-party application.

• Ensure that you have all required credentials for testing.

• We recommend using to test any authentication methods that you're adding for a connector.

The Steps

Step 1 Check the API documentation for the third-party application that you're using - confirm that basic authentication is supported, and for any special requirements.

For our example, we can see that basic authentication is permitted and that we need to pass consumer_key as the username and consumer_secret as the password:

Step 3 Access authentication details:

Step 4 Click the add new authentication method button:

Step 5 Complete basic details for this authentication method - ensure that you set the authentication type to basic and enter the required URL from your API documentation. Click the create button when you've finished, for more configuration options - for example:

If your API documentation requires users to provide an actual username and password to authenticate this connector, these can be left as they are. However, many APIs expect alternative information to be passed as these fields.

As such, we need to rename the default username and password fields. To do this, click the field name and update the display name as appropriate - we do this for both username and password:

Step 7 With username and password fields renamed (or not) as required, we now need to define where any information that users provide for these fields should be injected into the API request. For basic authentication, these details are always passed in request headers.

To set this up, click the header tab, followed by the add new header button.

Step 8 You can now enter your authentication options as key pairs:

Here, the key is the name of the parameter that you're passing in as the username / password, as defined in the API documentation for your third-party application. Taking our example, we know that the consumer_key is required for username and consumer_secret is required for password:

So, our key pair for username would be defined as follows (injecting consumer_key information into the {{username}} variable:

And our key pair for password would be defined as follows (injecting consumer_secret information into the {{password}} variable:

Next steps

This list will only include endpoints for which the same authentication method is enabled, as was used to add/authenticate the selected instance.

Introduction

The OAuth 2 authorisation code flow requires a user (in this case, a Patchworks user, for use in ) to log into an authorisation server and grant permission for Patchworks to access the required data.

How it works

When a Patchworks user and chooses to authenticate with OAuth 2 (authorisation code) they are directed to the authorisation server for a third-party service, where they log in and 'allow' requested access. A sample user journey for NetSuite is shown below:

Here, we:

1. Add an instance and confirm credentials.

2. Are redirected to NetSuite, where we log in.

3. Are presented with information about what access is being requested, and choose to proceed.

4. Return to the Patchworks connector page, where our new NetSuite instance is added and ready to use in process flows.

Authentication request URLs

When setting up OAuth 2 (authorisation code) authentication, two URLs are required. The first (URL) is the authentication endpoint and the second (Additional URL 1) is the authorise endpoint.

The following example is for a NetSuite implementation - please check your API documentation for your own required values:

Redirect URIs

When specifying redirect URIs for OAuth 2, the following values can be used:

OAuth 2 (authorisation code) authentication examples

It can be useful to compare how existing connectors have been configured for OAuth 2 (authorisation code) authentication. The Patchworks marketplace includes many connectors that are configured to use this authentication type - a few examples are linked below:

You can install any of these for comparison.

Related information

Introduction

The OAuth 2 client credentials flow allows client applications (i.e. Patchworks) to authenticate and obtain access to resources, without involving specific user intervention.

How it works

The exact mechanism used for client credentials authentication depends on the implementation of the authorisation server for the system in question, but a common mechanism is client secret.

This is where a client application (in this case, Patchworks) authenticates itself by sending its unique client identifier and client secret to the authorisation server, and receives a token in response.

OAuth 2 (client credentials) authentication examples

It can be useful to compare how existing connectors have been configured for OAuth 2 (client credentials) authentication. The Patchworks marketplace includes many connectors that are configured to use this authentication type - a few examples are linked below:

You can install any of these for comparison.

Related information

Introduction

OAuth 1.0 involves the use of cryptographic signatures for message integrity and verification. It requires the consumer (in this case, Patchworks) to sign API requests using a consumer secret, which is provided by the service provider. The service provider verifies these signatures to ensure the integrity of the requests.

Patchworks supports the following signature methods:

• HMAC-SHA256

OAuth 1.0 has been largely superseded by OAuth 2.0.

How it works

Here's how OAuth 1 authentication works:

OAuth 1 authentication examples

It can be useful to compare how existing connectors have been configured for OAuth 1 authentication.

Since OAuth 2 has largely taken over from OAuth 1, there aren't many examples in the Patchworks marketplace however, you will find both OAuth 1 and OAuth 2 defined for our NetSuite connector. You can install this for comparison.

Introduction

This page walks through the steps required to configure OAuth 2 authentication (authorisation code flow) for a connector.

Here, we're using NetSuite as an example. General principles will be the same for any system that supports this authentication method but please refer to your own API documentation for specific setup requirements.

Preparation

• For this task, we'll be using techniques described in previous connector variables and authentication method options sections - we advise getting familiar with these before attempting steps detailed here.

• Ensure that you have API documentation to hand, for your third-party application (we're using NetSuite as an example).

• Check the documentation for your third-party application and ensure that any in-app setup required for OAuth 2 has been completed. For example, NetSuite's documentation includes a section on tasks that administrators must complete to support OAuth 2 for integrations.

• Ensure that you have all required OAuth 2 credentials for testing.

• We recommend using Postman to test any authentication methods that you're adding for a connector.

Redirect URIs

When specifying redirect URIs for OAuth 2, the following values can be used:

The Steps

Step 1 Check the API documentation for the third-party application that you're using - confirm that OAuth 2 authentication (authorisation code flow) is supported, and for any special requirements.

Step 2 Log in to the Patchworks dashboard and navigate to process flows > connectors & instances, where all of your installed connectors are shown. From here, access settings for the connector that you need to update with a new authentication method - for example:

Step 3 Access authentication details:

Step 4 Click the add new authentication method button:

Step 5 Complete basic details for this authentication method - ensure that you set the authentication type to OAuth 2 authorisation code and enter the required URL(s) from your API documentation.

Click the create button when you've finished, for more configuration options - for example:

Step 6 By default, the OAuth 2 authorisation code type includes a range of default auth variables:

These are known variables that a user must provide to authenticate an instance of this connector using this authentication method.

Mandatory variables are locked however, you can change the display name if required. You can also add more auth variables here if needed.

Step 7 Now we'll check to see if there are any shared connector variables that need to be used as auth variables.

In our example, we need to use the accountid connector variable for authentication, because this is a user-provided value that forms part of our authentication request URL path (defined in step 5). So, we can simply choose to use the accountid connector variable as an auth variable for this authentication method:

To do this:

1. Click the connector variables tab.

2. Click the use button associated with the variable we want to use for our new authentication method.

3. That variable is added to this authentication method as an auth variable.

Step 8 Next, we need to confirm/change where any information that users provide for auth variables should be injected into authentication requests.

Default auth variables are pre-configured to be passed into API requests, as most commonly needed. For example, if we check the URL parameters tab now, we'll see that some of our user-provided auth variables have been added automatically:

And if we check the body tab now, we'll see that remaining user-provided auth variables have been added automatically:

Check the API documentation for your third-party application and ensure that all required auth variables have been added, and are being passed in the right place. Don't forget to save any changes that you make.

Step 9 This completes our setup for OAuth 2 authorisation code authentication. Now, when a user adds an instance of this connector and chooses to use this authentication method, they are prompted to provide all required/configurable authentication variables. Upon confirmation, they will be directed to your third-party authorisation server and asked to authorise access - then redirected back to Patchworks.

Next steps

When you configure a process flow connection shape to use a given instance, you can then choose from a list of available endpoints. For example:

This list will only include endpoints for which the same authentication method is enabled, as was used to add/authenticate the selected instance.

So, having added a new authentication method, you must enable it for any connector endpoints that you might want to use with instances that are added using this authentication method.

Introduction

This page walks through the steps required to configure OAuth 2 authentication (client credentials flow) for a connector.

Here, we're using Shopware as an example. General principles will be the same for any system that supports this authentication method but please refer to your own API documentation for specific setup requirements.

Preparation

• For this task, we'll be using techniques described in previous connector variables and authentication method options sections - we advise getting familiar with these before attempting steps detailed here.

• Ensure that you have API documentation to hand, for your third-party application (we're using Shopware API docs for this example).

• Check the documentation for your third-party application and ensure that any in-app setup required for OAuth 2 has been completed.

• Ensure that you have all required OAuth 2 credentials for testing.

• We recommend using Postman to test any authentication methods that you're adding for a connector.

The Steps

Step 1 Check the API documentation for the third-party application that you're using - confirm that OAuth 2 authentication (client credentials code flow) is supported, and for any special requirements.

Step 2 Log in to the Patchworks dashboard and navigate to process flows > connectors & instances, where all of your installed connectors are shown. From here, access settings for the connector that you need to update with a new authentication method - for example:

Step 3 Access authentication details:

Step 4 Click the add new authentication method button:

Step 5 Complete basic details for this authentication method - ensure that you set the authentication type to OAuth 2 client credentials and click the create button.

Step 6 Authentication variables are displayed. By default, the OAuth 2 client credentials type includes a range of default authentication variables:

These are known variables that a user must provide to authenticate an instance of this connector with this authentication method.

The following parameters are required for the OAuth 2 client credentials flow, and are configured to be displayed to users when they attempt to add an instance for this connector:

In each case, you can change the parameter name, default value and settings for how the field is made available to users when they choose to add connector instances. You cannot change the parameter key.

Step 7 Check your API documentation for any additional parameters that are required for authentication - do you need users to provide any additional information to authenticate instances of this this connector?

Step 8 Select the URL parameters tab and provide a request URL for authentication - you'll find this in your API documentation:

Also check your API documentation for any query parameters required for this URL and add them as needed.

Step 9 Select the header tab and add any authentication variables that need to be passed in the authentication request header - you'll find this in your API documentation:

For OAuth 2 (client credentials), a content-type parameter is added by default, with a value of application/x-www-form-urlencoded. Check your API documentation - if necessary you can change this value.

Step 10 Select the body tab and add any authentication parameters/content to be passed in the authentication request body - you'll find this in your API documentation.

Step 11 This completes our setup for OAuth 2 (client credentials) authentication. Now, when a user adds an instance of this connector and chooses to use this authentication method, they are prompted to provide all required/configurable authentication variables.

Introduction

SOAP (Simple Object Access Protocol) is a messaging protocol for exchanging structured information in a web environment. SOAP authentication is used specifically for authenticating SOAP-based web services.

How it works

The Patchworks Connector Builder incorporates token-based authentication for SOAP. When requests are made, user credentials (provided when the connector instance was created) are passed for authentication and a token is returned - tokens are incorporated into SOAP messages.

Your authentication setup will typically include variables for user credentials (e.g. username and password) and a response_authentication_token_key (or similar) which tells Patchworks where to find a token in authentication response SOAP messages. For example:

User experience of SOAP authentication

When a Patchworks user adds an instance of a connector and chooses to authenticate with SOAP authentication, they will see something similar to the example below:

Required variables will vary, depending on the API but in general there will be at least fields for users to enter their credentials.

SOAP-based authentication examples

It can be useful to compare how existing connectors have been configured for SOAP-based authentication. Some examples are linked below:

You can install any of these for comparison.

Related information

• Configuring token-based authentication

Introduction

DB user pass authentication is only used for building database connectors. Here, database access is authenticated with username and password over SSL (if unavailable, falling back to no SSL).

How it works

Here's how basic authentication works:

1. Patchworks sends an API request to the required database (e.g. MySQL). The request includes username and password authentication credentials in the HTTP header of the request, encoded in Base64 format.

2. Upon receipt of the request, authentication credentials are extracted from the request header and validated.

3. If the credentials provided are valid, access is granted for the requested resource. If the credentials are invalid or missing, an appropriate error response is returned and access is denied.

User experience of db user pass authentication

When a Patchworks user adds an instance of a connector and chooses to authenticate with db user pass authentication, they will see something similar to the example below:

Related information

• Building a database connector

• Configuring a database connection

Introduction

Endpoint options are used to define the API requests for any endpoints you want to make available for use with of this connector:

Working with endpoints

Introduction

This page walks through the steps required to configure no auth authentication for a connector.

The Steps

Step 1 Log in to the and navigate to process flows > connectors & instances, where all of your installed connectors are shown. From here, access settings for the connector that you need to update with a new authentication method - for example:

Step 2 Access authentication details:

Step 3 Click the add new authentication method button:

Step 4 Complete basic details for this authentication method - ensure that you set the authentication type to no auth (public) - for example:

Step 5 You don't need to add any settings under authentication setup - although if you want users to provide variable values when they add instances for this connector, or pass in header/body content, etc. then you can update these tabs:

Step 6 Save changes.

Introduction

The endpoint URL page is used to define the HTTP method and URL to be used, and any required URL parameters:

Endpoint URL

To add an endpoint URL, you must select the appropriate HTTP method:

...and then add the required URL:

Endpoint parameters

You can define two types of parameter:

Required parameters

In the example below, our endpoint URL is set to GET all products, but we are adding a default URL parameter to add a query which will only retrieve products with a product_type of snowboard:

https://parseapi.back4app.com/classes/product?product_type=snowboards

Optional parameters

Optional parameters are available for your users to update with their own required values, in process flows.

If we consider the example above - we are always restricting our 'GET all products' endpoint to return only products with a product_type of snowboard. But suppose we wanted to allow users to choose a product_type at the point they are running a process flow?

When a process flow runs for this connector, associated API requests are injected with the user-provided URL parameter value wherever a {{product_type}} parameter is found.

What if I want to force users to enter their required value for a URL parameter?

However, there may be scenarios where you need to ensure that a URL parameter is always provided by users running a process flow. For this, a slightly different approach is needed - in this case, you would:

More information

Introduction

Before a connector can be used (i.e. before for use in ) you must add at least one endpoint. The steps and settings required will vary depending on which type of endpoint you're adding, and how you want it to behave - general steps can be found below.

Step 1 Click the add new endpoint button:

Step 2 You're prompted to enter a name, and to select an entity type:

...enter a name for this endpoint and select the appropriate entity type from the dropdown list:

Step 3 Click the create button. Basic details are saved and the manage endpoint page is displayed:

This page is split into upper and lower panes - endpoint details at the top and endpoint setup in the lower panel.

Step 4 In the top endpoint details panel, use dropdown options to set the direction as required:

This determines the direction that data associated with this endpoint will flow:

• Choose receive if you will be pulling (i.e. receiving) data for this endpoint - typically these endpoints are associated with a GET http method.

• Choose send if you will be pushing (i.e. sending) data to this this endpoint - typically these endpoints are associated with PUT, POST, PATCH or DELETE http methods.

Configuring an endpoint

For any endpoint, the following options are available:

In this section

Introduction

The authentication tab for an endpoint is where you decide which of your for this connector, can be used for this endpoint:

AND

AND

How does this work?

So, if you have configured two authentication methods and added an instance for each - and you want your endpoint to be available whichever instance a user chooses to use in a process flow - you need to activate both of these for your endpoint.

For example, let's say that:

• You've configured basic auth and OAuth 2 authentication methods for your connector, and have added instance 1 with basic auth credentials and instance 2 using OAuth credentials.

• You add an 'orders' endpoint but you ONLY activate the basic auth authentication method.

The effect will be:

Activating an authentication method for an endpoint

To activate an authentication method for an endpoint, simply set the appropriate toggle option to 'on' - for example:

Overview

GraphQL cursor pagination is a method for paginating GraphQL APIs.

Here, we send a GraphQL query requesting a list of items. This query includes parameters such as the number of items to fetch and any filtering or sorting criteria required. In response, requested items are received, together with cursor information (each item in the response is associated with a cursor, which is typically a unique identifier for that item).

GraphQL cursor options

GraphQL cursor pagination - endpoint body requirements

The GraphQL cursor pagination method works in conjunction with a query on the endpoint body, which determines required settings. For example:

{"query":"{products(first: 250, {{pagination_cursor}}) {edges { node { id title } } pageInfo { hasNextPage startCursor endCursor }}}","variables":{}}

If you need to change the existing query for an endpoint, you should edit the connector and access body options for the required endpoint.

When does pagination stop?

Pagination continues until hasNextPage is returned as false.

Overview

Each page is denoted by the ID of the last object it holds, rather than its page. For example, if a 'page' returns 10 customers, then the ID of the last customer will be passed in the URL to get the next page.

Custom relative URI options

Example

Suppose we set the following options:

The following URL will be generated to get the first page:

GET http://my.shop/api/customers?limit=10

Notice our link parameter path (limit) and the actual limit value (10) at the end of the request. Our first page would look something like the example below:

{
  "data": [
    {"id": 1, "name": "Alice"},
    {"id": 2, "name": "Bob"},
    {"id": 3, "name": "Charlie"},
    {"id": 4, "name": "Lyn"},
    {"id": 5, "name": "John"},
    {"id": 6, "name": "Gordon"},
    {"id": 7, "name": "Izzy"},
    {"id": 8, "name": "Mike"},
    {"id": 9, "name": "Ralph"},
    {"id": 10, "name": "Rex"}
  ],
}

When pagination runs, it will look for the last id key in the payload, and use that as the starting point for the next request. So the request for page 2 will be:

GET http://my.shop/api/customers?limit=10&starting_after=10

Notice our link parameter path (limit) and the actual limit value (10) at the end of the request, followed by our Last ID parameter name (starting_after) set to the last id in the response.

A sample response for this request is below:

{
  "data": [
    {"id": 11, "name": "Josh"},
    {"id": 12, "name": "Adam"},
    {"id": 13, "name": "Tom"},
    {"id": 14, "name": "Aaron"},
    {"id": 15, "name": "Conor"},
    {"id": 16, "name": "Luke"},
    {"id": 17, "name": "Andrew"},
    {"id": 18, "name": "Nathan"},
    {"id": 19, "name": "Lee"},
    {"id": 20, "name": "Dean"}
  ]
}

When does pagination stop?

Pagination continues until the the number of items in the payload is less than the limit, or the page returns an error code.

Overview

This method is a slight variation on the next page URL approach. Instead of receiving a full URL in the response, it contains a 'token' (usually a random string/hash). The receiving system uses this token to keep track of the position of the last record in the current page of data.

Next page token options

Example

Suppose we set the following options:

...and we send a request to get the first page of data:

GET https://my.shop/api/customers?limit=10

The response will include the first page of data, together with a next page token that should be used to get the next page of results. For example:

{
  "data": [
    {"id": 1, "name": "Alice"},
    {"id": 2, "name": "Bob"},
    {"id": 3, "name": "Charlie"},
    {"id": 4, "name": "Lyn"},
    {"id": 5, "name": "John"},
    {"id": 6, "name": "Gordon"},
    {"id": 7, "name": "Izzy"},
    {"id": 8, "name": "Mike"},
    {"id": 9, "name": "Ralph"},
    {"id": 10, "name": "Rex"}
  ],
  "links": {
    "next": "abcd5780HJKLMN0PqR24"
  }
}

Notice the links.next section at the end of this response, which includes our next page URL. So, our request for the next page of results would be:

GET https://my.shop/api/customers?limit=10&page_token=abcd5780HJKLMN0PqR24

When does pagination stop?

Pagination continues until the token is no longer included in the payload.

Special notes

The next page token pagination method is implemented using a Patchworks pagination variable which contains a token for the next page:

<PageNo>[[pagination.next_page_token]]</PageNo>

Introduction

Some APIs include pagination functionality so that large HTTP responses can be served as multiple pages, which are more manageable. Different APIs use different methods to approach this.

Need to know

When paginated data is pulled, a payload is generated for each page.

Setting a pagination method

To set a pagination method for an endpoint, click in the pagination method field to activate a dropdown list of supported methods:

Having selected a method, click save. Any required options for the selected method are displayed.

Supported pagination methods

The following pagination methods are supported:

• Custom relative URI

• GraphQL cursor

• Limit-offset

• Link header

• Next page token

• Next page URL

• Page number parameter

• PeopleVox

• NetSuite SOAP

Introduction

The body tab is primarily used for creating or updating resources (i.e. for POST, PUT, PATCH and DELETE requests).

Any parameters added here are passed in the endpoint request body. You can define default body parameters, and optional body parameters:

The body tab is split into upper and lower panels:

• Required body parameters

• Body filters

Required body parameters

If you have parameters that must always be passed in the endpoint request body, add them to the required body parameters panel. Default parameters are passed straight into requests - users are never asked to provide values for these.

Required body content can be none, or added as raw, form, or text data:

Raw data

Use this option to pass static content or an incoming payload into the request body. Select the raw option and choose the required data type:

...then (if required) use the editor provided to add the required data:

Form data

Select the form option to add data as key pairs:

Text

Select the text option and add the required text content to the body content field:

None

Set this option to none if no body content is expected.

It's important to note that this option is ignored if data is found in the body. This handles scenarios where body content isn't typically expected so body format is set to none, but later (for example) a custom script is introduced which adds a payload to the body.

Body filters

If you have parameters that you want to expose to users when they configure a connection shape to use this endpoint in process flows and then pass provided values into the endpoint request body, add them to the lower panel:

Body filters are available for your users to update with their own required values, in process flows. These work in exactly the same way as noted for optional URL parameters, except any values provided by users (via the connection shape in process flows) are passed into the request body, rather than being added as URL queries.

More information

Techniques for adding header parameters are the same as all other types of parameters that you may encounter in the connector builder. For information about these options please see the Working with parameters page.

Introduction

Any parameters added to the header tab are passed in the endpoint request headers. You can define default header parameters and optional header parameters:

Notice that the header tab is split into upper and lower panels:

• Required parameters

• Header filters

Required parameters

If you have parameters that must always be passed in the endpoint request header, add them to the required parameters panel. Default options are added as key pairs, and are passed straight into request headers - users are never asked to provide values for these.

Header filters

If you have parameters that you want to expose to users in process flows and then pass provided values into the endpoint request header, add them to the lower panel.

Optional parameters are available for your users to update with their own required values, in process flows. These work in exactly the same way as noted for optional URL parameters, except any values provided by users (via the connection shape in process flows) are passed into the request headers, rather than being added as URL queries.

Webhooks

If you are building a connector for a webhook, you must include a content-type header.

More information

Techniques for adding header parameters are the same as all other types of parameters that you may encounter in the connector builder. For information about these options please see the Working with parameters page.

Overview

This method is similar to the approach, except that the URL for the next page is included in the response body, rather than the header.

Next page URL options

Example

Suppose we set the following options:

...and we send a request to get the first page of data:

GET https://my.shop/api/customers?page=1

The response will include the first page of data, together with a URL that should be used to get the next page of results. For example:

{
  "data": [
    {"id": 1, "name": "Alice"},
    {"id": 2, "name": "Bob"},
    {"id": 3, "name": "Charlie"},
    {"id": 4, "name": "Lyn"},
    {"id": 5, "name": "John"},
    {"id": 6, "name": "Gordon"},
    {"id": 7, "name": "Izzy"},
    {"id": 8, "name": "Mike"},
    {"id": 9, "name": "Ralph"},
    {"id": 10, "name": "Rex"}
  ],
  "links": {
    "next": "https://my.shop/api/customers?page=2"
  }
}

Notice the links.next section at the end of this response, which includes our next page URL. So, our request for the next page of results would be:

https://my.shop/api/customers?page=2

When does pagination stop?

Pagination continues until the next page URL is no longer included in the payload.

Overview

This pagination method has been developed specifically for PeopleVox. It should not be used with other systems.

Limit-offset options

Special notes

PeopleVox GET endpoints include body content which handles specific requirements for PeopleVox data. This includes a Patchworks pagination variable, which is used to calculate page numbers:

<PageNo>[[pagination.page]]</PageNo>

Overview

This pagination method has been developed specifically for the NetSuite SOAP connector. It should not be used with other systems.

Pagination options

Special notes

To find the required xPaths, tools such as can be useful. Paste in a sample NetSuite SOAP response (first page) to obtain the required paths to fields.

Overview

When a response to a request is received, the response contains a header which holds a URL for the next page of results.

Link header options

When does pagination stop?

Pagination continues until the response does not contain a link header.

Overview

In this method, the required page number is included as a parameter in the API request, and is incremented in each request to get the next page.

Page number parameter options

Example

Suppose we set the following options:

...and we send a request to get the first page of data:

GET https://my.shop/api/customers?limit=10&page=1

The response will include the first page of data (sometimes with metadata regarding pagination). For example:

{
  "data": [
    {"id": 1, "name": "Alice"},
    {"id": 2, "name": "Bob"},
    {"id": 3, "name": "Charlie"},
    {"id": 4, "name": "Lyn"},
    {"id": 5, "name": "John"},
    {"id": 6, "name": "Gordon"},
    {"id": 7, "name": "Izzy"},
    {"id": 8, "name": "Mike"},
    {"id": 9, "name": "Ralph"},
    {"id": 10, "name": "Rex"}
  ],
  "meta": {
    "totalItems": "150",
    "itemsPerPage": "10"
  }
}

Our request for the next page of results would be:

GET https://my.shop/api/customers?limit=10&page=2

When does pagination stop?

Pagination continues until the last page, when there is no more data to return.

Special notes

The page number parameter pagination method is implemented using a Patchworks pagination variable which contains the next page number:

<PageNo>[[pagination.page]]</PageNo>

Introduction

OAuth 2 is a protocol which allows users to grant limited access to their resources/data in an application or service (e.g. NetSuite), to another application or service (in this case, Patchworks) without ever sharing their login credentials.

The authentication flow and associated configuration for OAuth 2 vary according to which grant type is used. Patchworks supports the following OAuth 2 grant types:

OAuth 2 provides a more streamlined, standardised approach than - it’s easier to implement and more suitable for a wide range of applications.

Introduction

When you build a connector using the , available are determined by the specified for the endpoint. The schema tab is split into two panels - for example:

Introduction

Schemas aren't mandatory but they make things much simpler when building process flows. If your flow includes endpoints associated with schemas, any field selector options in process flow shapes are populated with the schema structure - all you need to do is choose the required field.

For example, the below is picking up the schema associated with the Shopify endpoint, configured in the preceding connector shape:

If a process flow uses an endpoint without a schema, any field paths defined in shapes must be defined manually.

Adding a schema

To apply a schema for an endpoint, follow the steps below:

Step 1 Click the edit schema button:

Step 2 Paste in the required schema and save changes:

Setting a data path

This is particularly important for JSON payloads, where the data structure is nested. Let's take an example below:

Here, all of our data is nested within one, top-level customers array object. If you scan down this example, you'll notice that there are two customer objects, each starting with an id for a customer record:

Now let's look at the data path field at the bottom of this page:

If we leave this set to empty, any subsequent field tags, mappings and filters will work on the basis that the top-level array object is our target. What we'd be saying in this scenario is 'don't treat the nested objects as separate records'.

So, for example, if we went on to apply a filter to match on first_name contains bob, we'd find a match in the second customer object but ALL objects would be returned because we're targeting the top-level array object. This isn't what we want - we need to treat each of the lower-level customer objects as separate records. To do this, we navigate the data path and select the parent object - in this case, its customers:

Introduction

Typically, users need to provide valid authentication credentials for any instance of a connector that they add - when the instance is created, Patchworks checks that the credentials are valid and if they are, the instance is created.

However, there may be times where you wish to allow users to add an instance without providing any authentication credentials - perhaps you're connecting to a public-facing system, or to a Postman mock server (for example).

User experience of token authentication

When a Patchworks user and chooses to authenticate with a configured no auth authentication method, they are not prompted to enter any credentials. Instead, they go directly to finalising the instance - for example:

Overview

This method is similar to the page number parameter approach. However, instead of appending a page number to the request URL, an offset parameter is used to indicate how many results have been returned so far (i.e. the start point for required data).

This method is rather like a database search: give me 5 records starting from the 15th record.

Limit-offset options

Example

Suppose we set the following options:

...and we send a request to get the first page of data:

GET https://my.shop/api/customers??limit=5&offset=0

The response will include the first page of data (sometimes with metadata regarding pagination). For example:

{
  "data": [
    {"name": "Gordon"},
    {"name": "Izzy"},
    {"name": "Mike"},
    {"name": "Ralph"},
    {"name": "Rex"}
  ],
  "meta": {
    "total": 50,
    "count": 5,
    "limit": 5,
    "offset": 5
  }
}

Requests for subsequent pages would increment the offset value by the limit value - for example:

GET https://my.shop/api/customers??limit=5&offset=5

...and then:

GET https://my.shop/api/customers??limit=5&offset=10

...and so on until 50 items (i.e. the total parameter path value) are returned.

When does pagination stop?

Pagination continues until the last page, when there is no more data to return.

Special notes

The limit offset pagination method is implemented using a Patchworks pagination variable which contains the next page offset:

<PageNo>[[pagination.offset]]</PageNo>

Fulfillments

Fulfillments line items

Refunds

Refund line items

Refunds order adjustment

Refund line item discounts

Refund line item tax lines

Refund transactions

Orders

Order lines

Order tax lines

Order line item discounts

Order line items tax lines