> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runalloy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

<Info>
  **Note**:

  If you are using the Frontend Modal, you **must** use our Frontend JavaScript SDK. For other presentation options such as the Embedded Link or Headless, the frontend JavaScript SDK is not required.
</Info>

Our Frontend SDK makes it easy to get started with Embedded iPaaS. The Frontend SDK is used to render the Embedded iPaaS modal and manage workflow installations for your end users.

## Installation

Install the package with npm:

```sh theme={null}
npm install alloy-frontend
# or
yarn add alloy-frontend
```

Alternatively, you can install the SDK as vanilla JavaScript by adding the script tag to the header of your site:

```html HTML theme={null}
<script
  src="https://cdn.runalloy.com/scripts/embedded.js"
  type="text/javascript"
></script>
```

When interacting with the Frontend Modal via vanilla JavaScript, you can access the Alloy library using the `window` object.

## Setting Your Token

Before using any SDK methods, you must set your JWT token. As mentioned [here](/reference/embedded/generate-jwt-token), a JWT is required to securely authorize the user. Once you've retrieved your short-lived token from the Embedded APIs, set it in the frontend SDK using the `setToken` method:

```javascript JavaScript theme={null}
Alloy.setToken("<YOUR_TOKEN>");
```

All frontend SDK methods require that you first invoke `setToken`.

## Rendering the Frontend Modal

To render the Alloy Modal for your user, call the `install` method. This displays the modal specific to the JWT you generated.

### Standard Installation

The `install` method accepts the following parameters:

| Parameter                  | Type    | Description                                                                                                                                                                          |
| :------------------------- | :------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `integrationId`            | String  | The Id of the integration you want to display.                                                                                                                                       |
| `workflowIds`              | Array   | An array of workflow IDs to install. Use this to prompt users to install specific workflows.                                                                                         |
| `callback`                 | N/A     | A callback function invoked when the user has successfully installed their workflow from the Alloy Modal.                                                                            |
| `workflowSelection`        | boolean | Allows the end user to select which workflows they want to install. Defaults to false. When set to true, it provides a toggle-list for users to choose which workflows to install.   |
| `alwaysShowAuthentication` | boolean | Always shows the authentication step in the Alloy Modal when set to `true`. By default, the authentication screen is hidden if the user has already authenticated the required apps. |
| `hide`                     | boolean | Hides the entire Alloy Modal if the user has already authenticated the required apps **and** the workflow does not require any configuration in the second step.                     |
| `title`                    | String  | Shows a custom title in the Alloy Modal.                                                                                                                                             |

**Example: Installing all workflows in an integration**

```javascript JavaScript theme={null}
Alloy.install({
  integrationId: "YOUR_INTEGRATION_ID",
  callback: (res) => {
    console.log({
      credentials: res.credentials,
      userId: res.userId,
    });
  },
  alwaysShowAuthentication: true,
  hide: false,
  title: "My Cool Shopify Integration",
});
```

**Example: Installing specific workflows**

```javascript JavaScript" theme={null}
Alloy.install({
  workflowIds: ["YOUR_WORKFLOW_ID", "YOUR_WORKFLOW_ID"],
  callback: (res) => {
    console.log({
      credentials: res.credentials,
      userId: res.userId,
    });
  },
  alwaysShowAuthentication: true,
  hide: false,
  title: "Cool Alloy Workflows",
});
```

### Dynamic Configuration

In some cases, you may need to pre-fill values or dynamically configure workflows based on user-specific data. For example, if each of your users has a unique form with different fields, you can pass that data to Alloy to properly configure the workflow.

When using dynamic configuration, the `install` method supports additional parameters:

| Parameter         | Type  | Description                                                                                                   |
| :---------------- | :---- | :------------------------------------------------------------------------------------------------------------ |
| `preFilledValues` | Array | Pre-fills values for your end user when no configuration is required by them.                                 |
| `outputOverride`  | Array | Dynamically displays available dynamic values to your end user, allowing them to configure workflow mappings. |

**Pre-filled Values Structure**

| Field          | Type   | Description                                                                                           |
| :------------- | :----- | :---------------------------------------------------------------------------------------------------- |
| `fieldName`    | string | The name of the field the value would be passed to.                                                   |
| `value`        | string | The value you would like to pre-fill on behalf of your end user rather than having them configure it. |
| `displayValue` | string | A beautified version of the value that you want to display to your end users.                         |

**Example: Installing workflows with dynamic configuration**

```javascript JavaScript expandable theme={null}
Alloy.install({
  workflowIds: ["YOUR_WORKFLOW_ID", "YOUR_WORKFLOW_ID"],
  callback: () => {
    console.log();
  },
  preFilledValues: [
    {
      workflowId: "YOUR_WORKFLOW_ID",
      connectorId: "YOUR_CONNECTOR_ID",
      data: [
        {
          fieldName: "formId",
          value: "abc123gjigwjio232r23",
          displayValue: "My Pretty Form Name",
        },
      ],
    },
  ],
  outputOverride: [
    {
      workflowId: "YOUR_WORKFLOW_ID",
      connectorId: "YOUR_CONNECTOR_ID",
      data: { "What is your name": "xyz", "What is your age": "18" },
    },
  ],
  alwaysShowAuthentication: true,
  hide: false,
  title: "Cool Alloy Title for my Cool Workflows",
});
```

## Updating a Workflow

When a new workflow version is released that is newer than the currently installed version, you'll want to prompt users to upgrade to the latest version.

<Info>
  **Updating Workflows**:

  You can tell when a workflow needs to be updated by comparing the payload returned from the [List Integrations](/reference/embedded/list-integrations) or [List Workflows](/reference/embedded/list-workflows) endpoints. When the `version` is greater than the `installedVersion` value, you should prompt the user to update their workflow.
</Info>

To update a workflow, invoke the `update` method. This method allows you to update a workflow and accepts the same parameters as `install`. The `update` method does not accept an `integrationId` and only works with `workflowIds`.

```javascript JavaScript theme={null}
Alloy.update({
  workflowIds: ["YOUR_WORKFLOW_ID", "YOUR_WORKFLOW_ID"],
  callback: () => {
    console.log();
  },
  alwaysShowAuthentication: true,
  hide: false,
  title: "Cool Alloy Workflows",
});
```

Note that the `update` method does not allow you to specify a version to update to. Instead, it defaults to the most recently released version (as specified by the `version` key in the [List Workflows](/reference/embedded/list-workflows) endpoint).

## Editing a Workflow

You may want to allow users to edit a workflow after they have installed it. For example, if your user installed a workflow that sends them a message in Slack every time an event happens, they might need to customize the "channel" parameter. Later, they may decide to change their selection.

The `edit` method allows you to present the modal again so users can modify their configuration:

```javascript JavaScript theme={null}
Alloy.edit({
  workflowIds: ["YOUR_WORKFLOW_ID", "YOUR_WORKFLOW_ID"],
  callback: (res) => {
    console.log({
      credentials: res.credentials,
      userId: res.userId,
    });
  },
  alwaysShowAuthentication: true,
  hide: false,
  title: "Cool Alloy Workflows",
});
```

The `edit` method does not accept an `integrationId` and only works with `workflowIds`.

## List all Workflows

You can list all workflows for a user by invoking the `getWorkflows` method:

```javascript JavaScript theme={null}
Alloy.getWorkflows();
```

## List all Integrations

You can list all integrations for a user by invoking the `getIntegrations` method:

```javascript JavaScript theme={null}
Alloy.getIntegrations();
```

## Deactivate a Workflow

You can deactivate a workflow by `workflowId` or `name` using the `deactivate` method:

```javascript JavaScript theme={null}
Alloy.deactivate({
  workflowId: "YOUR_WORKFLOW_ID",
});

// OR

Alloy.deactivate({
  workflowName: "Shopify to Snowflake",
});
```

## Activate a Workflow

Similarly, you can activate (or reactivate) a workflow by its `workflowId` or `name` using the `reactivate` method:

```javascript JavaScript theme={null}
Alloy.reactivate({
  workflowId: "YOUR_WORKFLOW_ID",
});

// OR

Alloy.reactivate({
  workflowName: "Shopify to Snowflake",
});
```