# 2: Connector variables

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

| Level                                                                                                                                                                                                 | Summary                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Connector instance (connector variables)](#what-you-need-to-do)                                                                                                                                      | **Connector instance variables** defined here can be used when you [configure authentication methods](/product-documentation/developer-hub/connector-builder/building-your-own-connector/3-authentication-methods/authentication-method-options.md). If you're defining multiple authentication methods which share common variables, define them once here and then choose to 'use' them in subsequent authentication methods. |
| [Authentication method (auth variables)](/product-documentation/developer-hub/connector-builder/building-your-own-connector/3-authentication-methods/authentication-method-options/auth-variables.md) | **Auth variables** (whether added directly or picked up and 'used' from predefined **connector instance variables**) are displayed as fields for your users to complete whenever the associated authentication method is used to [add a connector instance](/product-documentation/connectors-and-instances/working-with-instances/adding-an-instance.md).                                                                      |
| [Endpoint variables](/product-documentation/developer-hub/connector-builder/building-your-own-connector/4-endpoints/endpoint-options/endpoint-variables.md)                                           | **Endpoint variables** are displayed as fields for your users to complete whenever they configure a process flow connection shape to use an associated endpoint.                                                                                                                                                                                                                                                                |

## About connector instance variables

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

<figure><img src="/files/3ECnwkjoJmSCVbE1dz5C" alt=""><figcaption></figcaption></figure>

Users are prompted to provide values for these variables when they [add and authenticate an instance of this connector](/product-documentation/connectors-and-instances/working-with-instances/adding-an-instance.md). These values are then applied wherever this instance is used in process flows.&#x20;

## How it works

Any variables defined here are available for use when you move on to define [authentication methods](/product-documentation/developer-hub/connector-builder/building-your-own-connector/3-authentication-methods.md) for your connector.&#x20;

If you [choose to use one of these variables in an authentication method](/product-documentation/developer-hub/connector-builder/building-your-own-connector/3-authentication-methods/authentication-method-options/auth-variables.md#adding-auth-variables), the result will be that your users are asked to provide a value for this field when they [add an instance](/product-documentation/connectors-and-instances/working-with-instances/adding-an-instance.md) of this connector, with the associated authentication method.&#x20;

**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](/product-documentation/process-flows/about-process-flows.md) 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.

{% hint style="info" %}
In the Patchworks connector builder, variables must be defined in double curly brackets.
{% endhint %}

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

{% code title="GET" %}

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

{% endcode %}

All API calls that users might want to use in [process flows](/product-documentation/process-flows/about-process-flows.md) are added to the Shopify connector as [endpoints](/product-documentation/developer-hub/connector-builder/building-your-own-connector/4-endpoints.md). So, when a user configures a [connection shape](/product-documentation/process-flows/building-process-flows/process-flow-shapes/standard-shapes/connector-shape.md) 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:

<figure><img src="/files/AWsT7kJ0y8zvqUGfPfmw" alt=""><figcaption></figcaption></figure>

Whilst you COULD ask your users to enter the appropriate store name whenever they select an endpoint (via an [endpoint variable](/product-documentation/developer-hub/connector-builder/building-your-own-connector/4-endpoints/endpoint-options/endpoint-variables.md)), this would be inefficient, and open to error. &#x20;

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](/product-documentation/connectors-and-instances/working-with-instances/adding-an-instance.md) - for example:

<div align="left"><figure><img src="/files/Ryfsfmt7VLLPn9u4zKUn" alt="" width="375"><figcaption></figcaption></figure></div>

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.&#x20;

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](/product-documentation/developer-hub/connector-builder/building-your-own-connector/4-endpoints/endpoint-options/endpoint-variables.md), 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: &#x20;

<div align="left"><figure><img src="/files/23GiXVX68jJWdvJwpwKs" alt=""><figcaption></figcaption></figure></div>

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

<div align="left"><figure><img src="/files/CHSICuXLqARckr7XmpFh" alt=""><figcaption></figcaption></figure></div>

{% hint style="info" %}
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](/product-documentation/developer-hub/connector-builder/building-your-own-connector/techniques-for-working-with-variables-and-parameters/working-with-variables.md) page.

For guidance on configuring variables for specific **authentication types**, please see our [Supported authentication types](/product-documentation/developer-hub/connector-builder/building-your-own-connector/3-authentication-methods/supported-authentication-types.md) section.
{% endhint %}

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

<figure><img src="/files/tdFIy2jWn56sgWjjp8XE" alt=""><figcaption></figcaption></figure>

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

**Step 5**\
Click **next** for [authentication methods](/product-documentation/developer-hub/connector-builder/building-your-own-connector/3-authentication-methods.md), where you can choose to use these variables, if needed.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://doc.wearepatchworks.com/product-documentation/developer-hub/connector-builder/building-your-own-connector/2-connector-variables.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.