# Adding an instance

## Introduction

Once a [connector is installed](https://doc.wearepatchworks.com/product-documentation/connectors-and-instances/working-with-connectors/installing-a-connector) or built using our [connector builder](https://doc.wearepatchworks.com/product-documentation/developer-hub/connector-builder), it becomes available on your Manage Connectors page. From here, you can add any required instances.

Every *instance* requires *authentication credentials* that allow you to access the associated third-party application - you'll need these to hand before starting the steps detailed on this page. Typically, you'll create one instance for each set of credentials that you have for a given connector that you want to use in [process flows](https://doc.wearepatchworks.com/product-documentation/process-flows/about-process-flows).  

## The steps

To add an instance for one of your installed connectors, follow the steps below.

{% stepper %}
{% step %}
**Access your connectors**

Log in to the [Patchworks dashboard](https://app.wearepatchworks.com/login) and select `process flows` ➤ `connectors & instances` to access the `manage connectors` page.
{% endstep %}

{% step %}
**Launch the instance setup wizard for your connector**

Locate the required connector and click the `add new instance` button. For example:

<div align="left"><figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FZDZzw2ZdU22uupSC8fkM%2Fadd%20instance%20a1.png?alt=media&#x26;token=808d80dc-36aa-4e01-84bc-01d97e213a0e" alt=""><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}
**Launch the instance setup wizard for the required connector**

Enter a `name` for this instance, then click the `next step` button. For example:

<div align="left"><figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FVOMYptsNwH8vzHYR6ChF%2Fadd%20instance%20b1.png?alt=media&#x26;token=9c234651-bf4f-4be8-9d4a-57bce5c63bff" alt="" width="452"><figcaption></figcaption></figure></div>

{% hint style="info" %}
The name entered here is what your users will see when they choose an instance to associate with [connector shapes](https://doc.wearepatchworks.com/product-documentation/process-flows/building-process-flows/process-flow-shapes/standard-shapes/connector-shape) in [process flows](https://doc.wearepatchworks.com/product-documentation/process-flows/about-process-flows).
{% endhint %}
{% endstep %}

{% step %}
**Review & update connector details**

Review the default connector details and update where appropriate - then click the `next step` button:

<div align="left"><figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2Fu80cR46F2x4Dv3gqdhHk%2Fadd%20instance%20c1.png?alt=media&#x26;token=41a7ad0c-7083-42d4-b32a-d2428802ff3b" alt="" width="451"><figcaption></figcaption></figure></div>

{% hint style="info" %}
The settings defined here take effect wherever this instance is configured in process flow [connector shapes](https://doc.wearepatchworks.com/product-documentation/process-flows/building-process-flows/process-flow-shapes/standard-shapes/connector-shape).
{% endhint %}

Available options are summarised below:

<table><thead><tr><th width="226">Option</th><th>Summary</th></tr></thead><tbody><tr><td>Time zone</td><td>Used to convert the time in any date/time filters that are applied when this instance is used in process flows. </td></tr><tr><td>Date format</td><td>The expected date format when this instance is used in process flows.</td></tr><tr><td>Rate limit amount<br>Rate limit unit</td><td><p>Determines the rate at which Patchworks is allowed to make API requests to the associated system when using this instance of the connector. If the rate limit for an instance is exceeded,  remaining requests are queued and sent when the rate limit is released again.  </p><p></p><p>Default settings are provided but you may need to adjust this to suit your specific needs. For example, you might have a plan which allows you a higher rate limit, or you might have multiple instances for the same connector running at the same time, which all need to share a rate limit. If you're not aware of any specific requirements, leave the default settings as they are. </p></td></tr><tr><td>Connection pool</td><td>If the connector associated with this instance has a concurrency limit and you have configured connection pools, these are available for selection here. For more information see our <a href="../../process-flows/building-process-flows/connection-pools">Connection pools</a> page.</td></tr></tbody></table>
{% endstep %}

{% step %}
**Select how this instance should be authenticated**

Choose which `authentication type` you wish to use for this instance, then click the `next step` button:

<div align="left"><figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FH1E3yFIXIfW4ENdaD5EN%2Fadd%20instance%20d1.png?alt=media&#x26;token=9650a5c6-d1c3-4c86-8ba2-6575ea35d4ba" alt="" width="448"><figcaption></figcaption></figure></div>

{% hint style="info" %}
All [authentication methods](https://doc.wearepatchworks.com/product-documentation/developer-hub/connector-builder/building-your-own-connector/3-authentication-methods/authentication-method-options) defined for the underlying connector are available for selection. Often, there will only be one; however, if multiple authentication types are shown, choose the one associated with the credentials that you have available.
{% endhint %}
{% endstep %}

{% step %}
**Provide credentials**

Enter valid credentials for this instance and click `create`. For example:

<div align="left"><figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FZ82egyHom8HUN9T91WQu%2Fadd%20instance%20d1a.png?alt=media&#x26;token=440610a1-4180-4b34-8075-de6d1896a23d" alt="" width="482"><figcaption></figcaption></figure></div>

{% hint style="info" %}
Only valid credentials can be saved. Required credentials will vary, depending on the selected authentication type. If you see an `advanced` section, it's worth reviewing these settings, though typically, these fields don't need to be changed for standard use. If required, you can also upload authentication certificates.
{% endhint %}

{% hint style="info" %}
Currently, `p12` certificates are supported.
{% endhint %}

<details>

<summary><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2F3XunX6DbnKf6wRfDulWp%2Ficons8-info%20(3).svg?alt=media&#x26;token=ddeb7ae5-d7c7-46f5-baf3-55a3d5b1478f" alt="" data-size="line"> Invalid credentials  </summary>

If the credentials that you provide can't be validated, you'll see a failure notification at the top of the page, and a `view details` button is displayed at the bottom - for example:

![](https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FU0eG93AJ67nezR5ntrCX%2Fadd%20instance%20h1.png?alt=media\&token=f96125f5-ef84-41c1-9bce-1d1384b0b432)

Click the `view details` button to view details for the authentication request and response. For example:

![](https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FCDv8syumyzTuK9UR4zL0%2Fadd%20instance%20h2.png?alt=media\&token=5afc27b7-abb2-4f5e-81b3-8fed7eebad60)\
\
The `request` tab confirms any information passed for validation, and the `response` tab shows response information for the authentication request. Here you'll see a response code, body content (typically the failure message associated with the response code) and header details.

</details>
{% endstep %}

{% step %}
**The instance is ready for use**

The instance is created for the associated connector and is now shown on the `manage connectors` page - for example:

<div align="left"><figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FkviTWihJI5AS687GWQDy%2Fadd%20instance%20e1.png?alt=media&#x26;token=4a8536ae-37b8-4ba3-8134-d0f0fa34b3ee" alt=""><figcaption></figcaption></figure></div>

Once an instance is added, it becomes available for selection in [connection shapes](https://doc.wearepatchworks.com/product-documentation/process-flows/building-process-flows/process-flow-shapes/standard-shapes/connector-shape) when you [build process flows](https://doc.wearepatchworks.com/product-documentation/process-flows/building-process-flows).&#x20;
{% endstep %}
{% endstepper %}