Skip to main content

Adding and editing Scenarios

Updated over 2 months ago

Scenarios page overview

To view the Monitoring Scenarios page, click on Analyst Toolbox in the left menu bar and then select Monitoring scenarios. The page will appear, displaying scenarios if any have been set up, or blank if none are present.

On the Monitoring page, you can filter your alerts by various conditions, such as Type and Status. You can also enter Scenario pages by clicking on a selected scenario or add new scenarios.

📚 Explore the Scenario Library
You don’t have to start from scratch and write your own scenarios. Our library is packed with ready-made scenarios that you can pick and adjust to fit your needs.

Adding new scenarios

Step 1: Creating Scenario

To add a new scenario, click +New Scenario at the top right.

Next, fill out the following information and click Create Scenario.

Internal ID

  • Description: Assign an ID to your scenario. This ID acts as a unique code for better scenario management. For instance, if you're creating a real-time monitoring scenario to track transactions resembling layering activities, you might use a code like RT-TR-LAYER-1.

  • Requirements:

    • This field is mandatory.

    • If you don’t have internal codes, you can use simple numbers or any other preferred method.

    • There are no restrictions on the symbols you can use, but the ID must be 30 characters or fewer.

Scenario Name

  • Description: Enter a clear and descriptive name for your scenario. This name will appear in alerts and will be used for alert filtering, dashboards, exports, and more.

  • Tips: Make the name human-readable for easy identification.

Category and Typology

  • Description: Select a category and typology for your scenario to enhance its organisation and management.

  • More Information: You can find detailed information about categories and typologies here.

Scenario Type

  • Description: Choose the type of scenario you are creating. The options are:

    • Real-time: Monitors events as they happen.

    • Post-event: Analyses events after they occur.

    • Periodic: Regularly checks for specific conditions at set intervals.

  • Important Note: Once the scenario type is selected, it cannot be changed.

  • More Information: Learn more about scenario types here.

Alerted Entity

  • Description: Specify the entity that will trigger an alert in this scenario. The options include:

    • Person: Alerts are triggered based on individual persons.

    • Transaction: Alerts are triggered based on transactions.

    • Counterparty: Available if a Periodic scenario is selected and the counterparty feature is set up.

  • Important Note: Once the scenario type is selected, it cannot be changed.

Step 2: Creating Scenario version and adding content

Once you have clicked Create Scenario, you can then add the scenario version by clicking on +New version.

❗️ Current and Historic versions of a Scenario cannot be edited, their statuses cannot be changed. Only Draft versions can be made Current after the query and parameters have been validated and no errors were found.

Fill in the following information:

  • Scenario logic - describe how your scenario works, what’s its purpose, what thresholds it uses, etc. Use parameters, if needed. For example: "Scenario checks all transactions and generates an alert when amount is higher than 10,000 Eur".

  • Details - add information you want to be showed with each alert the scenario generated. You can use:

    • $param placeholder to use values related to the subject of the alert, e.g. amount of the current transaction. Read more on how to use the $param placeholder below.

    • You can use parameters, if needed, for example: “Amount threshold: $amount; current transaction amount: $param”.

    • Note: The maximum length for alert details is 1000 characters. Any characters beyond this limit will be discarded and will not appear in the alert.

  • Query - Enter the actual query in the language specified above. You can read more about syntax requirements at the bottom of this article.

    • Language - Select which language the scenario will be written in. You can use SQL or JMESpath for Real-time and Post-event type, but only SQL for Periodic type.

  • Parameters - define parameters and their values to be used in the scenario. Read more here.

  • Trigger for - select Person and Transaction Segments the Scenario should be triggered for. Read more here.

  • If Periodic scenario is selected, define Periodic scenario interval and Periodic scenario start time:

    • For example, if you select a start time of 2024-03-25 at 8:00 AM, which falls on a Monday morning, and set an interval of 1 week, this means the scenario will run every Monday morning.

  • Alert suppression interval - set an alert suppression interval for your scenario.

  • Note - For example, if you change something in the query, then you need to add a notes, so it would be easy to understand what was changed.

  • Validate query and parameters - After content has been added, query (and parameters, if defined) needs to be validated. If no errors are found, you can save the version as draft or make it current.

  • Validate the scenario against a Transaction or Person - by entering the ID of the relevant entity (depending on the scenario's alerted entity) you can check whether the entity matches the scenario. The validation process checks against the scenario query, parameters and applied segments.

❗️ Making a version current has different implications depending on scenario’s status:

  • If the scenario is ACTIVE, the new current version is then used by the scenario to run checks.

  • If the scenario is INACTIVE, the scenario is not activated automatically, no checks are run - in order for the scenario to start working, you need to activate the scenario separately.

Activating new scenarios

Step 1: Turning Scenario version to current

When you have a scenario that you wish to activate, you must first set a relevant version of the scenario to Current. To do this, select a version and perform a validation check. If no errors are found, you can then make it current.

Step 2: Activating Scenario

Once you have identified a version of a Scenario you wish to start monitoring with and have set its status to Current, proceed by clicking Activate button by scenario's status at the top of the page. Once activated, scenario's status will change to Active and it will start generating alerts.

❗️Post-event and Periodic Scenarios start working right after you activate them. However, Real-time Scenarios require a separate monitoring check API call. If you define a scenario as Real-time but the API call is not made, then those scenarios will not run. See the API documentation for more details.

Editing existing scenarios

To edit an existing scenario, click on the scenario.

If you want to change the scenario's Internal ID, name, category, or typology, click the edit icons next to these parameters.

Please note that scenario type and alerted entity cannot be edited once the scenario has been created.

If you want to change the query itself, then click +New version and add the new version OR duplicate an existing version and edit it by clicking Actions → Duplicate as a draft.

Editable version will be in 'Draft' status. In that status you can change the scenario how many times you like.

💡 Editing a Scenario that is already active:

  • Creating drafts of the Scenario does not affect the Current version; it continues to function as before.

  • After changing the Draft version to Current, you don't need to reactivate the Scenario. It automatically starts using the new version and continues monitoring.

Deactivating and archiving scenarios

Deactivating Scenarios

You can deactivate the Scenario by clicking on the Deactivate button next to the scenario's status. A deactivated scenario will stop generating alerts.

Archiving Scenarios

You can archive the Scenario by clicking on the three dots next at the top right of the scenario page and clicking Archive.

If you want to restore archived scenario, click on Restore next to the scenario's status.

❗️Archiving a Scenario does not affect alerts generated by the Scenario. If needed, you will use the archived Scenario in Alert filters.

Scenario history

The Scenario History feature logs key events for each scenario: when and by which user a scenario is added, its status changes, a version is made current, or when its name or ID is changed.

Accessing Scenario History

To view a scenario's history, go to the Scenario Page, click the three dots in the top right corner, and select View History. This will display a log of changes, including who made each change and when.

Scenario syntax requirements

Scenario syntax requirements

Real-time and Post-event scenario syntax requirements

For SQL queries for real-time and post-event, pay attention to the following:

SQL query example for real-time or post-event:

select sum(past.amount) >= 10000 and count(distinct past.receiver_account) >= 20 
   , sum(past.amount) 
   , count(distinct past.receiver_account) 
from transaction new 
join transaction past on past.person_id = $personId and past.customer_id = $organisationId 
join person p on p.id = $personId and p.customer_id = $organisationId 
where new.id = $transactionId 
   and past.timestamp <= $transactionTimestamp 
   and past.timestamp >= $transactionTimestamp - '30 days'::interval 
   and past.direction = 'OUTGOING' 
   and p.type = 'INDIVIDUAL'

  • The first field in the SELECT clause needs to return TRUE or FALSE for the conditions relevant to the scenario. In the above example, the total amount in the past 30 days is at least 10000 and the number of distinct receiver accounts is 20.

  • Other fields in the SELECT clause are needed if they are used as dynamic parameters in the details field. This information will appear along with the alert.

    In order to use parameters, add them to the SELECT clause and use the “$param” placeholder on the details field.

    See the SQL scenario example above.

  • When joining tables on person ID: Ensure you add “person.id = $personId” and person.customer_id = $organisationId. When person data gets added, “$personId” will be replaced by the relevant person_id, and "$organisationID" will be replaced by your organisation ID.

  • Ensure you add “transaction.id = $transactionId” to the WHERE clause. When a transaction comes in, “$transactionId” will be replaced by the relevant transaction_id.

  • When using the timestamp of the current transaction, please use $transactionTimestamp. "$transactionTimestamp" will be replaced by the current transaction timestamp.

For JMESPATH queries, keep the following in mind:

JMESPATH query example for real-time or post-event:

currentTransaction[?direction == 'O'].amount.to_number(@)>`10000`

  • For JMESpath you can use variable currentTransaction to monitor one transaction, you can specify the needed parameters and query must return True-False.

  • For more on writing JMESpath, you can check out public documentation here.

PERIODIC scenario syntax requirements

For SQL queries for periodic scenarios, pay attention to the following:

SQL query example for a periodic scenario:

select person_id 
   , last_month_sum >= 1.5 * prev_month_sum and last_month_sum >= 10000 
   , last_month_sum 
   , prev_month_sum 
from 
   ( 
   select past.person_id as person_id 
      , sum(case when past.timestamp >= date_trunc('month', current_date-'1 month'::interval) then past.amount else 0 end) as last_month_sum 
      , sum(case when past.timestamp < date_trunc('month', current_date-'1 month'::interval) then past.amount else 0 end) as prev_month_sum 
   from transaction past 
   where past.customer_id = $organisationId 
      and past.timestamp < date_trunc('month', current_date) 
      and past.timestamp >= date_trunc('month', current_date-'2 months'::interval) 
   group by 1 
   ) sub

  • Periodic scenarios do not use $transactionId, $personId, or $transactionTimestamp placeholders.

  • Instead, put person.id (or transaction.person_id) as the first field in the SELECT clause and group by that field.

  • The second field in the SELECT clause should still return TRUE or FALSE.

  • No other fields are mandatory, but you can still use dynamic query parameters.

Available computed parameters

  • $organisation.id — number

  • $person.id — number (Salv's internal numeric ID for persons, separate from the IDs you send)

  • $transaction.id — number (Salv's internal numeric ID for transactions, separate from the IDs you send)

  • $transaction.timestamp — timestamp

  • $person.risk — person final risk as string. Possible values: LOW, LOW_TO_MEDIUM, MEDIUM, MEDIUM_TO_HIGH, HIGH, UNACCEPTABLE

  • $person.tags — array of person screening tags. Possible values: PEP, SANCTION, ADVERSE_MEDIA, CUSTOM_SCREENING_LIST, ADVERSE_MEDIA_ENTITY

  • $scenario.handle — string

  • $person.attributes.* — person attributes as strings, cast into other types explicitly if necessary.

  • $transaction.attributes.* — transaction attributes as strings, cast into other types explicitly if necessary.

  • $transaction.type

  • $person.type - string, possible values: INDIVIDUAL, LEGAL or UNDEFINED (legacy PRIVATE or BUSINESS)

  • $transaction.external_id , $person.external_id - your internal IDs for transaction/person

Related Articles
Breakdown of a TM scenario: ‘INDIVIDUAL: Large Movement of Funds Coming into and out of an Account on a Single Day’
Breakdown of a TM scenario: jsonb and hstore attributes in queries
Scenarios with accessing previous alerts
Best practices for writing and optimising Monitoring scenarios
Parameters in Scenarios
Did this answer your question?