Introduction

We need to tell Patchworks what authentication methods can be used when someone chooses to add an instance of your connector, for use in process flows.

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:

• Basic authentication

• Token-based authentication

• OAuth 2 (client credentials)

• OAuth 2 (authorisation code)

• OAuth 1

Working with authentication methods

Please see Adding a new authentication method for general steps required to add a new authentication method for a connector.

You'll find detailed information about options and settings in the Authentication method options section, and step-by-step examples for each type in the Supported authentication types section.

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 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 , so users associated with your company profile can add 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 , 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 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, 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:

In this section

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

In this section

• Basic authentication

• Token-based authentication

• OAuth 2 (client credentials)

• OAuth 2 (authorisation code)

• OAuth 1

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

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

The connector variables tab displays any instance-level, shared variables that you defined in Step 2: connector variables - 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:

From here, the variable is treated like any other auth variable - you will need to set options to determine if/how this variable is displayed to users, and how any values for it should be passed in API requests for authentication.

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

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

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

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

Here, we're using WooCommerce 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.

• Ensure that you have all 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 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 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 basic 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 basic authentication type includes two required auth variables - username and password:

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.

Taking our example, the WooCommerce API documentation states that a consumer key should be provided as the username and a consumer secret should be provided as the password:

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:

If required, you can add more auth variables here.

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:

Step 9 This completes our setup for basic authentication. Now, when someone chooses to add an instance for this connector, basic authentication will be an option that they can choose. If selected, the user will then be prompted to enter a username and password - or in the case of our example - a consumer key and a consumer secret:

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

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

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

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

Introduction

This page walks through the steps required to configure token 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 the steps detailed here.

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

• Ensure that you have all the 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 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 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 7 Now we need to define where information that users provide for these fields should be injected into the authentication requests.

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:

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

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

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 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 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

This page walks through the steps required to configure OAuth 2 authentication (authorisation code flow) 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 (we're using 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, 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 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 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:

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.

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

Token-based authentication allows users to verify their identity with a third-party server using a token. This is a more secure approach than 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 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

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

In this section

• Authentication

• Variables

• URL

• Header

• Body

• Pagination

• Schema

Introduction

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

Any endpoints added here will be available for your users to select when they choose to add an instance of this connector to a process flow - for example:

Working with endpoints

Please see Adding a new endpoint for general steps required to add a new endpoint for a connector. You'll find detailed information about options and settings in the Endpoint options section.

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 adds an instance of a connector 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:

Introduction

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

When an authentication method is activated for an endpoint, it means that that the endpoint will be available in process flows when:

• You add a connection shape to a process flow

AND

• You associate that connection with an instance of this connector

AND

• That instance was originally configured using this authentication method

How does this work?

When you add an instance for a connector, you must provide a set of credentials for authentication. Any authentication methods that you have configured for the connector will be available to choose from.

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:

• If you add a connection shape to a process flow and associate it with instance 1 (i.e. using basic auth), the 'orders' endpoint will be available for selection - this is because we've activated basic auth for the endpoint.

• If you add a connection shape to a process flow and associate it with instance 2 (i.e. using OAuth 2), the 'orders' endpoint will NOT be available for selection - this is because we didn't activate OAuth 2 for the endpoint, but the instance is authenticated using OAuth 2 credentials.

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:

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

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

The Steps

Step 1 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 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

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

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:

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:

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:

Introduction

We've already seen how variables are defined at and levels - the final level that variables can be defined at is on endpoints. Any variables added here are only applicable to the associated endpoint:

When the process flow runs (i.e. when API requests are performed) the information provided by your user is injected into any corresponding {{variable}} tokens found in the endpoint requests.

For example, you might define an endpoint to retrieve a single customer record, and require your user to specify the required ID at runtime:

Precedence

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

Adding a variable for an endpoint

To add a variable for an endpoint, follow the steps below.

Step 1 Click the add new variable button:

Step 3 Click the save button.

Removing a connector variable from auth variables

You can remove an endpoint variable by clicking the associated trash icon on the auth variables tab - for example:

Introduction

The Patchworks field tag taxonomy covers a range of entities across orders, products, fulfilments, and inventory. You'll see this if/when you come to apply field tags. The current taxonomy is detailed in the following sections:

• Orders

• Customers

• Refunds

• Products

• Fulfillments

• Inventory

Introduction

The essence of process flows is to pull defined data from one Patchworks connector (i.e. a third-party system) and push it into at least one other connector (i.e. another third-party system). It’s unlikely that two third-party systems will have the same data structures, therefore we use the mapping shape to define where a data field from one connector should be placed in another.

When you build a connector using the connector builder, available field mappings are determined by the data schema specified for the endpoint. Field names used in data schemas can appear to be quite random and complex - this is fine if you know the schema and you're the only company ever likely to install the associated connector, but if you think that you might want to share your connector with other Patchworks customers in future, then field tagging is really important.

What is a field tag?

A field tag is a standard Patchworks tag that can be applied for a data field in the schema associated with a connector endpoint.

The Patchworks field tag taxonomy covers a wide range of entities across orders, products, fulfilments, and inventory. You'll see this if/when you come to apply field tags.

How do field tags help?

By standardising how fields are identified across all connectors, we can automate mappings between them.

So, if you add two connection shapes to a process flow - each with endpoints that have been fully tagged - you'll find that mappings are automatically created when you add a map shape between them. Without field tagging, you need to apply mappings manually.

Do I have to apply field tags?

Field tagging isn't mandatory if you're building a connector that will only ever be used within your own company.

However, if there's a chance that you'd like to share your connector in the Patchworks marketplace for other organisations to install, then you must apply standard Patchworks field tags - this will be a condition of verification.

Can I apply multiple field tags for a single field?

Yes - if a data field in your schema needs to be associated with more than one tag, you can apply as many as you need.

What are tracked fields?

When you choose to add a field tag, you'll see a tracked option. Typically, this should be set for fields that you might need to track if/how records have been processed.

For example, if you're configuring an endpoint to receive 'order' data, there will usually be some sort of order id field that uniquely identifies each order; if you're configuring an endpoint to receive 'customer' data, there will usually be some sort of customer id field that uniquely identifies each customer.

By marking these fields as 'tracked', they become for viewing/filtering/selecting wherever tracked data is shown in Patchworks.

Introduction

When building connectors with the connector builder, you need to add/update variables and parameters in most stages of the process. Whilst the purpose of these will vary (for example, endpoint and authentication variables are needed for different things), techniques for adding and managing variables and parameters is always the same.

In this section

• Working with variables

• Working with parameters

About parameters

Parameters can be defined throughout the connector builder, in:

• Authentication method URL parameters

• Authentication method headers

• Authentication method body

• Endpoint URL parameters

• Endpoint headers

• Endpoint body

When a process flow runs, any associated API requests are injected with given variable values wherever a corresponding {{key}} is found - this is Irrespective of where parameters are defined

Optional vs default parameters

Depending on where you are in the connector builder, you will encounter both default and optional parameters, where:

• Default parameters are always applied to API requests, whenever it is used.

• Optional parameters are those that users can choose to apply with their own values - either when adding connector instances (in the case of parameters defined for authentication methods) or as filter parameters when configuring connection shapes for process flows.

Irrespective of where parameters are defined, any associated API requests are injected with given default and optional parameter values wherever a corresponding {{key}} is found.

In some places, you can only add default variables, but in others you can add both types. In this case, the variables page is split into two panels - for example:

Default parameters are defined in the top panel, with optional parameters in the lower panel. The sections below explain the use of these parameters in general terms - for specific guidance in a particular context, please use the links provided above.

Default parameters

Default parameters are those which must always be passed into the request URL, header, or body using values that you specify as part of the configuration. They are added as key pairs:

Defined values can be static or dynamic. Default parameters are passed straight into requests - users are never asked to provide values for these.

Optional parameters

Optional parameters are those that you want to expose to your users in process flows, and then pass values that they provide into your API requests (via the URL, header, or body).

Any optional parameters that you define are displayed as filter parameters for a connection shape when a user selects the associated instance/endpoint. Essentially, you are defining filter options for users to apply in process flows. For example:

Adding optional parameters

When you choose to add an optional parameter, you're prompted to complete the fields as below:

Use the following table as a guide for completing these fields:

Optional parameter type examples

As noted above, the parameter type selected determines the user experience of updating this parameter (via connection shapes) in process flows. Below is an example of each parameter type, so you can see the resulting behaviour in a process flow.

Updating & removing parameters

Having added a parameter, you can simply click its name to access details in edit mode - for example:

From here, you can edit key and value fields, or choose the delete this entry - for example:

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 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>

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

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

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.

Introduction

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

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 method is similar to the link header 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 the NetSuite SOAP connector. It should not be used with other systems.

Pagination options

Special notes

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

Introduction

All endpoints must be associated with a data schema - a formal description which defines the structure of associated data. The required schema for your third-party application should be available in the associated API documentation.

When you add a schema, you can also choose to apply field tags and set which (if any) fields are tracked.

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

Use the data path field to define the hierarchical level to be used for field tags and filters:

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.

What we actually want is 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:

When you save your new data path, you won't see any changes to the schema - but the change will be applied in the field tagging tab. Here, the schema preview shows the structure that applies as per your selected data path in the schema tab.

When you come to use instances of this connector in process flows and apply a filter shape, you'll see confirmation of the selected data path in filter settings - for example:

Introduction

To access field tags, edit an endpoint for your connector and select the schema/taxonomy tab - for example:

• Add a new field tag

• Change an existing field tag

• Remove a field tag

Adding a new field tag with/without tracking

Follow the steps below to add a new field tag for your schema:

Step 1 Click the add new tag button:

...the edit field tags modal is displayed:

Step 3 Move down to the select tags field and find a tag to apply from the Patchworks field tag taxonomy- for example:

Step 4 Click anywhere outside of the list of fields to confirm your selection.

Step 5 If you want to track this field, click the tracked checkbox to enable this option:

Step 6 Save the tag - for example:

...the new tag is added to your list:

Changing an existing field tag

Follow the steps below to update an existing field tag for your schema: