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

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

In this example, we've already defined two auth variables for username and password, so users will be prompted to enter these details when adding an instance of this connector for use in process flows.

How we then pass this information into API requests is determined by the API documentation for the underlying third-party application. Often, these details are passed in request headers, but sometimes it will be via the request body.

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

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

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

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

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

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 :

How it works

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

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:

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.

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.

In this section

Introduction

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

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

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.

Adding auth variables

To add an auth variable, follow the steps below:

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:

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

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:

Dynamic values

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

In this section

• Basic authentication

• Token-based authentication

• OAuth 2 (client credentials)

• OAuth 2 (authorisation code)

• OAuth 1

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

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

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

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

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

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

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 .

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.

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

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 (client credentials 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 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 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 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.

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:

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?

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

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.

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

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

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

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

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

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:

In this section

• Authentication

• Variables

• URL

• Header

• Body

• Pagination

• Schema

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

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

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

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

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 are added as key pairs and are always applied for the endpoint, whenever it is used. Use the top panel to add required parameters.

• Optional parameters are displayed as connection shape filters, so users can apply with their own values when using this endpoint as a data source in process flows. Use the lower panel to add optional parameters.

Any parameters that you add (to either panel) here are automatically appended to the existing endpoint URL as a query parameter when this endpoint is used in process flows.

Required parameters

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

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:

By adding this as a default URL parameter for the endpoint, this query will be applied whenever this endpoint is added to process flows (via a connection shape). The actual endpoint used will be:

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 includes a connection shape which is configured to use this endpoint, users can see/update filter fields for any optional URL parameters that have been defined for the endpoint. For example, let's add an optional parameter for product_type:

Now if we configure a process flow connection shape with this endpoint, a product_type filter option is available, so the person running this flow can choose to use it if they wish:

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?

Optional URL parameters are just that - process flow users can choose to add a parameter value if they wish. If a user doesn't choose to update an optional URL parameter field, then no query is applied.

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:

Step 1 Add a 'required' endpoint variable for the field that you want to force users to update in process flows.

Step 2 Update the endpoint URL to include a query for this variable.

Step 3 Add a default URL parameter, specifying your endpoint variable (added in step 1) as the parameter value.

Step 4 Now when a user adds this endpoint to a connection shape in a process flow, they must update this variable field before proceeding.

More information

Techniques for adding URL parameters are 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

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

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

Typically, these are variables that you want your users to update when they configure a process flow connection shape with an instance of your connector, using this 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.

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.

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 2 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 endpoint variables:

• When you add an endpoint variable and choose to make it required, you are effectively saying: 'When a user adds a connection shape to a process flow and selects an instance of this connector together with this endpoint, do not allow them to proceed without providing a value for this variable'.

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

Step 3 Click the save button.

Step 4 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 variable that you define here would then be added to the endpoint URL, or the header, or the body for the endpoint.

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

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.

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

The essence of is to pull defined data from one Patchworks (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 to define where a data field from one connector should be placed in another.

When you build a connector using the , available field mappings are determined by the 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 associated with a connector endpoint.

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

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 to a - each with endpoints that have been fully tagged - you'll find that mappings are automatically created when you add a 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 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:

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:

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:

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

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:

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

Our request for the next page of results would be:

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:

Customers

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

Refunds

Refund line items