Skip to main content

Run a workflow as a service user

Choose a permission group as a workflow's run identity so scheduled, webhook-triggered, and query-triggered runs use that group's access in Retool Workflows.

Assign a run identity to a workflow so triggered workflow runs use the access of a permission group you choose, instead of an admin's access. Retool creates a service user for the group and runs the workflow as that service user.

This guide is for workflow editors. To understand how run identities work, refer to Service users for workflows.

Requirements​

To assign a run identity, you need:

  • Edit access to the workflow.
  • Membership in the permission group you want the workflow to run as.

The group also needs:

  • At least Use access to the workflow.
  • At least Use access to every resource the workflow queries.

Ask an admin to update the group's permissions if it doesn't have this access. Refer to Configure permission groups.

Assign a run identity​

To assign a run identity to a workflow:

  1. Open the workflow in the workflow IDE.
  2. Open the Triggers panel.
  3. In the Run Identity section, click the Service user dropdown and select a group. The list contains the groups you belong to.
  4. Review the resources listed for the group. A service user run fails on queries against a resource the group can't access.
  5. Publish the workflow. The run identity applies to runs of the published version.

If you enable a trigger and don't select a group, the Triggers panel shows a warning that the workflow runs as an admin until you set up a service user.

Check what the group can access​

After you select a group, Retool lists the resources and workflows that the group can and can't reach. A service user run fails on queries against a resource the group can't access, so resolve gaps in permissions before you publish.

A warning is also displayed when you add a block that uses a resource the group can't access. To fix this, either choose a different group or ask an admin to grant the group access to the resource.

Remove a run identity​

To go back to running as an admin, select None in the Service user dropdown and publish the workflow.

Caution

If your organization turned on data access enforcement, workflows without a run identity are blocked from querying enforced resources on workflows triggered via schedule or webhook. Refer to Run workflows against enforced resources.

Edit a workflow that has a run identity​

Only admins and members of the group selected in the Service user dropdown can edit a workflow that has a run identity. Other people with edit access get a read-only workflow, and a banner names the group with a run identity. Ask a member of the group to make changes, or ask an admin to add you to the group.

Run failures​

Deleting a group permanently retires its service user. Workflows set to run as the service user of a deleted or archived group don't fall back to another user or an admin. Each new run stops before it does any work and appears in run history as failed with the message: "Run failed: this workflow is set to run as a group that's no longer available."

When the group selected in the Service user dropdown is deleted or archived, the failure depends on the type of trigger:

  • Webhooks and publicly shared apps: The request returns HTTP 409.
  • Schedules: The schedule keeps firing, and each run records a failure.
  • Query triggers: The trigger stops polling.
  • Retool Event triggers: The triggering action, such as a login, still completes. Admins get the failed-run email.

To fix this, select a new group in the Service user dropdown, save, and release the workflow if it uses releases. Runs fail the same way if the group loses Use access to the workflow.

Archiving a group has the same effect. Retool treats the group's service user as though it doesn't exist, and runs of workflows that use it fail.

Run history​

Click Run history in the status bar of the workflow IDE to see the runs of a workflow. For service user runs, Retool limits run logs and block results to people who can access the workflow and share a group with the service user. If you can't view the logs of a run, you might not belong to the group selected in the Service user dropdown.

Troubleshooting​

The following are common problems when you run a workflow as a service user.

Why can't I choose a group?​

You can only choose a group you belong to. Ask an admin to add you to the group, or choose one of your groups.

Why can't I edit the workflow?​

The workflow has a run identity, and you aren't in its group. Refer to Edit a workflow that has a run identity.

Why did a query fail in a scheduled run?​

The group selected in the Service user dropdown might not have access to the resource. Check the group's resource access, and review any data access policies that apply to the group.

Why do runs fail with "this workflow is set to run as a group that's no longer available"?​

An admin deleted or archived the group, or the group lost Use access to the workflow. Refer to Run failures.

Why does a resource that uses my OAuth credentials fail?​

Service users can't use personal OAuth credentials. Use a resource that authenticates with a shared credential for workflows that run as a service user.

Why do some blocks fail only in service user runs?​

Service user runs can't do the following:

  • Run agent queries, such as queries with the RetoolAIQuery resource.
  • Query Retool Vectors.
  • Query resources that use %USER_*% placeholders in their configuration.
  • Dispatch a Retool Agent run.

Move these blocks to a workflow that doesn't run as a service user.