The Adaptavist Group LogoDocumentation

Visual Flow

The visual flow is a chart of what a workspace's scripts do.

It follows each script from what triggers it, through its decisions, loops and function calls, to every external API endpoint, connector and record storage call it makes.

Use it to understand a workspace at a glance, to check what you or an AI agent built before you deploy a release, and to spot problems in an environment's setup, such as a parameter the environment doesn't define, a connector that isn't authorized, or a host the egress firewall blocks.

The chart is generated from the saved code. Your scripts are never triggered to draw it, and it isn't generated by AI.

Key terms

Chart
The drawing of a workspace's scripts. Each box is a step, such as a decision, a loop, or a call to an external API endpoint.
Entry point
A script function that something triggers: a manual trigger, a scheduled trigger, an event listener or another script.
HEAD
The latest saved version of the workspace. An environment with no release deployed runs HEAD. A release has its own chart.
Outdated
A chart drawn before the workspace last changed. It stays as it was until you generate it again.
Calls resolved
How many of the outbound calls in the code the chart could follow to their destination.
Code warning
Something in a script that the chart found wrong or couldn't follow, with the script and line.
Environment warning
Something in the environment setup that the code encounters, such as a missing parameter.

Find Visual flows

Open a workspace and in the left sidebar, click Get started → Visual flow

Note: Visual flow is being rolled out together with the embedded agent. If the side navigation shows AI assistant instead of AI agent, Visual flow isn't in the workspace's list yet. It isn't available in private cloud hosting.

Generate a chart

  1. Open Visual flow in the workspace.
  2. Click Generate visual flow.
  3. Wait for the chart, or carry on elsewhere. A message tells you when The visual flow is ready.

To be told while you're in another browser tab or window, turn on notifications using the Bell icon in the embedded agent panel's header. The same setting covers the agent's questions and access requests.

When the chart is out of date, or you want to draw it again anyway, click Regenerate. While a new chart is generated, the old one stays on screen.

Agents you run yourself and the CLI can generate a chart and read its warnings too.

Charts and environments

  • HEAD environments share one chart. The steps are the same across all environments running HEAD. The environment warnings, parameter values, and egress firewall colors apply to the environment you're viewing.
  • A release has its own chart. It's generated automatically when you create the release. An environment running a release displays that release's chart, with a note that environment-specific configuration stays with the environment, not the release.

Chart status

The status is displayed next to the title.

StatusWhat it means
Not generatedThe workspace has no chart yet. Click Generate visual flow.
Generating…A chart is being generated. You can leave the page.
Up to dateThe chart matches the saved workspace.
OutdatedSomething the chart was drawn from has changed since. Click Regenerate.
FailedThe chart could not be generated, and there is no earlier chart to display. The reason is displayed above the chart.
Release (followed by its version)The chart of the release the environment runs.

A HEAD chart becomes outdated when someone changes a script, an API connection, an event listener or a scheduled trigger, or adds or removes a parameter in any of the workspace's environments.

Any chart, including for a release, also becomes outdated when ScriptRunner Connect changes how charts are drawn. A release's status still displays Release and its version, and a note above the chart says it's outdated. Regenerate it to see it in the new way.

If generating a new chart fails, the existing chart remains unchanged.

Read the chart

The chart has several tabs:

  • Overview: every trigger, the scripts they trigger, and what those scripts talk to: API connections, hosts called with the Fetch API, and record storage.
  • Warnings: every code and environment warning, displayed only when there are some. The tab's name includes how many.
  • One tab for each entry point, named after its script, with every step it takes.

Above the tabs, the chart says when it was generated and what percentage of calls it resolved. A figure under 100% means some calls go to a destination that is worked out only while the script runs (see Limitations below).

Shapes

Click Legend in the chart to see every shape and line. The main ones are:

ShapeWhat it stands for
TriggerA manual trigger, a scheduled trigger or an event listener. A disabled trigger is faded.
Entry pointThe script function triggered.
Decision or switchA point where the code takes one path or another.
Try and catchSteps whose errors are caught and handled.
Loop, Loop in parallelSteps are repeated for each item, one after another or several at the same time.
Calls started togetherCalls that run at the same time, such as with Promise.all.
Function callA call to another function in the workspace. A stacked box can be opened to display its steps.
Chained triggerA script triggering another script with triggerScript.
API connection, Fetch API callA call to an external API endpoint, through a connector or with the Fetch API.
Record storageReading or writing records.
ThrowAn error the code raises.
UnresolvedA step the analyzer couldn't follow.

Lines show the flow in the direction it moves, the way back to the start of a loop, calls to a function or another script, and where an error is caught.

Egress firewall colors

Every call to an external API endpoint is colored by how the egress firewall handles it.

ColorMeaning
🟢 GreenThe firewall allows the call.
🟡 AmberThe call is waiting for approval on the firewall.
🔴 RedThe firewall blocks the call.

When the firewall is off, these boxes are grey.

Parameters

A step that uses a parameter displays the parameter's value in the environment you're viewing. The values of Password parameters are never displayed.

Explore a step

Click a step, or move to it and press Enter, to display its details on the right: what it is, its warnings, and what it links to, such as the connector, the API connection, the egress firewall entry or the schedule. Drag the edge of the details pane to resize it.

A selected step also displays buttons for what you can do with it:

ActionWhat it does
Open in editorOpens the script in the editor at the step's line.
Explain by AI agentOpens the embedded agent with a request to explain the step and how it fits into the workspace. You review the request before sending it. Not displayed if the agent is disabled at the team level.
Drill downOpens the tab of the entry point that a script or chained trigger leads to.
Expand in chart, Collapse in chartDisplays or hides the steps of a function call in place.
Manage connectorOpens the connector used by the step.
Open API connectionOpens the API connection used by the step.
Open egress firewallOpens the egress firewall, when the call is blocked or waiting for approval.
Open event listener, Open event queue, Open scheduled triggerOpens what triggers the script.

Warnings

The Warnings tab lists everything the analyzer found. Click a warning to open the script at its line.

To have the embedded agent look into the warnings, click Investigate by AI agent. The agent proposes fixes before it makes any changes.

Environment warnings

WarningWhat to do
The code reads a parameter that the environment doesn't defineAdd the parameter to the environment.
The code uses an API connection that has no connector in the environmentChoose a connector for the API connection in that environment.
A connector isn't authorizedAuthorize the connector. Calls through it fail until you do.
A host or connector has no entry on the egress firewall's allowlistAdd it to the allowlist. Until then, the firewall blocks the calls.
A host or connector is waiting for approvalAsk a team admin to approve it on the egress firewall.
A host or connector is waiting for room in the connections allowanceA team admin removes an entry the team no longer needs, or the team moves to a plan with more connections. The entry then still needs approval.

Fix these in every environment you deploy to, not only the one you build in.

Code warnings

Code warnings fall into three groups:

  • Mistakes to fix
    • A chained trigger names a script the workspace doesn't have, the code imports an API connection the workspace doesn't have, a script has a syntax error, or an event listener's script has no default exported function or expects a different event.
  • Work nothing waits for
    • A call written without await, or an async callback given to forEach. The script goes on at once, can finish before the call does, and the call's errors aren't caught. Add await, or use for...of with await, unless you meant the call to run on its own.
  • Steps the chart can't follow
    • A URL, a function, a connection, or a chained trigger's target that is resolved only while the script runs. This isn't a fault. Change the code only if a fixed value or an API connection would be just as correct.

Compare versions

Once a workspace has a release, you can compare two versions of its chart: two releases, or a release and HEAD.

  1. Click Compare. In an environment running a release, the button is Compare with HEAD.
  2. Pick the versions in From and To. Swap turns them round.
  3. Read the changes: boxes are marked as added, changed or removed, and the counts are displayed above the chart. A function call with changes inside is marked so you can open it.
  4. To read the code itself, click Compare code. It displays the scripts side by side or inline and can hide lines and scripts that haven't changed.
  5. Click Exit compare when you're done.

If one of the versions has no chart yet or an outdated one, you can generate it from the comparison.

Who can see and generate charts

Anyone who can read a workspace can see its chart and generate one. Generating doesn't change anything in the workspace, so it works while someone else is editing it. Each chart someone generates is recorded in the team's audit log.

In access policies, the permissions are View visual flow and Generate visual flow. Both are included in the built-in Read-Only policy, so an AI agent with the default access can generate a chart.

Best practices

  • Check the chart before you deploy a release, especially after an AI agent changed the workspace.
  • Fix environment warnings in every environment you deploy to.
  • Write code that the chart can follow. Use API connections, or URLs built from fixed text and parameters, that await every call, and trigger scripts by name. Code the chart can follow is easier for the next person to read, too.
  • Split very large scripts. Smaller scripts produce charts that are quicker to generate and easier to read.

Limitations

The chart reads the code without running it, so it can only draw what the code declares before it runs.

  • Only saved code is in the chart.
    • Changes you haven't saved in the editor aren't included.
  • Code inside NPM packages isn't followed.
    • A package that calls an external API endpoint itself, such as a vendor's SDK, isn't drawn and yields no warning, so the calls resolved figure can read 100% without it. The workspace's API connections, record storage and chained triggers are drawn.
  • Anything decided only while the script runs is marked, not drawn.
    • A URL built at run time, a function or connection picked by a condition, or a chained trigger whose target is built at run time.
  • Code run through eval or new Function isn't drawn and yields no warning.
  • The chart displays every path the code could take.
    • It doesn't show how many times a loop runs, which path of a decision is taken, or whether a call happens at all.
  • Errors are drawn from the outer try block to its catch step, not from the step that failed.
  • Promise.race and Promise.any are drawn like Promise.all, as calls started together.
    • The chart doesn't display that only the first one to finish counts.
  • A function that calls itself stays closed in the chart.
  • A host read from a parameter can't be checked against the egress firewall, so it's drawn red even when the firewall allows it.
  • Text quoted from the code is shortened.
    • Long strings are cut in the chart, and the script has the rest.
  • A script the chart can't analyze is left out, with a warning.
  • A very large workspace may not get a chart. If generating takes too long or the chart comes out too large to display, it is stopped.
    • Split the largest scripts and try again.
  • Some function calls stay closed in a very large view.
    • Close other calls to open them.

Search documentation

Start typing to search the docs.