Skip to main content
Version: 4.1

Run screening

Start NSS Business Processes​

The Evelyn contains several Business Processes (BP) that you can use:

Names Screening Business Process​

The figure below shows a core Names Screening BP workflow:

Once Evelyn is installed and configured, you can initiate screening in any of the following ways:

Use signal ID​

To start the core BP via a signal ID, do the following:

To start the core BP, complete the following steps:

  1. In Control Tower, go to AI Agents and locate Name Sanctions Screening.

  2. Click the variation you wish to use. On the variation details page, open the core Names Screening BP.

  3. On the Data tab, select Streaming Records from External Sources and specify a signal ID.

  4. Go to the Run tab and click Run This Process to start the BP.

Once all entities from the input file are processed, the BP automatically completes and uploads the report to S3 Manager.

tip

You can set the core Names Screening BP to run on schedule. For more details, refer to Schedule Business Process.

From REST API with CSV file​

To start the core Names Screening BP using the REST API with a CSV file, ensure you selected WorkFusion API as the input source when configuring Evelyn.

Before running the BP, complete the following steps:

  1. Navigate to the Data tab and click Upload Data.

  2. Select a CSV file and click Upload

The CSV file must contain the required column headers:

  • request_id: unique identifier for internal NSS processing

  • rest_request: JSON containing all required screening details

    Sample JSON
    "{
      ""input_id"": ""3"",
      ""input_full_name"": ""Affred Trump"",
      ""input_record_type"": ""person"",
      ""client_id"": ""123"",
      ""input_gender"": ""male"",
      ""input_address"": [
        {
          ""type"": ""citizenship"",
          ""country"": ""USA"",
          ""state"": ""NY"",
          ""city"": ""New York""
        }
      ],
      ""input_date"": [
        {
          ""type"": ""DOB"",
          ""year"": ""1949"",
          ""month"": ""06"",
          ""day"": ""14""
        }
      ],
      ""hits"": [
        {
          ""hit_id"": ""3_1"",
          ""hit_matched_name"": ""DoNald Trump"",
          ""hit_record_type"": ""INDIVIDUAL"",
          ""hit_gender"": ""male"",
          ""hit_address"": [
            {
              ""type"": ""citizenship"",
              ""country"": ""USA"",
              ""state"": ""NY"",
              ""city"": ""New York""
            }
          ],
          ""hit_date"": [
            {
              ""type"": ""DOB"",
              ""year"": ""1949"",
              ""month"": ""06"",
              ""day"": ""14""
            }
          ]
        }
      ]
    }"

When using REST API with a CSV file as a request source, Evelyn generates QC and HTML reports as configured. One report is generated per REST request, including all associated hits.

Go the Results tab to view the Business Process execution results.

The Final Results section contains the following data:

  • transaction_id: transaction UUID
  • screened_data: input data received for screening
  • wle_list: watchlist entity information received from the selected screening system
  • request_id: external request identifier
  • wle_count: number of watchlist entities found per transaction

For more details, refer to Learn about input and output data.

Name Screening Ticker Lookup Business Process​

Evelyn contains the Name Screening Ticker Lookup BP designed to maintain accurate and current ticker data within the NSS internal storage by retrieving information from https://www.sec.gov/, which is a reliable source of financial data. The BP ensures that ticker data for various financial instruments is maintained properly and supports compliance with regulatory requirements.

To run the BP, complete the following steps:

  1. Open the Name Screening Ticker Lookup BP.

  2. Navigate to the Run tab and click Run This Process.

tip

You can schedule this BP to update ticker information at your preferred frequency.

You can also enable email notifications for BP executions. When enabled, execution results are sent to the specified email addresses.

info

To avoid impacting the production environment, it is recommended to schedule the Name Screening Ticker Lookup BP outside of regular production hours so it does not interfere with the execution of critical BPs.

The Name Screening Ticker Lookup BP writes its execution results to logs. If a ticker is updated or added to the Data Store, the BP generates the following log entry:

Ticker Lookup count before 12345, after 12347

Updated:
ABC, Old ABC Name, New ABC Name

Added:
DEF - DEF Name

If no updates are made, the BP produces the following log entry:

Ticker Lookup no differences

Call NSS REST API​

You can invoke NSS by calling the WorkFusion REST API. To do this, configure an AI Agent variation to source data from the WorkFusion API.

To configure REST endpoints, perform the following steps:

  1. Open the core BP. On the Data tab, select Streaming Records from External Sources. If needed, specify a custom signal ID.

  2. On the Run tab, click Run This Process. Once the BP starts, return to the Run tab and click Show API... to view available generated endpoints.

NSS supports asynchronous invocation only. Use the following endpoints:

  • /start-record-raw to start a BP
  • /check-record-status to check the status of a running transaction
  • /get-record-result to retrieve the result of a completed transaction
additional information

REST API request​

Evelyn supports the following JSON request structure for triggering screening. The structure depends on the selected screening system.

Additionally, a request can include:

  • hits
  • configuration
Full alert screening JSON template
{
    "input_id": String (required),
    "input_full_name": String (required),
    "input_aliases": [
      alias1, alias2 ...
    ],
    "input_record_type": String,
    "client_id": String,
    "input_gender": String,
    "input_address": [
        {
            "type": String,
            "country": String,
            "state": String,
            "city": String,
            "street": String,
            "address": String
        },
        ...
    ],
    "input_date": [
        {
            "type": String,
            "year": String,
            "month": String,
            "day": String
        },
        ...
    ],
    "hits": [ 
        {
            "hit_id": String (required),
            "hit_matched_name": String (required),
            "hit_aliases": [
              alias1, alias2 ...
            ],
            "hit_record_type": String,
            "hit_gender": String,
            "hit_address": [
                {
                    "type": String,
                    "country": String,
                    "state": String,
                    "city": String,
                    "street": String,
                    "address": String
                },
                ...
            ],
            "hit_date": [
                {
                    "type": String,
                    "year": String,
                    "month": String,
                    "day": String
                },
                ...
            ]
        }
    ],
    "configuration":
    {
        "mt_assignee": String,
        "mt_title": String,
        "mt_force": String,
        "mt_filter_sla": String,
        ...
    }
}
Dow Jones Risk & Compliance, World-Check One, Thomson Reuters JSON template

The request JSON structure should only contain the input elements. If the hits element is present, it is ignored.

{ 
  "input_id": String (required),
    "input_full_name": String (required),
    "input_aliases": [
      alias1, alias2 ...
    ],
    "input_record_type": String,
    "client_id": String,
    "input_gender": String,
    "input_address": [
        {
            "type": String,
            "country": String,
            "state": String,
            "city": String,
            "street": String,
            "address": String
        },
        ...
    ],
    "input_date": [
        {
            "type": String,
            "year": String,
            "month": String,
            "day": String
        },
        ...
    ],
    "configuration":
    {
        "mt_assignee": String,
        "mt_title": String,
        "mt_force": String,
        "filter_attribute_1": String,
        ...
    }
}
Firco Trust Case Manager API JSON template

Once the screening with Firco Trust System is initiated, all existing messages are processed via a BP.

Firco Trust business units and units coming from a REST request have a higher priority than the AI Agent configuration. 

{ 
  firco_trust_b_unit: String,
  firco_trust_unit: ["unit_1", "unit_2"]
}

REST API response​

After a successful run, the BP returns a response. The response structure varies based on the screening system.

note

If you enable Quality Check (QC) or HTML reports, the REST response includes hyperlinks to these reports.

Full alert screening JSON template
{
    "input_id": String,
    "alert_resolution": String,
    "alert_explanation": String,
    "html_report_link": String,
    "qc_report_link": String,
    "hits": [ 
        {
            "hit_id": String,
            "hit_resolution": String,
            "hit_explanation": String
        }
    ]
}
Dow Jones Risk & Compliance, World-Check One JSON template
{
    "input_id": String,
    "alert_resolution": String,
    "alert_explanation": String,
    "html_report_link": String,
    "qc_report_link": String,
    "hits": [ 
        {
            "hit_id": String,
            "hit_resolution": String,
            "hit_explanation": String
        }
    ]
}
Firco Trust Case Manager API JSON template
{
    "report_link": []
}
Example of REST API response with hit decision scores
{
    "input_id": "1",
    "alert_resolution": "Needs further review",
    "alert_explanation": "This case can not be evaluated as false positive because there is a hit required additional review",
    "hits": [
        {
            "hit_id": "1",
            "hit_resolution": "False positive",
            "hit_explanation": "False Positive.\nStrong name mismatch (\"THE NEW BROWN FAMILY TRUST\", \"ABCD TEST T\"). ",
            "hit_score": "0.69"
        },
        {
            "hit_id": "2",
            "hit_resolution": "Need more information",
            "hit_explanation": "Please review manually. Not enough information to disposition.\nStrong name match (\"THE NEW BROWN FAMILY TRUST\", \"NEW BROWN FAMILY\"). \nWeak location mismatch (\"Los angeles, Ca, Usa\", \"VA USA\"). ",
            "hit_score": "1.0"
        }
    ],
    "html_report_link": "https://link.to.html_report.html",
    "qc_report_link": "https://link.to.qc_report.csv"
}

REST API configuration map​

You can include JSON configuration parameters in REST requests to override the AI Agent settings for Manual Tasks (MT).

Default parameters​

The following parameters, if sent, are processed by Evelyn to configure manual review assignments:

  • mt_assignee sets an assignee for an assignment in Workspace. For details, see Define task assignees.

  • mt_priority sets the assignment priority. For details, see Set assignment priority.

  • mt_title sets the assignment title. For details, see Adjust assignment title.

  • mt_force forces a request to go to the manual review step:

    • true: always uses manual review.

    • false: always skips manual review.

Additional parameters​

You may include any other parameters in the configuration map, including filter attributes.

Sample request

In the example, mt_filter_sla can be used to create filter attributes.

{
    "input_id": "183800066.6686744",
    "input_full_name": "PINKAL PATEL",
    "input_record_type": "INDIVIDUAL",
    "input_gender": "",
    "input_address":
    [
        {
            "type": "",
            "country": "USA",
            "state": "CT",
            "city": "BERLIN"
        }
    ],
    "input_date":
    [
        {
            "type": "DOB",
            "year": "1976",
            "month": "07",
            "day": "05"
        }
    ],
    "hits":
    [
        {
            "hit_id": "149868084",
            "hit_matched_name": "PINKAL P PATEL",
            "hit_record_type": "INDIVIDUAL",
            "hit_gender": "",
            "hit_address":[],
            "hit_date":[]
        }
    ],
    "configuration":
    {
        "mt_assignee": "aharhots1",
        "mt_title": "PINKAL PATEL - WKSFN2342",
        "mt_force": "true",
        "mt_filter_sla": "01/01/2024"
    }
}

Track NSS API request status​

To support REST request tracking, Evelyn updates a dedicated Data Store whenever an MT is created, saved, or completed.

The tracking feature works only if you meet the following requirements:

  • Select WorkFusion REST API as the input source.

  • Create a Secrets Vault entry using the following parameters:

    • Alias: workspace_url
    • Key: URL to Workspace
    • Value: leave empty

    If no Secrets Vault entry is found during processing, the request status contains an error prompting you to create one.

Evelyn updates the dedicated uc_B_AML_PEP_request_status_v3_0 Data Store with the current request progress in the following cases:

  • When an MT is ready for review.

    The current request ID in the Data Store is updated with the READY_FOR_MT status. The message contains a link to the corresponding MT.

  • After the MT is resolved.

    The current request ID in the Data Store is updated with the MT_COMPLETED status. The message is empty until processing is in progress.

  • After processing completes.

    The current request ID in the Data Store is updated with the FINISHED status. The message is updated with the NSS REST output contract.

For more details, see Understand NSS data flow | Tracking request status table.

View and submit assignment in Workspace​

note

To review assignments, ensure you have required Workspace permissions.

When a Manual Task is triggered, it appears as an assignment in Workspace.

The assignment page displays the following details:

  • Input data

  • Hits

  • Original model decisions

Click a hit to open its details, review information, and validate or adjust the model decision and explanation.

Manual Tasks show a comparison of entity pairs with color-coded values, for example, red for match, green for mismatch.

After you review all hits, submit the assignment. The results and reviewer explanation are returned to the BP and stored in NSS analytics.

Review screening results​

You can review screening results in two ways:

View log details​

Errors are logged in a standardized format to help quickly identify issues.

The syntax is as follows: [Error Type] in column (Client Column Name) on line(s): [Line Numbers]

For example, the log Date Parsing error in column (input_date_1) on line(s): 2,7,15 indicates that the values in the input_date_1 column on lines 2, 7, and 15 of the CSV file could not be parsed as valid dates. CSV headers are indexed at 0 so that line numbers start from 1.

See an example of a full error log from a BP:

You can also trace logs using a client ID and transaction UUID that appear in every log entry generated during BP execution.

When a BP is initiated and a transaction is created, Evelyn performs the following actions:

  1. Generates a unique transaction UUID (transaction_uuid). A UUID is created for each record and persists throughout its lifecycle.

  2. Retrieves a client ID (client_id). The client account under which the transaction is running is identified.

  3. Prepends identifiers to logs. The client ID and transaction UUID are added to all log entries.

info

If a BP runs but no transaction is created or if transaction creation fails, no identifiers are added to logs.

Identifiers appear at the beginning of each log entry, enclosed in square brackets:

  • Standard format: both the client ID and the transaction UUID are displayed, separated by a colon.

    Syntax: [clientId:transactionUUID]

    Example: [352:f47ac10b-58cc-4372-a567-0e02b2c3d479]

  • Conditional format: a special condition applies when the BP is run by the default client with an ID of 1. For such logs, client_id is omitted to reduce noise and improve readability.

    Syntax: [:transaction_uuid]

    Example: [:f47ac10b-58cc-4372-a567-0e02b2c3d479]

Last updated on