Quick Start

Overview

In this guide, we’ll walk through how to get started building integrations with Alloy Embedded. Alloy Embedded is the easiest and fastest way to go live with not just one but hundreds of pre-built, maintained, and powerful integrations. Offering your users integrations with Third Party Apps (3PA) has increasingly become an essential part of any successful SaaS product. But building and maintaining dozens of robust integrations require a sizable time and financial commitment that ultimately takes time away from your product roadmap. Enter Alloy Embedded. Alloy Embedded is an Embedded iPaaS product designed to streamline building native integration experiences. Let us handle the complexity of managing integrations – just implement our SDK once and build integrations with ease. In this Quick Start guide, you’ll learn how to create comprehensive integrations with the Alloy Embedded platform. We’ll cover the following topics:

Key concepts
How to build an integration
How to add Alloy Embedded to your application
Going live

Prior to reading this guide, we strongly recommend reviewing our Terminology page as we’ll be mentioning these terms throughout this guide. Grab a cup of coffee and let’s dive in!

Key Concepts

Before we begin, let’s align on a handful of key terms:

Term	Definition
ISV	We refer to you as the Independent Software Vendor (ISV). The ISV determines what integrations to build and show in their application
End User	We refer to the users/clients of your application as users or end users. Users authenticate their credentials and choose which integrations to install. Users interact with your platform and connect their integrations using the Alloy Embedded modal behind the scenes.
Integrations	An integration is a combination of workflows centered around a Third Party Application. For example, you could build a Shopify integration with three workflows: (a) workflow #1 sends order data to your data warehouse every time a Shopify order is placed, (b) workflow #2 syncs customer data to your data warehouse, and (c) workflow #3 tags a customer in Shopify when a user clicks a button on your site.
Workflows	Workflows define exactly what should happen when any given event occurs. A workflow consists of an event (also known as a “trigger”) and a destination (also known as an “action block”). An event initiates the workflow. A destination defines where the data from the event should be routed to (e.g. assume you built a workflow that creates a new contact in NetSuite every time a customer signs up in your app. In this scenario, the event is triggered whenever a customer signs up in your application and the destination is NetSuite).
Installation	You build workflows and integrations using our visual interface, known as the Alloy Workflow Builder. Every time an end user installs a workflow, they create a copy of the template you’ve built. Each user-specific copy of the template is called an installation. You can think of a workflow like a class in programming. The template you build in the Alloy Workflow Builder defines the general structure of your flow. When your end user installs that workflow, they create an instance (i.e. an installation) of that workflow specific to them.
Alloy Modal	Often referred to as just the “modal”, the Alloy Modal is part of our Frontend JavaScript SDK and is used to collect the details from users needed to setup and configure an integration (example below).

Integration Structure

Before we build our first integration, let’s take a moment to plan it. Assume you’re a software engineer at AcmeCo were given the following product requirements: We’ll need to build two workflows to support this use case:

Workflow #1: When a new order is created in BigCommerce, create a new record in AcmeCo
Workflow #2: When a fulfillment status is updated in AcmeCo, update the order status in BigCommerce

Info:AcmeCo wants to offer a BigCommerce integration to its customers. The integration must support bi-directional data syncing. It should update the order record’s status in the linked BigCommerce store every time a fulfillment status is updated in AcmeCo’s systems. Also, AcmeCo needs to be alerted each time an order is placed in the client’s BigCommerce store.

Building the Integration

Let’s start designing your first integration with the Alloy Embedded Workflow Builder. Let’s assume your company, AcmeCo, is a fulfillment management tool. As per the product requirements above, we’ll need to design the two workflows to satisfy the task.

Selecting the Integration

Navigate to the Alloy Embedded dashboard and select New Integration > then locate BigCommerce.

Workflow #1: BigCommerce → Your App

To create a workflow click New Workflow. This will create your first workflow and take you inside the Alloy Workflow Builder.

From here, let’s build out the Workflow #1. As a reminder, Workflow #1 must function as follows:

Info:When a new order is created in BigCommerce, create a new record in AcmeCo

First, give your workflow a descriptive name on the top left corner of the workflow builder. Click the “Untitled Workflow” text to enter a name as seen below.

Next, select BigCommerce Trigger as your event. Selecting BigCommerce as the event tells Alloy Embedded where to listen for incoming events. From the inputs section on the left hand side, select the order created event. Quite literally, you’re telling Alloy Embedded to trigger this workflow each time a new order is created in your end user’s BigCommerce store.

Lastly, locate the “Stream Data” block. Once you’ve selected it, enter the URL of the destination where you want to stream the BigCommerce order data. This URL should be a server that can accept incoming POST requests made by Alloy Embedded. The Stream Data block will make an API call to your server each time the BigCommerce event is invoked.

When you’re done, hit the “Release this Version” button to publish the workflow. This will make it available to your users for installation via the frontend SDK – more on that in a minute. Just like that you’ve built your first workflow with Alloy Embedded.

Info:In this example, we elected to stream data to our own webhook server via the Stream Data block. However, you can also send data to any of our various destination blocks including data warehouses like Snowflake, databases like MySQL, or even ingestion pipelines like Amazon EventBridge.

Workflow #2: Your App → BigCommerce

Next, let’s build the second workflow. As a reminder, Workflow #2 must function as follows:

Info:When a fulfillment status is updated in AcmeCo, update the order status in BigCommerce.

This time around, instead of using a Third Party App as the event trigger, this workflow will be triggered from your application. Let’s build that now. Create a new workflow and give it a detailed name like before. Select the Custom Event as the event trigger.

Info:A Custom Event is a special type of event block that allows you to specify your own payload to trigger a workflow. Because we want to update an order status in BigCommerce from AcmeCo’s application, we’ll use Custom Event.

Custom Event requires you define an Event Schema. The Event Schema Make represents the structure of the data you’ll be sending over from your application. The values of the JSON you write should be dummy text. When you invoke the Custom Event from your application, be sure to pass over real data. Sample Custom Event Schema

JSON

{
  "orderId": "String",
  "status": "String"
}

Once you’ve created your Custom Event, be sure to give it a name – in this example, we’ll call our event Fulfillment Updated.

Note:Once you’ve defined a custom event, you can reuse that event across multiple workflows – any workflows with that event will be automatically invoked. To invoke a custom event, you can do so via our SDKs or with the Run Event endpoint.

Next, select BigCommerce as your destination. Select the “update an order status” under Block Action. Then select the input parameters that will be passed to BigCommerce. This is called data mapping. Here, you’ll map the orderId value from the Custom Event to the Order field in BigCommerce. Data Mapping tells Alloy Embedded which values from one app should be mapped to the other, in this case, which values from the Custom Event should be sent over to BigCommerce.

When you’re done, once again click Release this Version. Good work!

Setting up the Code

Authentication

Congratulations on building your first integration. With that behind us, let’s switch gears and start configuring your application to work with Alloy Embedded. In order to make calls to the Alloy Embedded API, you will need to obtain an API key. Your Alloy Embedded API key is used to authenticate all API requests. API Keys are meant to be kept secret and should never be shared publicly (we recommend storing your API key in a secure location like AWS Secrets Manager). Navigate to the Embedded Settings page. From here, select API Key and under the Development Environment box, click Generate API Key. Since we’re just building, we’ll want to use this key for testing purposes. When you’re ready to go live, make sure to switch to the Production Environment key.

Creating a User

Using the API key, let’s make our very first API call. Before you can install an integration, you first need to create a user. An end user in Alloy Embedded represents a tenant/client in AcmeCo’s application. Any integrations/workflows your clients install will be linked to this end user account. Typically, we recommend creating an Alloy Embedded end user each time a new user is created in your application. To create a new end user, make an API call to the POST Create User endpoint. We’ve included an example below. Be sure to pass your API key along in the header. This endpoint requires a username and an (optional) fullName be passed over. Note that the username must be a unique value. Sample Request

curl --request POST \
    --url https://embedded.runalloy.com/{VERSION}/users \
    --header 'Accept: application/json' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: bearer YOUR_API_KEY' \
    --data '{ "username": "gregg" }'

This endpoint returns a userId as seen below. Depending on how you architect your system, you might want to store this identifier for later use in your database. Sample Response

JSON

{
  "userId": "xyz123abc098754"
}

Listing Integrations

Now that you’ve created your first user, let’s next make a call to the GET Integrations endpoint. This API returns a list of all the integrations in your Alloy Embedded account. Typically, ISVs use this endpoint to power an integrations page. Sample Request

curl --request GET \
     --url 'https://embedded.runalloy.com/{VERSION}/integrations?userId=<YOUR_USER_ID>' \
     --header 'accept: application/json'
     --header 'Authorization: bearer YOUR_API_KEY'

Note:you must pass the userId as a query string parameter when invoking this endpoint. This parameter tells Alloy Embedded who to return a list of integrations for.

Sample Response

JSON

{
  "data": [
    {
      "integrationId": "63ea758e82c3074141968bb9",
      "app": "BigCommerce",
      "installed": false,
      "icon": "https://cdn.runalloy.com/icons/magento.png",
      "workflows": [
        {
          "workflowId": "63ea75a2fcf2e2c72e805ddc",
          "name": "> When a new order is created in BigCommerce, create a new record in AcmeCo",
          "installed": true,
          "version": 1,
          "installedVersion": 1,
          "active": true,
          "blocks": [
            {
              "name": "Custom Event",
              "id": "bc9202b2-8e7e-47d4-9416-5ba6b319fa2a",
              "type": "customEvent",
              "icon": "https://cdn.runalloy.com/icons/app-event.svg"
            },
            ...
          ]
        }
      ]
    },
}

This endpoint returns an array of integrations. Note the installed parameter which returns a boolean indicating if the end user has previously installed this integration.

Example Integrations Page

To see this in action, below you’ll find an example of Postscript, an Alloy Embedded customer, using the Get List Integrations endpoint to power their apps page. Figure 1.1 – Example Integrations Page This is a live customer (Postscript) using Embedded to power their integrations. Behind the scenes, the GET Integrations endpoint populates the data for this page.

A few things to note:

Response Structure: Each integration that’s returned by the GET Integrations endpoint, we return an array of workflows which each contain a corresponding workflowId
Installed Status: this endpoint also returns a status indicating if the workflow has been installed by the user yet. This is denoted by the installed key which has a boolean value of true or false.
Version: notice the installedVersion and version keys. The version key reflects the most updated and currently released version available. The installedVersion represents the latest version the specified user has installed. If the version is greater than the installedVersion you’ll want to prompt your users to update to the latest version.

Next, let’s take a look at how to install an integration. We’ll need to present the Alloy Modal so we can collect some basic authentication details. In Figure 1.2 below, you’ll find an example of the Alloy Modal showcasing our BigCommerce integration. Figure 1.2 – Alloy Modal

Installing the Frontend SDK

Our frontend SDK allows you to instantiate the Alloy Modal within your application. To install the frontend SDK, you have two options:

Install via npm
Import the vanilla JS snippet into the header of your application

npm install alloy-frontend

You can read more about the Frontend SDK here.

Note:The demo site comes pre-installed with the Frontend SDK so no need to import it in the demo project

Once you’ve imported the Frontend SDK, the next step is to render the modal. But before you can render the Alloy Modal in your frontend, you’ll need to generate a short-lived JSON Web Token (JWT) on your server.

Generating Short-Lived JWT

To generate a short-lived JWT, we need to invoke the GET /user/:userId/token endpoint on your backend. You can find an example cURL request below. Sample Request

curl --request GET \
     --url https://embedded.runalloy.com/{VERSION}/user/:userId/token \
     --header 'Accept: application/json' \
     --header 'Authorization: bearer YOUR_API_KEY'

This endpoint returns a JSON Web Token which looks something like the below. You’ll want to pass this to your frontend. Note that this token is only valid for an hour so you’ll need to regenerate it again each time you intend to render the modal. Also note that the JWT is user-specific meaning that you’ll need to generate a new token for each user.

JSON

{
  "token": "XXXXXXXX.YYYYYYYYY.ZZZZZZZZ"
}

Frontend SDK Methods

Once you’ve passed the JWT to your frontend, pass the JWT as an argument to the Alloy.setToken() method on the frontend. The setToken() method sets the JWT for this instance of the Alloy SDK and makes it available in every subsequent SDK method you call. All frontend SDK methods require that you must first invoke setToken().

Note:If you’re interacting with the Alloy.js SDK from a react app, you can call these methods by invoking window.Alloy.install().

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

JavaScript

JavaScriptAlloy.setToken("<YOUR_TOKEN>");

Once you’ve set the token, call the Alloy.install() method to show the modal. This endpoint takes an integrationId as an argument. Sample Method

JavaScript

JavaScriptAlloy.install({
  integrationId: "YOUR_INTEGRATION_ID",
  callback: () => {
    console.log();
  },
});

If you’ve done everything correct, you should see a popup in the frontend. Next, let’s take a look at how to trigger your integration.

Triggering a Custom Event

Recall that Workflow #2 uses a custom event, and should only be triggered whenever an event happens on your application. In this section, we’ll take a look at how to trigger a custom event. We previously defined the following Custom Event schema to be as follows:

JSON

{
  "orderId": "String",
  "status": "String"
}

To invoke the Custom Event, make an API call to the POST Run Event endpoint. You’ll need to pass over the event name (i.e. Fulfillment Updated) and the corresponding userId you want to invoke the event for. Pass along any data you defined in Custom Event schema. Any workflows using this Custom Event will immediately be triggered.

cURL

curl --request POST \
   --url https://embedded.runalloy.com/{VERSION}/run/event \
   --header 'accept: application/json' \
   --header 'content-type: application/json' \
   --header 'Authorization: bearer YOUR_API_KEY' \
   --data '{
      "event": "Fulfillment Updated",
      "userId": "00001",
      "data": {
          "orderId": "123",
          "status": "FULFILLED"
      }
 }'

Congratulations, you have now successfully invoked a Custom Event on Alloy Embedded.

Going Live

We’re almost done. In this section, we’ll look at putting the finishing touches on our implementation before we call it quits. Alloy Embedded supports a number of features to reduce friction when debugging. To view workflow logs, invoke the GET Error Logs endpoint. This endpoint accepts a workflowId and returns basic log information about the error. Sample Request

cURL

curl --request GET \
     --url https://embedded.runalloy.com/{VERSION}/workflows/:workflowId/errors \
     --header 'Accept: application/json' \
     --header 'Authorization: bearer YOUR_API_KEY'

The response data includes the error message, the block that errored, and the errorOccurredAt date stamp. Sample Response

JSON

{
  "data": [
    {
      "workflowId": "WORKFLOW_ID",
      "block": "bigcommerce",
      "errorOccurredAt": "2024-09-17T22:12:34.567Z",
      "message": "The customer failed to create due to an invalid Id"
    }
  ]
}

You can also configure Alloy Embedded to stream error logs in real time to a webhook on your server, Datadog, AWS EventBridge, or any other logging service via our Embedded Logs APIs. Navigate to the Settings → Logging section in Alloy Embedded and select the Route Error Logs option.

To stream logs to AWS EventBridge, select the Connect to AWS EventBridge option. To stream logs to Datadog, select the Connect to Datadog option. For more on streaming logs to Datadog, see here.

Deactivating and Re-activating Workflows

To deactivate a workflow, invoke the PUT /workflows/deactivate endpoint by passing in the userId and the workflowId. Similarly, you can reactivate the workflow at any time by invoking the PUT /workflows/activate endpoint with the same structure as below. Sample Request

cURL

curl --request PUT \
     --url https://embedded.runalloy.com/{VERSION}/workflows/deactivate \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'Authorization: bearer YOUR_API_KEY' \
     --data '{
     "userId": "00001",
     "workflowId": "632531cf3beb6c98611abd09"
   }'

Upgrading Workflows

Every time you make a change to a live workflow, you’ll need to release an update. Users can be prompted to update their installation by calling the PUT workflows/ {workflowId} /upgrade endpoint. To use this endpoint, the new workflow must have the same configurable fields as the original. If any new configurable fields were added, you will not be able to upgrade the workflow programmatically and instead would need to reinstall the workflow for the end user.

Workflow Logs

To return specific data about a workflow (e.g. historical success messages), make a request to the GET /workflow/:workflowId/logs endpoint. This endpoint returns an array of executions. An execution represents a single workflow run. For example, if the workflow has been invoked 100 times, you’ll be able to see 100 invocations and the associated logs for each invocation. Sample Request

cURL

curl --request GET \
     --url 'https://embedded.runalloy.com/{VERSION}/workflows/:workflowId/logs?userId=:userId' \
     --header 'accept: application/json' \
     --header 'Authorization: bearer YOUR_API_KEY'

Note:Alloy Embedded stores logs for 7 days. Any logs older than 7 days are automatically deleted and cannot be retrieved.

Compliance

To handle GDPR and CCPA compliance requests, we’ve built a deletion endpoint to purge user-related data. Sample Request

cURL

curl --request DELETE \
     --url https://embedded.runalloy.com/{VERSION}/users/:userId/logs \
     --header 'Accept: application/json' \
     --header 'Authorization: bearer YOUR_API_KEY'

Wrapping Up

In this article, we’ve looked at how to build an integration with Alloy Embedded, how to set up an integration and how to configure it to stream data bidirectionally. As always, please refer to our API reference. We’re constantly improving Alloy Embedded, so if you have thoughts, questions, suggestions, please don’t hesitate to reach out to your support representative. Happy building!

Getting Started

Advanced Features

Headless

Tutorials

Troubleshooting

Overview

Key Concepts

Integration Structure

Building the Integration

Selecting the Integration

Workflow #1: BigCommerce → Your App

Workflow #2: Your App → BigCommerce

Setting up the Code

Authentication

Creating a User

Listing Integrations

Example Integrations Page

Installing the Frontend SDK

Generating Short-Lived JWT

Frontend SDK Methods

Triggering a Custom Event

Going Live

Deactivating and Re-activating Workflows

Upgrading Workflows

Workflow Logs

Compliance

Wrapping Up

Getting Started

Advanced Features

Headless

Tutorials

Troubleshooting

​Overview

​Key Concepts

​Integration Structure

​Building the Integration

​Selecting the Integration

​Workflow #1: BigCommerce → Your App

​Workflow #2: Your App → BigCommerce

​Setting up the Code

​Authentication

​Creating a User

​Listing Integrations

​Example Integrations Page

​Installing the Frontend SDK

​Generating Short-Lived JWT

​Frontend SDK Methods

​Triggering a Custom Event

​Going Live

​Deactivating and Re-activating Workflows

​Upgrading Workflows

​Workflow Logs

​Compliance

​Wrapping Up

Overview

Key Concepts

Integration Structure

Building the Integration

Selecting the Integration

Workflow #1: BigCommerce → Your App

Workflow #2: Your App → BigCommerce

Setting up the Code

Authentication

Creating a User

Listing Integrations

Example Integrations Page

Installing the Frontend SDK

Generating Short-Lived JWT

Frontend SDK Methods

Triggering a Custom Event

Going Live

Deactivating and Re-activating Workflows

Upgrading Workflows

Workflow Logs

Compliance

Wrapping Up