Before we dive into how to edit a scenario, let us give an overview of what a scenario is made of, and how it is executed.

The scenario object

A scenario is used to detect a certain type of risk, following specific business rules, for a specific triggering event. The "event" can be a transaction waiting to happen (in a transaction authorization usecase), or an existing business entity to review (for instance in an a posteriori review of a transaction or an account review).

To achieve this, a scenario is defined by

• its Triggering entity: the primary source of data, on which the decision is taken and from which we can access data from ingested entities
• its trigger condition: a rule, computed on the trigger object, that determines whether the scenario is "relevant" for this trigger payload
• a set of Rules: an ensemble of rules, computed on the trigger object. Every rule that evaluates to "true" increments the decision score by the modifier of this rule (positive or negative)
• a set of score thresholds: they help to determine a coarse grained Outcome from the score

Executing a scenario

What happens when a scenario is executed

There are two ways to execute a scenario:

1. API Execution: The scenario is triggered by an API call, with the input data provided in the POST request body.
2. Batch Execution: The scenario is run on ingested data, where each input is an ingested entity. Batches can be scheduled to run automatically or started manually.

Both methods follow the same four steps during scenario execution:

1. [API Only] Input Validation: Verify that the received data conforms to the expected data model for the trigger entity and that the scenario has a live version
2. Trigger Condition Execution: Evaluate the rule corresponding to the trigger input to check if the scenario is relevant. If true, proceed with executing the other rules and computing a score. If false, return a 400 status code for API calls, or ignore the entry for scheduled executions.
3. Rules Execution: Execute the scenario's rules one by one using the trigger input. Each rule that evaluates to true increments the decision score by its Score modifier.
4. Decision Creation: After all rules are executed, compare the total score to the scenario thresholds to determine the Outcome. Store the decision along with the input data and the results of each rule.
   1. Optionally, if a workflow is defined, this is where the decision may be automatically added to a case.

🚧

Error handling during scenario execution

Some errors can occur during rule execution due to the data used in the rule. Common unavoidable errors include division by zero and comparisons involving null fields (which can originate from the payload or ingested data).

If an expected error occurs during the trigger condition rule execution, the API returns a status code 400, similar to when the rule evaluates to false.

If an error occurs during the execution of a scenario rule, an error code is stored as the result of that rule's execution. The decision score is not incremented, and scenario execution continues. You can review the detailed rule execution results in the app's decisions detail panel to identify the error source.

How to request a scenario execution by API

There are two available ways to execute a scenario on a payload by API.

• The first is to request a decision for a specific scenario id on the payload, which returns exactly one decision
• The second is to request every possible decision for a specific payload and entity type, which iterates through all the active scenarios with a trigger entity matching this entity type, and creating a decision every time the trigger condition evaluates to true. Returns an array of 0-N decisions.

Creating a decision and ingesting data

For a given entity in the data model, the same format is expected if you want to ingest an object or create a decision.

However, the two actions are distinct: requesting a decision on an entity does not ingest a copy of it at the same time (though a copy of the payload is stored with the decision for the audit trail).

The motivation for this is that there are cases where you would want to take a decision to accept or reject (for example) a transaction, before it has been executed (and as such should join the set of ingested transactions, which will be used for future decisions).

Editing a scenario

In the following pages, we get into the details of how a scenario is built (and how to iterate on it).