---
description: Integration Templates, Wizard Builders and Wizards.
---

# Integration Templates

## What is an Appmixer Integration? <a href="#what-is-an-appmixer-integration" id="what-is-an-appmixer-integration"></a>

Appmixer Integration is another way how to offer Appmixer flows to your end-users. Integration is just an ordinary flow with the additional `wizard` property.‌

Let's consider the following simple scenario: we want to offer a simple Slack alarm to our end-users. The flow will contain two components and will look like this:

![](https://3844357853-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LATDgYqVMe0hChW7efU%2F-MZqfAIKcHOH_LVJchrs%2F-MZqtLAxBgQBKJr_njWG%2FAppmixer_SDK.png?alt=media\&token=1995e4ed-5561-4aa5-a22e-368090716fb8)

There is a Scheduler component that will trigger the flow and a Slack component that sends a message. The _SendChannelMessage_ component was renamed to _Slack Alarm._ Components will be displayed in the Wizard builder by their name, it is a good practice to name them after their function. In the next step, we will create a Wizard that will allow the end-user to configure and run such flow, but with a much simpler UI interface.

Open with _Wizard Builder_ from the main Designer menu:

![](https://3844357853-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LATDgYqVMe0hChW7efU%2F-MZqfAIKcHOH_LVJchrs%2F-MZquO8EWt3T1z9jmaNZ%2FAppmixer.png?alt=media\&token=967501e7-3147-47ab-8bcb-3ca92d43c31f)

Wizard Builder window will open:

![](https://3844357853-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LATDgYqVMe0hChW7efU%2F-MZqfAIKcHOH_LVJchrs%2F-MZqn8C4_rKu7hmLmJ87%2FSkitch.png?alt=media\&token=4eca54a3-6528-4f5e-b05d-2410a9ec4d7d)

On the left side, there are fields (inputs) that the end-user will have to set/fill in. There is a component in the flow that requires user authentication (Slack). Therefore the _Slack account_ input with a lock icon is displayed in the top left corner. If the flow contains other components that require user authentication, all of them will be displayed there. Then we want the user to set the alarm - set hour and minute. The final Wizard will contain three inputs. Let's add them.&#x20;

Open the Select component menu and choose the _Scheduler_ component:

![](https://3844357853-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LATDgYqVMe0hChW7efU%2F-MZqfAIKcHOH_LVJchrs%2F-MZr1j60LcUGXtoHDSyn%2FAppmixer_SDK.png?alt=media\&token=f92773c5-c866-448f-a286-4bc249e0c168)

A new field has been added to the Wizard:

![](https://3844357853-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LATDgYqVMe0hChW7efU%2F-MZqfAIKcHOH_LVJchrs%2F-MZr22tnD34ZT1gBbZeP%2FAppmixer_SDK.png?alt=media\&token=859b5dcd-2f33-4a30-bd17-a826fe72bbe3)

The _Scheduler_ component has five inputs, we want the end-user to set two of them. The _minute_ and the _hour_. And the Slack component requires the Slack channel where we want to send the message.

![](https://3844357853-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LATDgYqVMe0hChW7efU%2F-MZqfAIKcHOH_LVJchrs%2F-MZr3Fq_u7O0arNRBKjO%2FAppmixer_SDK.png?alt=media\&token=a20c821b-0df3-488b-8a76-e9444e1c4b62)

![](https://3844357853-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LATDgYqVMe0hChW7efU%2F-MZqfAIKcHOH_LVJchrs%2F-MZr3ogZcWaJ3t5G3a_V%2FAppmixer_SDK.png?alt=media\&token=b68ced74-23e2-4838-b830-0dab62d46637)

And the _hour,_ the Slack channel and the Slack message.&#x20;

![Input field for the Slack channel.](https://3844357853-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LATDgYqVMe0hChW7efU%2F-MZqfAIKcHOH_LVJchrs%2F-MZsBMTDbPc_GfQMp2an%2FAppmixer_SDK.png?alt=media\&token=f0166501-e72b-4ce0-89fc-20dc20fd4b9f)

![Input field for the Slack channel message with custom label.](https://3844357853-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LATDgYqVMe0hChW7efU%2F-MZqfAIKcHOH_LVJchrs%2F-MZsByshoK0bl-ZLV4Bk%2FAppmixer_SDK.png?alt=media\&token=62a2e5d1-2b48-464e-82c0-c2f2bc9218d3)

At this point, this is still just an ordinary flow. The user who created this flow can run it, test it ... The only difference is that this flow has a `wizard` property that describes the _Wizard_ created by this _Wizard Builder_. We call such flow an _Integration Template._ At this point, you can _publish_ the Integration Template. If you publish the template it will be visible to all the users in Appmixer (in other words it will be shared in read-only mode with all the users).&#x20;

Publishing the Integration Template:

![Publishing the Integration Template.](https://3844357853-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LATDgYqVMe0hChW7efU%2F-MZqfAIKcHOH_LVJchrs%2F-MZsC8x9o39G6oWR-yak%2FAppmixer_SDK.png?alt=media\&token=a9a44448-4e7e-4feb-9b78-1d100ed883ff)

Now, the Integration Template is shared with the end-users - it is visible to all users in the system.&#x20;

{% hint style="info" %}
Appmixer does not offer teams or other than read-only share options for the flows. It means that only the user that created the flow can change it or publish/unpublish. If you want more users to do that, you should create a dedicated Appmixer account that will be shared among your users.
{% endhint %}

Next, you will learn how to show the Integration Templates to the end-users.

## Testing the Integration Template

If you use our Appmixer FE application that comes with Appmixer, you can open the&#x20;

`https://[your-appmixer-fe-url/integrations`

{% hint style="info" %}
`your-appmixer-fe-url` - The URL of the Appmixer application. If you're running Appmixer on localhost, it will be http://localhost:8080. If you're using hosted Appmixer it will be https://\[acme].appmixer.cloud. If you're running Appmixer on your server then you know the URL.
{% endhint %}

URL and see the Integration Templates and your Integrations. This page implements our _appmixer.ui.Integrations_ UI widget, more about this Appmixer SDK widget in the next chapter.

## How to show Integrations to end-users

We have an Integration Template that we created in the previous step. Now, how to show it to the end-users so they can start using it.

You can open the `demo.html` file from the Appmixer package and choose _Integrations_ from the main menu:

![appmixer.ui.Integrations widget](https://3844357853-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LATDgYqVMe0hChW7efU%2F-MZqfAIKcHOH_LVJchrs%2F-MZs9FNLG3tSI4qpjEJM%2FAppmixer_SDK.png?alt=media\&token=ffb93d6e-678a-457e-a4a8-fdb9dc76fe9e)

There are two Appmixer SDK widgets you can use with Integrations. The first one is the [_appmixer.ui.Integrations_](broken-reference) _which you_ can use to show the Integrations to the end-user. In the upper part, you can see all the available Integrations (Integration Templates) that are published. At the bottom, you can see your own Integrations. An Integration Template becomes an Integration when the user clicks the _Configure_ button.

![Creating an Integration.](https://3844357853-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LATDgYqVMe0hChW7efU%2F-MZqfAIKcHOH_LVJchrs%2F-MZs9_Ly1meuLoAfQRfq%2FAppmixer_SDK.png?alt=media\&token=2b9b1e6f-37bc-4135-ba2d-10350910404f)

What happens when the user clicks the _Configure_ button can be seen in the `demo.html` file.&#x20;

```javascript
integrations.on('integration:create', async (templateId) => {
    hideWizardPopUp();
    wizard.close();
    // Create integration flow as a clone of the template. Disconnect
    // accounts because they might not be shared with the end user.
    const integrationId = await appmixer.api.cloneFlow(templateId, { connectAccounts: false });
    // Identify the clone as an integration.
    await appmixer.api.updateFlow(integrationId, { templateId });
    wizard.set('flowId', integrationId);
    showWizardPopUp();
    wizard.open();
});

```

We create a clone of the Integration Template and open the second Integrations UI widget [_appmixer.ui.Wizard._](broken-reference) This is also a place where you can for example add [custom fields](../flows-metadata-and-filtering#setting-custom-metadata) for the Integration.

![The Wizard.](https://3844357853-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LATDgYqVMe0hChW7efU%2F-MZqfAIKcHOH_LVJchrs%2F-MZsCPE6NWZKuxGaTI3y%2FAppmixer_SDK.png?alt=media\&token=c3248032-145f-4bfd-b3ef-c7b9fe66ae34)

The first input in the Wizard is the account selector for the Slack component. This the same account selector as you can see in the Appmixer Designer. Then there the four inputs we defined in the Wizard Builder: _Hour, Minute, Slack Channel_, and _the Alarm text._ As you can see, the _Alarm text_ message has been predefined in the Integration Template. It uses a _Variable_ from the Scheduler component (Now). The end-user can change the text to anything they want.

![Integration is ready to be started.](https://3844357853-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LATDgYqVMe0hChW7efU%2F-MZqfAIKcHOH_LVJchrs%2F-MZsDKW79Kkbue8y7-_F%2FAppmixer_SDK.png?alt=media\&token=79a497e2-4238-4f9d-b9c0-5946e43639d3)

After filling in all the details, the Integration is ready to be started.

![Running Integration.](https://3844357853-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LATDgYqVMe0hChW7efU%2F-MZsDbm7prnOz3FTEsl9%2F-MZsEfZkYsjVqJJMXXxE%2FAppmixer_SDK.png?alt=media\&token=eeaa986d-d2d3-42c6-980e-e8de9b219431)

## Custom Integrations Page

You don't have to use the built-in _appmixer.ui.Integrations_ widget to display the Integrations.

You can use the Appmixer [flows](../../api/flows#get-flows) API with a _filter_ param to get only the Integration Templates and display them the way you want. Integration Template is a flow that has a non-empty `wizard` property and does not have a `templateId` propert&#x79;_._

```javascript
GET /flows?filter=templateId:!&filter=wizard.fields
```

This way you can get all the _Available Integrations_ for the signed-in user. The API request should also include the _offset_ and _limit_ parameters for paging and you can use _projection_ to exclude the flow thumbnail.

To get the end-users Integrations use the following query:

```javascript
GET /flows?filter=templateId
```

Users Integrations contain the `templateId` property and its value is the Integration Template ID they were created from. What has to happen when the user wants to create their Integration from the Integration Template can be seen in the _demo.html_ and is described in the previous section. Basically, you have to create a clone of the Integration Template, set the `templateId` property for the newly created flow and open the _appmixer.ui.Wizard_ widget with the new flow.

The only other feature the _appmixer.ui.Integrations_ widget does is getting the icons of the components that are used in the Integration Template wizard.

## Injecting User Accounts

As shown in the first section where we used a Slack component in an Integration, the Integrations may contain components that require end-user authentication. If such a component is used in the Integration, the Wizard will contain an account selector and the end-user will be allowed to authenticate the component(s). If there are more components in the Integration with the same authentication service (like _appmixer:slack_) the account will be used for all of them.&#x20;

Now, let's assume you write your own module with custom components - _acme.application.notifications_ for example. And that module will contain components to send notifications in your application. Each component requires an Oauth2 access token in order to work properly. Then you create an Integration Template that contains an _acme.application.notifications.send_ component. When such Wizard is opened by the end-user they will see the account selector and would have to authenticate that component. That's not a problem, but at that moment, the end-user is already signed into your application, there's no need to do it again. You can inject the _acme.application_ account for the user and then the account will be pre-selected in the Wizard.

```javascript
// you can do the account injection after the end-user click the Configure
// button (want to create an Integration from the Integration Template), but
// it can be anywhere in your application.
integrations.on('integration:create', async (templateId) => {

    // as the name of the account you can use whatever you want - user's
    // name, email address ... The name will then be visible in the Wizard
    const name = 'martin@client.io';
    // service ID, there has to be an auth.js module for this service
    // installed in the Appmixer
    const service = 'acme:application';
    // and the access token, this can also be an API KEY or any other secret
    // that your auth.js module requires
    const accessToken = 'and-the-actual-access-token';

    // you can check if the signed in user already has an account for your
    // service acme:application
    let accounts = await appmixer.api.getAccounts({ filter: 'service:acme:application' });
    if (accounts.length) {
        // at this point you know that the user already has your account,
        // but this API does not return information about the tokens/api keys,
        // that may be enough for you, if not the next API validates the
        // tokens in Appmixer and return more information
    }

    const response = await appmixer.api.getAuth('acme.application');
    // the response object contains all the accounts for acme.application
    const validAccessToken = response.accounts
        && response.accounts[Object.keys(response.accounts)[0]].accessTokenValid === true;

    if (!validAccessToken) {
        // there is no valid access token, inject one
        // the next API call creates an account (if it already exists in Appmixer
        // then it will just add new token).
        await appmixer.api.createAccount(
            // in the case, Appmixer won't use the access token to get user's
            // profile infor from your API, instead we will provide the
            // user's profile info directly in the request
            { requestProfileInfo: false },
            {
                name,
                service,
                token: {
                    accessToken,
                    scope: [
                        'channels:write',
                        'groups:write',
                        'channels:read',
                        'groups:read',
                        'channels:history',
                        'users:read',
                        'chat:write'
                    ]
                },
                profileInfo: {
                    id: 'U0DDZESMC - client IO'
                }
            }
        );
    }

    // and now cloning the Integration Template, opening the Wizard ...
});
```

If we use this code to inject a _Slack_ access token into the Appmixer and then open the Wizard, the _Slack_ account will be automatically pre-selected.

![](https://3844357853-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LATDgYqVMe0hChW7efU%2F-MZwf9HNR61fPxUjAU-0%2F-M_13HuaivfOw2e1y50l%2FAppmixer_SDK.png?alt=media\&token=d70d2634-0f8c-4c87-8d57-34b2f9cd32a4)
