Skip to main content
Version: 4.2

Install and configure

The guide details how to install and configure Evelyn.

Prerequisites​

Before installing the Name Sanctions Screening and PEP Screening Alert Review (NSS) AI Agent, make sure your environment meets the following requirements.

Hardware​

The server requirements for the AI Agent are the same as for the Work.AI Platform. To run screening, you don't need the RPA server.

ServerRecommended OSCPU (cores)RAM (GB)HDD (GB)
MasterRHEL/Rocky Linux 8.x848750
AgentRHEL/Rocky Linux 8.x832150
Superset AnalyticsRHEL/Rocky Linux 8.x41650
MS SQLMicrosoft Windows Server 2022, 2019416500

For the architecture deployment diagram, refer to Install AI Agents | View architecture deployment.

Software​

  • You have installed Work.AI v.10.3+ and enabled the Control Tower (CT) and Analytics components. See the installation guide.
  • You have obtained the bundles with the NSS Business Processes and machine learning (ML) models from your Account Managers.
  • You have received the credentials for the required watchlists or licenses for the external screening software to be integrated with the AI Agent.
  • You have enabled the Advanced Package Import and Import/Export permissions in CT. For detailed instructions, read Manage Control Tower roles and permissions.

Performance​

Performance is measured per hit across the total run to calculate throughput at the specific scaling level. Test datasets include 20,000 hits.

Number of BEP AgentsInputThroughput
320,000k hits75,800 hits per hour
620,000 hits140,000 hits per hour
2020,000 hits205,000 hits per hour

Install​

For instructions, see the Install AI Agents guide.

Configure​

Once Evelyn is installed, configure the AI Agent before running it for the first time:

  1. Set up Secrets Vault entries.
  2. Select an input source.
  3. Configure the selected input source.
  4. Configure the model.
  5. Configure data enrichment.
  6. Configure manual review.
  7. Set up output options.

You can configure multiple variations or sets of parameters for NSS, for example, a different media provider or a set of keywords per variation. For more information, see the Manage AI Agent Variations.

warning

A secret entry is not a part of the AI Agent package. You must configure it manually after installing Evelyn.

Set up API credentials in Secrets Vault​

To use external data providers, set up credentials in Secrets Vault. For instructions, see the guide.

The following external data providers are supported:

  • Dow Jones Factiva REST API v1.0
  • World-Check One v2.2.0
  • Firco Trust Case Manager API v5.4.22
  • Thomson Reuters CLEAR
tip

Before setting the above data providers, make sure you have obtained required licenses with credentials.

Select input source​

To select a screening provider, do as follows:

  1. In Control Tower, go to AI Agents, find your newly installed Name Sanctions Screening, and click Prepare.

  2. In the configuration window, on the Input step, select from where to source input data for the configured AI Agent.

  3. Configure the selected input source.

Configure input​

To configure the selected input source, specify relevant parameters. For detailed setup instructions, see the sections below:

Screening system​

If you select Screening system as the input source, Evelyn will search for records about an entity or individual in the system you choose in the appropriate drop-down list.

To configure the screening system to work with Evelyn, follow the steps below:

  1. Choose a screening system:

  2. Set up an integration with the selected screening system as described in the instructions below.

Dow Jones Risk & Compliance​

  • API URL. Select the address of the Dow Jones Risk & Compliance API. Available options are as follows:

    • https://api.beta.dowjones.com
    • https://djrc.api.dowjones.com

  • Credentials location. Specify the Secrets Vault alias storing the credentials for the Dow Jones Risk & Compliance system.

  • Number of hits in one request. Specify the number of hits to be processed per request for a particular entity from Dow Jones Risk & Compliance API. This parameter impacts how many requests are sent to Dow Jones Risk & Compliance API. The default value is 500.

  • Desired search type. Set the desired tolerance for the search in the Dow Jones Risk & Compliance system. By default, it is Precise. Available options are as follows:

    • Precise: the mode requires an exact match between the search input and the data in the database. It is highly specific, meaning that the names, dates, or other identifying information must be identical or very close to the input.

      The mode is best suited for situations where you have complete and accurate information about the search entity. It minimizes false positives but might miss matches if there are minor discrepancies in the data (for instance, slight variations in spelling).

    • Near: the mode allows for minor variations in the search input. It is less strict than the precise search, accommodating small differences, such as typos, abbreviations, and slight spelling variations.

      It is most useful when the information might not be entirely accurate or complete. It balances the need to catch more potential matches while still reducing the number of false positives as compared to the Broad search.

    • Broad: the mode is the least restrictive, allowing for significant variations and partial matches between the search input and the database entries. It casts a wide net to catch as many potential matches as possible.

      The mode is perfect when the information is highly uncertain or incomplete. It increases the number of potential matches identified but generates more false positives, requiring additional manual review to filter out irrelevant results.

  • Use developer's mode after configuration. Select Yes to enable the Developer mode for a Business Process. The Developer mode caches requests and responses from the Dow Jones Risk & Compliance API to avoid a ban from Dow Jones due to a massive number of queries.

    For the production configuration, set the value to No.

More about cache

The cache is meant to reduce the number of requests to screening systems. It is implemented as a separate Data Store.

After you install Evelyn, the cache Data Store is empty by default. The hit data is received in responses when a bot sends a name request to an external screening system. The received data is then saved to the cache.

Most screening systems send one response that contains all necessary hit data. But in some cases, there can be two requests:

  • The first one obtains brief information on all hits. The data is saved to the search cache.
  • The second one with the hit ID obtains detailed information on the specific hit. The received data is saved to the hit cache.

Evelyn supports caching both for searches and for hits.

Search cache​
warning

Activate the search cache (with the Developer mode) in development environments only. If enabled in the production environment, Evelyn operates with obsolete data.

The search cache implies that hits for particular names are used from the cache instead of the real-time API. In such a situation, the stored data will soon become outdated. This is why the search cache is intended for the Developer mode only.

The operation flow with the enabled search cache is the following:

  1. The AI Agent sends a search request to the API.
  2. All data received from the API is stored in the search_cache Data Store.
  3. Next time, when input contains the same name for the search, Evelyn will obtain all hits for this particular name from the cache instead of DJ API.
Hit cache​

The hit cache is always enabled to reduce requests to the Dow Jones API and improve BP performance.

The operation flow of the hit cache is the following:

  1. Evelyn sends a search request to the API and receives a list of hits with short data for this name.
  2. Evelyn performs the second request with a specific hit_id to get the hit's detailed info.
  3. The hit details are saved to the hits_cache Data Store. It also stores the date when the hit was updated last time in the database.
  4. Next time, when the AI Agent requests hit details, the system checks whether the hit cache contains up-to-date hit details.
  5. If the hit details in the hit cache are outdated, Evelyn sends a new request for the hit details and updates the cache for this particular hit.
World-Check One​

  • API URL. Select the World-Check One API address. By default, https://api-worldcheck.refinitiv.com is used.

  • World-Check One group. Enter the World-Check One group ID associated with your license.

  • Credentials location. Specify the Secrets Vault alias that stores the credentials for the World-Check One system.

  • Do you want to enable parallel production execution? Select Yes to enable the parallel production execution mode. Then, all alerts will be updated in the World-Check One system with the status set to Unknown and the risk set to Unspecified.

  • World-Check One reason. Enter the name of the reason for updating the alert status in the World-Check One system. Ensure this reason is pre-configured in the Resolution Toolkit within the World-Check One system.

  • World-Check One 'Need more information' update risk. The field contains the risk level to be assigned when selecting Need More Information.

  • World-Check One 'False Positive' update status. Choose the status: Positive, Possible, False, or Unspecified.

  • World-Check One 'False Positive' update risk. The field contains the risk level to be assigned when marking an alert as a false positive.

More about Resolution Toolkit

The Resolution Toolkit configuration provides a default set of resolution states, risks, and reasons used to resolve potential matches generated during the screening process. You can view or modify the Resolution Toolkit in the World-Check One UI or via APIs.

The following example of the Resolution Toolkit illustrates all possible statuses, risks, reasons, and resolution rules that define valid combinations of these elements. Any attempt to resolve a case must comply with the defined resolution rules.

{
  "groupId" : "t3jgv1fffqdudk8ascrep",
  "providerType" : "WATCHLIST",
  "resolutionFields" : {
    "statuses" : [ {
      "id" : "cy8c94bb9z83pndydvdvu",
      "label" : "POSITIVE",
      "type" : "POSITIVE"
    }, {
      "id" : "lhq5ceb5v2387lx65i2v0",
      "label" : "POSSIBLE",
      "type" : "POSSIBLE"
    }, {
      "id" : "iq6p13p73xc0d1ax86rwx",
      "label" : "FALSE",
      "type" : "FALSE"
    }, {
      "id" : "baik1o4jre1extosbozyp",
      "label" : "UNSPECIFIED",
      "type" : "UNSPECIFIED"
    } ],
    "risks" : [ {
      "id" : "k1ld4dgzmgl7p5nt3117l",
      "label" : "HIGH",
      "type" : null
    }, {
      "id" : "9bbysus4odx0z8xl17mur",
      "label" : "MEDIUM",
      "type" : null
    }, {
      "id" : "14t2l2o2v5csz3vhn22by",
      "label" : "LOW",
      "type" : null
    }, {
      "id" : "gbul1lc02506bybw02cvg",
      "label" : "UNKNOWN",
      "type" : null
    } ],
    "reasons" : [ {
      "id" : "d5rj12qz49ih1o7z90fo7",
      "label" : "WF Evelyn NSS",
      "type" : null
    }, {
      "id" : "emyqfbfyiqn1f2u8qtzom",
      "label" : "No Match",
      "type" : null
    }, {
      "id" : "l23ovbpbjzry3kt2v40hz",
      "label" : "Full Match",
      "type" : null
    }, {
      "id" : "16aueejqjnwbrss910zsp",
      "label" : "Partial Match",
      "type" : null
    }, {
      "id" : "ok70toq0yf19kvvb4yk5f",
      "label" : "Unknown",
      "type" : null
    }, {
      "id" : "DEFAULT_REASON_AUTO_RESOLVED",
      "label" : "Auto-Resolved",
      "type" : null
    } ]
  },
  "resolutionRules" : {
    "iq6p13p73xc0d1ax86rwx" : {
      "reasons" : [ "d5rj12qz49ih1o7z90fo7", "emyqfbfyiqn1f2u8qtzom" ],
      "remarkRequired" : false,
      "reasonRequired" : true,
      "risks" : [ "gbul1lc02506bybw02cvg" ]
    },
    "baik1o4jre1extosbozyp" : {
      "reasons" : [ "ok70toq0yf19kvvb4yk5f", "d5rj12qz49ih1o7z90fo7" ],
      "remarkRequired" : false,
      "reasonRequired" : true,
      "risks" : [ "gbul1lc02506bybw02cvg" ]
    },
    "cy8c94bb9z83pndydvdvu" : {
      "reasons" : [ "d5rj12qz49ih1o7z90fo7", "l23ovbpbjzry3kt2v40hz" ],
      "remarkRequired" : false,
      "reasonRequired" : true,
      "risks" : [ "k1ld4dgzmgl7p5nt3117l", "9bbysus4odx0z8xl17mur", "14t2l2o2v5csz3vhn22by" ]
    },
    "lhq5ceb5v2387lx65i2v0" : {
      "reasons" : [ "d5rj12qz49ih1o7z90fo7", "16aueejqjnwbrss910zsp" ],
      "remarkRequired" : false,
      "reasonRequired" : true,
      "risks" : [ "k1ld4dgzmgl7p5nt3117l", "9bbysus4odx0z8xl17mur", "14t2l2o2v5csz3vhn22by", "gbul1lc02506bybw02cvg" ]
    }
  }
}

Evelyn processes the input data provided by the user and watchlist entity (WLE) data from World-Check One using the NSS classification model. Based on the results, a similar response is sent to World-Check One to resolve the case:

{
  "resultIds" : [ "5jb698vlinz01jgl74ymzgtdn", "5jb698vlinz01jgl74ymzgtdp", "5jb698vlinz01jgl74ymzgtdr", "5jb698vlinz01jgl74ymzgtdt" ],
  "statusId" : "lhq5ceb5v2387lx65i2v0",
  "riskId" : "9bbysus4odx0z8xl17mur",
  "reasonId" : "d5rj12qz49ih1o7z90fo7",
  "resolutionRemark" : "Hit is False Positive."
}

Resolution criteria are as follows:

  • Updating results must be enabled in the UI.
  • At least one WLE must be associated with the input data.
  • World-Check One must return caseSystemId in the response.
  • Resolution rules in the Resolution Toolkit must allow the configured reason to be used in combination with all possible risks and statuses.
  • If parallel production is enabled, the status will be Unspecified and the risk will be Unknown.
  • If an alert is selected for automatic quality check, the status will be Unspecified and the risk will be Unknown.
Firco Trust​

  • API URL. Select the address of the Firco Trust Case Manager API.

  • API port. Select the port of the Firco Trust Case Manager API Receive Message Service. You can find the value in the Trust Case Manager API configuration file.

  • Credentials location. Specify the Secrets Vault alias storing the credentials for the Firco Trust system.

  • Firco Trust business unit. Specify the business unit that will get messages from the Firco Trust system.

  • Firco Trust unit. Specify one or more underlying units or feeds associated with the Firco Trust business unit where screening should be performed. To enable parsing of the screened entity's message field, upload a format file to the name_sanctions_screening/firco_format_files/ folder in S3. The format file must follow the following naming convention: <unit_name>_format.csv. See a sample format file for reference.

  • Update alert in Firco Trust system. Select if Evelyn's Business Process must update the alert in the Firco Trust UI with model decisions.

  • Firco Trust 'Need More Information' update status. Specify the alert status to be set if the model's decision is Need More Information.

  • Firco Trust 'False Positive' update status. Specify the alert status to be set if the model's decision is False Positive.

  • Enable obsolete hit filter? Select to filter out obsolete hits.

  • Select period for obsolete filtering. Specify how old a hit should be to be valid for filtering. Works in combination with the Enable obsolete hit filter? option.

For details on parsing data with Firco Trust, refer to Understand NSS data flow.

Thomson Reuters CLEAR​

For Thomson Reuters CLEAR settings, refer to the documentation.

WorkFusion API​

Select WorkFusion API for full alert screening through REST API. To include the complete QC report in the API response body, set Do you want to include QC report content in the API response body? to Yes.

For more details on data transfer via API, refer to Run screening | Call NSS REST API.

Upload CSV file​

Select Upload CSV file for historical data evaluation. The uploaded CSV file should contain historical data and WLE data.

To complete the configuration, provide the following data:

  • Format file location. Specify the S3 path where the format file is stored. Click Download format file to get a CSV template and ensure your uploaded file matches the required format. Only CSV files are supported.

  • Input data file location. Specify the the S3 folder or file path where the historical data is located. Ensure the input file contains input_id (a unique identifier) to minimize unintended volume usage.

  • Do you want to proceed in case of parsing errors in the input file? Choose how Evelyn handles parsing errors in the input file.

    • Set to Yes (default) for the Business Process to process all valid records from the input CSV file, even if some records contain errors.

    • Set to No for Evelyn to use a strict all-or-nothing approach. If any error is detected, the entire Business Process is stopped. See possible scenarios depending on your choice:

    Proceed on parsing errors

    • Scenario 1: no errors in input data

      1. The CSV File Ingestion Business Process successfully parses all records.

      2. All parsed data is sent to the core Names Screening Business Process for processing.

        Result: the Business Process completes as normal.

    • Scenario 2: mix of valid and invalid data

      1. The CSV File Ingestion Business Process scans the file and identifies both valid and invalid records.

      2. A log message is generated indicating the total number of records and how many will be processed (the valid ones).

      3. Error logs are generated.

      4. Only the valid records are sent to the core Names Screening Business Process.

        Result: the Business Process processes valid data and logs errors for invalid records.

    • Scenario 3: all records contain errors

      1. The CSV File Ingestion Business Process scans the file and determines that all records are invalid.

      2. A log message is generated stating that no records can be processed.

      3. Detailed error logs are created.

      4. The Business Process stops gracefully without sending any data to the core Names Screening Business Process.

        Result: the Business Process stops, preventing the core Business Process from running with faulty data.

    Stop on parsing errors

    • Scenario 1: no errors in input data

      1. The CSV File Ingestion Business Process successfully parses all records.

      2. All parsed data is sent to the core Names Screening Business Process for processing.

        Result: the behavior is the same as when the feature is enabled.

    • Scenario 2: mix of valid and invalid data

      1. The CSV File Ingestion Business Process scans the file for errors.

      2. A log message is generated indicating that errors were found.

      3. Detailed error logs are created, specifying the column, defined header name, and line number(s) of the error(s).

      4. The Business Process stops gracefully, and no data is sent to the core Names Screening Business Process.

        Result: the entire transaction is aborted to ensure data integrity.

    • Scenario 3: all records contain errors

      The behavior is identical to Scenario 2. The CSV File Ingestion Business Process stops on the first error and logs the issue.

      Result: the entire Business Process is stopped.

  • Do you want QC report file name to be copied from the input file?: set to Yes (default) if you want Evelyn to generate the QC report file name from the input file name. Subsequently, the QC report is stored under the name and enriched as per QC configuration.

For more information on the historical data evaluation flow, see the guide.

Configure enrichment​

On the Enrichment tab, you can configure name, location, and custom enrichment.

Name enrichment​

In the Name enrichment section, enable or disable name enrichment. The feature is enabled by default.

  1. Select Yes for Do you want to enable name enrichment for all names? to enrich all name fields. If No (default) is selected, Evelyn enriches only the primary name field (input_full_name).

    To enable enrichment only for the security type entities, set Do you want to enrich only entities of the type Security? to Yes.

  2. Select Yes for Do you want email notification with tickers symbols update? to enable email notifications for Ticker Lookup Business Process runs. The feature is disabled by default.

    1. In the Email addresses to notify field, enter the email addresses where notifications should be sent.

    1. In the ds_uc_B_AML_PEP_configuration_v3_0 Data Store, configure SMTP parameters. For details, see Ticker enrichment configuration table.

    2. Add a Secrets Vault entry with authentication credentials. Use the alias stored in smtp.credentialsAlias in the configuration Data Store.

    For more details, see Perform data enrichment | Name enrichment.

Location enrichment​

In the Location Enrichment section, leave Location lookup empty to skip address enrichment.

To enable address enrichment, complete the following steps:

  1. In the Location lookup dropdown, select a provider. The AI Agent retrieves detailed information about the location from the selected provider and enriches ScreenedData and WleData. Available providers are as follows:

    • Google Geocoder. One request is made per address, returning relevant geolocation data.

    • Google Places Api. First, NSS calls https://maps.googleapis.com/maps/api/place/autocomplete/json to retrieve a list of predicted addresses. Then, it calls https://maps.googleapis.com/maps/api/place/details/json to get detailed address information for each prediction.

  2. In the API key field, enter the key used to retrieve geolocation data from the selected provider.

  3. In the Lookup settings section, specify when to perform an address lookup. If enrichment is needed for both the input entity and WLE, select both checkboxes:

    • Lookup on input entity applies address enrichment to input data only.

    • Lookup on watch list entity applies address enrichment to hit data.

In Connection type, the method used to connect to the selected geolocation provider is set to Direct by default, which enables direct calls to the provider.

For more details, see Perform data enrichment | Location enrichment.

Custom enrichment​

The feature lets you enrich standard inputs with your own data sources and transformations.

In Do you want to enable a custom enrichment?, select one of the following options:

  • Yes, via NoCode: use no-code capabilities for simpler logic.

  • Yes, via sync Trigger: syncronously call another Business Process (Synchronous Sub-process Execution) that contains your custom logic to update ScreenedData or WatchListEntities. The sub-process must be schema-based.

  • No: do not use the feauture.

For more details, also see Perform data enrichment | Custom enrichment.

Configure model​

In the configuration window, on the Model tab, you can change the following model-related settings:

  • Leave the Use latest model version selected by default to apply the default prepackaged model.

    To change the model version, deselect the option and select the required version in the Trained Model drop-down list. For the list of compatible models, refer to Supported models.

  • Leave the Include all criteria in the decision narrative option deselected if you want the model's decision narrative to include only the most significant factors for the strong match and weak mismatch (if available).

    Select the Include all criteria in the decision narrative option if you want the model's decision narrative to include all factors for the strong match and weak mismatch (if available).

  • Specify the factors the model uses to identify a hit as a false positive. To define rules, select the Name, Location, Date, Type, Gender, or Identifier checkboxes and set the values in the rules matrix. For instructions, refer to Configure classification model | Rules.

  • Open the Thresholds section and set similarity thresholds for comparing names, dates, and locations. For more details, see Configure classification model | Thresholds.

Configure manual review​

The Human in the Loop step allows you to verify or modify the decisions of the NSS classification model by providing all available information that might be too complex for the model to process. Alerts chosen for manual review remain available in Workspace till manually submitted.

To set the Human in the Loop step, follow the steps below:

  1. Select whether and how you want to check the AI Agent's output manually in Workspace:

    • Enable in all cases: Evelyn sends all alerts with hits to manual review.

    • Enable for Need More Information alerts only: Evelyn creates manual review assignments for alerts where the model decision was Need more information.

    • Enable for False Positive alerts only: Evelyn creates manual review assignments for alerts evaluated as False Positive.

    • Disable in all cases: Evelyn skips the manual review step in all cases, sticking to the model decisions.

    Additionally, for the Enable for Need More Information alerts only and Enable for False Positive alerts only options, type in the exact alert categories that should be forced (Enable for the following alert categories) or skipped (Disable for the following alert categories).

    info

    The above configuration can be overridden by using the mt_force parameter. For details, read Run screening | REST API configuration map.

  2. Select Auto quality check to enable the AI Agent to randomly submit the defined percentage of false positive alerts for additional manual review in the selected screening system.

    • Percentage of false positive alerts. Specify the percentage of false positive alerts to be submitted for additional manual review. The associated screening system is updated to indicate that the AI Agent marked this alert for the auto quality check.

    • If in step 1 you choose Enable for Need More Information alerts only or Enable for False Positive alerts only, choose if you want the alerts flagged for the automatic quality check to be sent for manual review.

Configure output​

On the Output step, choose the format for the screening request reports generated after the Business Process execution and specify their storage location:

  1. Select Yes for Do you want to enable csv report? to generate a Quality Check (QC) report—a CSV file containing detailed information about all completed transactions.

    • Select Yes for Do you want to include field matching results to CSV report? to add field matching data to the report. The following columns are included in the QC report:

  2. Select Yes for Do you want to enable HTML report? to generate an HTML report for each transaction.

    • Select Yes for Do you want to generate a single page combined HTML report? to generate a single-page HTML report.

  3. In the Resulting path field, specify the location where the QC and HTML reports will be saved. The field provides a sample path format.

  4. In the Report bucket field, specify the S3 bucket where the QC and HTML reports will be saved. The default bucket is doc-upload.

  5. Select Year to include the year in the resulting path, for example, 2025, 2026, and so on.

  6. Select Month to include the month in the path, for example, July, August, and so on.

  7. Select Week to include the week of the month in the path, for example, week1, week2, and so on.

  8. Select Day to include the day of the month in the path, for example, 01, 02, and so on.

  9. In the Custom folder field, add an additional folder name to further organize reports, for example, to separate outputs by variation. Depending on your configuration, this folder can appear before or after the date-based folders.

  10. In the Custom file prefix field, add a prefix to generated report filenames to support file sorting or easier identification.

note

The Custom folder and Custom file prefix fields accept only letters, numbers, underscores (_), and hyphens (-). Each value can be up to 25 characters long.

Last updated on