Custom integrations and custom actions

If a tool has an HTTPS API but no ready-made Siit integration, you can connect it yourself. A custom integration holds the connection to the tool, and custom actions define what Siit can ask it to do, such as "Create a VPN account".

Where you can use custom actions

• From the side panel of a request, or a person's About menu
• In workflows, where outputs become variables for later steps and branch conditions
• In the provisioning and deprovisioning steps of an app access role
• With Assist, when integration actions are enabled for it in your workspace

Before you start

• Custom integrations depend on your plan. If you don't see the Custom category in the Integration library, contact us through in-app chat.
• You need the Can configure integrations permission.
• Have the API credentials, the base URL and the endpoints you want to call at hand. All URLs must use https:// and point to a public address.

Create the connection

Go to Settings → Workspace → Integration library, open the Custom category and create your integration. The page has two tabs, Connection and Actions.

1. Add the integration's name and, if you like, a link to its API documentation.
2. Enter the Base URL of the API.
3. Pick an authentication method. Each method is a card, and Siit only asks for the fields that method needs.
4. Enter your credentials. They are masked once saved. Use Replace to change them. Saving other changes never clears them.

When the method adds a header, Siit shows you the authentication header it will send. Default custom headers are under Advanced.

Create an action

In the Actions tab, click New action. The list shows each action's name and description, where it runs, where it is available, when it last ran, and whether it is a Draft or Active. The editor has five sections:

1. What it does: a name, a description, and where it runs: Request, People, Apps or All.
2. What it needs: the inputs. For each one, set a label, a type, what fills it, and whether it is required. Workflow-specific inputs are under Advanced.
3. The call: the HTTP method, the path (shown after your Base URL) and the JSON body, where you can insert variables. Query parameters and action headers are under Advanced.
4. Outputs: for each value you want back, a name, the path to it in the JSON response, and a type. For a response like {"data": {"userId": 42}}, the path is data.userId.
5. Where it is available: tick the places where admins can use it. Options that don't fit the action's context are greyed out.

Click Save draft to keep working, or Activate to make it available.

Use the outputs

Outputs appear in the workflow variable picker. You can insert them in later steps, and use them as conditions in a branch. See Branch a workflow on what a previous action returned.

Frequently asked questions

What is the difference between Draft and Active?

A Draft is saved but can't be run anywhere. An Active action is offered in the places you ticked.

Who can run my custom actions?

Each custom integration counts as its own integration in Roles & permissions. A new one is only granted to Super admin roles at first. Grant it to other roles as needed. A role without access doesn't see its actions anywhere. See Roles and Permissions.

Can I see my credentials again after saving?

No. Credentials are write-only, admins included. Use Replace to enter new ones.

What if the API is slow or fails?

Each run must finish within about 20 seconds, and Siit sends each call once with no retries, so the third party never receives the same request twice. Every run is recorded with its inputs, the response and its status.

What happens if I edit or delete an action that a workflow uses?

Workflows always use the action's current definition. If you rename or remove an input a workflow fills in, that workflow's runs fail until you update the step. Deleting an action makes the steps that use it stop working.

Need help?

Contact support@siit.io.