Simulation Actions

Once a simulation is saved, the sale usually has a next step outside the portal: a document to produce, a team to notify, a record to update on the deal. A simulation action lets the seller trigger that step from the phone, with one button, without leaving the simulation.

Behind each button is a workflow you choose in the Hub, and it always runs on the deal the simulation is linked to. The seller never types anything into it and never sees what the workflow computed. What comes back to the seller is deliberately narrow: whether the run worked, the messages the workflow chose to show, and the files it produced.

What an Action Is

An action is a published workflow that sellers can run on the deal linked to a saved simulation. You pick up to five of them in the Hub, in the order the seller will see them, each with an optional label. When an action has no label, the seller sees the workflow's name, or its alias if the workflow has no name.

The seller sends no input. AltScore takes the deal from the simulation and passes it to the workflow, so the only thing the seller decides is whether to press the button. The workflow's own output is never shown in the portal; to tell the seller something, the workflow has to say it on purpose (see Telling the Seller What Happened).

The seller finds the actions in a block with the small heading Actions, the title Simulation actions and the line Your administrator chose them in the Hub, and they run on the deal linked to this simulation. While the list loads, the block reads Looking up the available actions... The block appears in two places: on the summary at the end of the simulator, and on the simulation's detail page. It does not appear for a discarded simulation, and it does not appear at all when no action is configured or none comes back for that simulation.

An action needs a deal, and the deal comes from the simulation. The link is made through the operation number the seller enters when building the operation (see Operation Data and Payment Plan): if a deal of that customer carries the same number, the simulation is linked to it. Deals themselves are described in the Deals API.

Setting Up Actions in the Hub

Actions are configured on the seller portal settings card: Settings, then the Configuration section, then Seller portal. The card needs the configurations.write permission; the rest of it is covered in Configuring the Portal. The field is Simulation actions, inside the Build an operation capability, and it describes itself as Workflows the seller can run on a saved simulation, in this order.

Open Add an action to pick a workflow. The picker only offers workflows that qualify (next section) and that are not already on the list, so each workflow can be added once. Actions appear to the seller in the order you added them, and the list has no way to reorder them: to move an action, remove it with the X on its row and add it again. Once there are five, the picker reads There are already 5 actions, the maximum.

Each action on the list has two settings:

With Approved simulations only, the action stays disabled in the portal until the simulation is approved, in the Hub or by a workflow. Sellers cannot approve simulations themselves; approval is described in Own Financing in the Hub.

Nothing applies until you press Save. The picker and the label field already keep the list within these limits, and AltScore enforces the same limits every time the settings are saved, so you should rarely see the three messages below. Any of them blocks the save, and the message shows in red above the button:

When a Workflow Stops Qualifying

An action whose workflow is no longer published, or no longer meets the requirements, is not removed from the list. It stays there in red: an action whose workflow is no longer published shows its alias followed by (no longer available), and one that no longer qualifies shows its name followed by (no longer qualifies). The card warns: An action is no longer published or no longer qualifies, and the seller sees it disabled. Remove it or fix the workflow. Until you do one of the two, sellers see that action greyed out with its reason.

What a Workflow Needs to Qualify

Because the seller types nothing, a workflow can only be an action if the deal is the one thing it needs from outside. AltScore applies the same rule in the Hub picker, when the seller's list is loaded and again when the seller presses the button. A workflow qualifies when all of these hold:

• It is in the Action category.
• It is published and has an alias.
• It is not archived and not hidden.
• It has a required input called deal_id. The spellings dealId and deal-id are accepted too.
• Every other required input has a default value, and that default is of the type the input declares, for example text for a text input or a number for a number input. A default of the wrong type is dropped, and the input would reach the run empty, so such a workflow does not qualify.

AltScore fills the simulation's deal into every deal_id input the workflow declares. Every other input runs with its default value.

When no workflow in your organization qualifies, the picker states the rule: No workflow qualifies. To show up here it has to be in the Action category, published and not hidden, require deal_id, and every other required input has to have a default value of the type it declares.

The version that runs is always the one currently published under the workflow's alias. Publishing a new version changes what the next press runs, without touching the Hub settings; see Publishing Workflows and, for building the workflow itself, the Workflow Builder.

Telling the Seller What Happened

The seller never sees the workflow's output, so a workflow that only computes and stores something leaves the seller with a green or red line and nothing else. Two things do reach the seller: messages from Notice nodes, and files.

Notice Nodes

The Hub puts it in one line: To tell the seller why an action did not work, add a Notice node to the workflow: its message is shown next to the result.

Only messages raised by a Notice node of the workflow version that ran reach the seller. Messages generated by the engine or by data sources are dropped, and so are empty ones. The seller sees at most five, errors first, then warnings, then info, and each message is cut at 300 characters. The Notice node's Severity sets the color in the portal, and any severity other than these three is shown as Info (grey):

Notices appear on both successful and failed runs. Write them for the seller, in plain language and saying what to do next, for example "The deal has no signed contract yet. Ask the back office to upload it, then run this action again." A failed run with no notice only tells the seller that something went wrong and to let the administrator know, which usually ends in a phone call.

Files

When a run succeeds, the seller can download the files it produced: first the files attached to the run itself, then those attached to the workflows it launched directly. Only one level down is looked at, and at most 50 of those launched runs. Each file is shown with its own name; a file without one is named after the workflow that produced it plus a number, for example "Contract package 1" and "Contract package 2".

Files are shown only for successful runs. A run that fails never offers its files, even if it attached some before failing.

Running an Action

On the seller's side, each action is a button with a play icon and the action's label. Pressing it opens a confirmation, here for an action labelled "Send to signature":

• Title: Run “Send to signature”?
• Body: The action runs on the deal linked to this simulation. Once started it cannot be cancelled from here.
• Buttons: Run and Cancel.

Only one action runs at a time on the screen. While one is running, every action button is disabled.

While It Runs

The action shows Running... If three minutes pass without a result, the line changes to “Send to signature” is taking longer than usual. with a Check again button. The seller does not have to wait on the screen: leaving and reopening the simulation picks the run up again (see The Last Run).

The Result

A successful run shows a green line, “Send to signature” finished successfully., then the workflow's notices, then one row per file with its name, its extension and a Download button. Screen readers announce each button as "Download" followed by the file name.

A failed run shows a red line, “Send to signature” could not be completed. If it happens again, let your administrator know., followed by the notices. If the failure arrives without any notice, the portal reads the result once more after 1.5 seconds, in case the notices were written a moment after the failure. Failed runs never show files.

Each Download asks AltScore for a fresh link, because download links expire after an hour, and opens the file in a new tab. Only secure (https) links are opened. If the file cannot be opened, the row shows We could not open the document. Try again.

When the Run Cannot Start

Pressing Run can still be refused, because the situation may have changed since the list was loaded. AltScore checks these in order and returns the first that applies, and the portal shows the message as a red line under the action:

For the first five, the portal also reloads the list of actions, so the buttons and their reasons catch up with the change. An action counts as already running when the same seller started the same action on the same deal within the last 15 minutes and that run is still pending, running or paused.

When an Action Is Unavailable

An action that cannot run is shown disabled, with the reason underneath. AltScore decides availability each time the list is loaded; nothing is decided on the phone. When several reasons apply, the seller sees the first one in this order:

The block is hidden for discarded simulations, so the first reason only shows up when a simulation is discarded while the seller already has it open, for example from the Hub, and the list is loaded again. The fifth reason is not repeated under each action while the orange box described below is on screen, because the box already explains it. If the list itself cannot be loaded, the block shows the error with a Check again button.

The Deal Is Not Linked Yet

When the simulation has no linked deal, an orange box above the actions, titled This simulation is not linked to a deal yet, explains why. The deal is looked up by the simulation's operation number, and the box names it. With a fictitious number OP-1042, the five explanations are:

The box has a Check again button, which loads the list again. A simulation saved before its deal existed does not stay unlinked: every time the actions are listed or run, AltScore looks for the deal by operation number again and saves the link once it finds it. So when the deal is created after the sale, the seller only has to press Check again later. A discarded simulation is never linked.

The first three situations are also reported to the seller as warnings when the simulation is saved; see The Save Warnings. Saved simulations and their statuses are covered in Saved Simulations and History.

The Last Run

When the seller reopens a simulation, each action shows its latest run by that seller on the simulation's deal: Last run: followed by the date and time, the success or failure line, and a View result button. The notices and files are not loaded until the seller presses View result; while they load, the action reads Looking up the result...

A run that is still in progress shows Running..., and the most recent one is picked up and watched again automatically, so a seller who left during a long run sees the result appear when they come back.

The last run is personal. It only ever shows runs started by the same seller, and the result of a run can only be read by the seller who started it, and only from the simulation whose deal it ran on.

Things to Know

The seller sees only what the workflow says on purpose. The output, the variables and the engine's own messages stay out of the portal. If a workflow should explain a failure or confirm what it did, it needs a Notice node on that path.

Republishing a workflow changes the action immediately. The Hub stores the alias, not a version, so the next press runs whatever is published at that moment. A new version that adds a required input without a default stops qualifying, and the action turns disabled for every seller.

The duplicate guard is short and per seller. It only blocks the same seller, the same action and the same deal, for 15 minutes, while the run is unfinished. Another seller can run the same action on the same deal at the same time, and the same seller can run it again once the first run ends.

The last run looks back ten runs. To find an action's last run on this deal, AltScore looks at no more than ten of the seller's most recent runs of that action: the ones on this deal, plus failed runs whose deal it has to confirm. Runs on other deals do not count toward the ten, except failed ones. So if the seller has ten or more newer failed runs of that action on other deals, the action can show no last run here even though one exists.

Download links do not last. Each link expires after an hour. The portal asks for a new one on every press, but a link copied out of the browser and sent to someone else stops working.