In this section

• Authentication

• Variables

• URL

• Header

• Body

• Pagination

• Schema

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

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

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

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

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.

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

More information

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

This method is similar to the 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:

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

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

...and then:

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

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

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

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

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

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

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

Adding a schema

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

Step 1 Click the edit schema button:

Step 2 Paste in the required schema and save changes:

Setting a data path

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

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

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

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

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

Introduction

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

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:

Step 1 Click on an existing tag that you want to change - for example:

...the edit field tags modal is displayed and any existing tags are shown - for example:

Step 2 To remove an existing tag to replace it with another, click the associated 'cross' icon - for example:

...then use the select tags field to find a replacement tag from the Patchworks field tag taxonomy- for example:

Step Save the tag.

Removing an existing field tag

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

Step 1 Click on an existing tag that you want to remove - for example:

...the edit field tags modal is displayed and any existing tags are shown - for example:

Step 2 Remove all existing tags using the associated 'cross' icon - for example:

Step 3 Once all tags are removed, save the tag - for example:

What if there's no field tag for a field in my schema?

Don't worry! The point of field tagging is that we tag the most common fields that Patchworks has identified. If your data schema includes fields where none of our tags apply, there's no need to tag it.

Introduction

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

Introduction

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 . The current taxonomy is detailed in the following sections:

Customers

Fulfillments

Fulfillments line items

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.

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:

If you need to change the existing query for an endpoint, you should and access 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 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:

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:

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:

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:

Inventory items

Inventory levels

Locations

Overview

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

Page number parameter options

Example

Suppose we set the following options:

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

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

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

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

Our request for the next page of results would be:

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

When does pagination stop?

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

Special notes

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

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

Products

Variant

Images

Refunds

Refund line items

Refunds order adjustment

Refund line item discounts

Refund line item tax lines

Refund transactions

Orders

Order lines

Order tax lines

Order line item discounts

Order line items tax lines

Discount details

Shipping address

Shipping line discounts

Shipping lines

Shipping line tax lines