Skip to main content
Version: 3.3.4

Install and configure

The guide provides instructions on installing and configuring the Tara AI Agent.

Check requirements​

WorkFusion uses the following options to install and run Tara for transaction screening:

  • On your premise
  • In your cloud
  • In a private cloud hosted by WorkFusion

Hardware​

note

The requirements are for the on-prem installation type.

The servers must conform to the following standards:

ServerRecommended OSCPU (Cores)RAM (GB)HDD (GB)
MasterRHEL/CentOS 8.x832750
BEP AgentRHEL/CentOS 8.x832150
Superset AnalyticsRHEL/CentOS 8.x2450
MS SQLMicrosoft Windows Server 2022, 2019416500

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

Software​

  • Work.AI v10.2.8 or 10.2.9
  • ODF 2
  • Python 3

Performance​

Performance is measured per hit across the total run to calculate throughput at the specific scaling level.

Number of BEP AgentsInputThroughput
320,000 alerts66,667 hits per hour
620,000 alerts110,000 hits per hour
2020,000 alerts250,000 hits per hour

Test datasets include between 20,000 and 100,000 alerts, with an average of two hits per alert. The maximum number of hits per alert in these datasets is 1,000.

The performance testing criteria include the following metrics:

  • Average response time

  • 90th percentile response time

  • Minimum response time

  • Maximum response time

  • Error percentage

  • Overall model throughput for the duration of the run

The following table shows performance results when using 3 BEP Agents.

AlertsAverage response90% responseMinimum responseMaximum responseError %Throughput
18,2164,757 ms5,009 ms2,697 ms267,888 ms05/sec

Install​

See the Install AI Agents guide.

Configure​

You can configure or update the AI Agent configuration in one of the following ways:

  • Go to the Digital Workers tab, select your Business Model, click the Actions menu, and select Settings.

  • Go to the Digital Workers tab and click your Business Model. On the Business Processes tab, click the Actions menu and select Settings.

Configure the following settings:

  1. Input
  2. Model
  3. Data enrichment
  4. Reapplication data
  5. Output

Use the Next or Back buttons to navigate between configuration screens. Click Finish to save the changes.

Input​

In the Input section, specify the way to supply data to your BP.

  1. Choose one of the following options:

  2. In the Maximum hits field, define the maximum number of hits per alert. Alerts exceeding this threshold will not be resolved.

Model​

In the Model section, configure the model settings:

  1. In the Decision model drop-down list, select a compatible model. If none is selected, the default (latest) one is used.

  2. In the Trained NER model drop-down list, select a Named Entity Recognition (NER) model. If none is selected, the default (latest) one is used.

  3. In the Custom rules file (optional) field, provide a unique name for the custom rule file located in a designated directory to prevent overwriting during updates. When configured, the file is used instead of the default rules. You can have multiple versions of the custom rule file.

    info

    The default rule file is stored in a versioned directory, such as doc-upload/payment_sanctions_screening/{$version}/rules/rules_v1.drl. Modifying the default file is not recommended.

  4. In the Name matching field, enter a value between 0 and 1.00. Consider names a match if they are similar to a screened entity at least to the defined extent.

    Scores closer to 0 indicate less similarity, while scores closer to 1.00 indicate more similarity. Below the threshold, names are considered different, resulting in a mismatch. Above the threshold, names are considered similar and referred to as a match.

    The default value is 0.75. For example, a name with a predicted match score of 0.75 or higher is considered matching or partially matching.

    note

    Increasing the threshold value might reduce name matches, potentially increasing the automation and error rates.

  5. In the Token overlap configuration drop-down list, select one of the following options:

    • None (default) does not apply specific token overlap criteria, resulting in the final name score determined by other matching methods or defaults.

    • Rare boosts the name score for rare or unique token overlaps, favoring matches where unique identifiers are critical. For example, "SBERBANK ZRT" versus "CORPORATE UNIVERSITY OF SBER BANK" results in a name match if selected.

    • Screened prioritizes matches where the screened name is contained within the watchlist entity (WLE) name. For example, "Doors LLC" versus "Wood Doors Installation Services LLC" results in a match if selected.

  6. Select Ignore middle names during name matching to prevent middle names (individual names other than the first or last name) from contributing to a name mismatch. Selecting the option can reduce the error rate when names are similar but have different middle names but it can also lower the automation rate by causing more names to match.

  7. In the Date of birth matching field, enter a value between 0 and 9999. Dates within this range are considered matching.

    The default value is 365. Thus, if Tara identifies birth dates that are within 365 days of each other, it considers them a match. When two birth dates are more than the specified number of days apart, they are considered a mismatch.

  8. In the ID matching section, select ID prefix match to match IDs with the same prefix. For example, "NL0123456789" matches "NL0123456".

  9. In the Address matching section, select an option to compare addresses:

    • String Comparator (default) compares two addresses. If all tokens match, the addresses are considered a match. The method is executed first regardless of the chosen option. If two addresses are identical, there is no need to use additional services.

    • Google geocoder compares all available addresses from the screened and sanctioned data by sending them to the Google geocoder for validation. If an address exists, the geocoder returns a placeId value. If the placeId values match, the addresses are considered a match.

      To enable the geocoder functionality for address matching, you must select the Google Web Services option on the Data enrichment tab. In case of failure or if no result is returned from the call, String comparator is used.

    • External address matcher service is an in-house product that uses the Nominatim API to compare addresses. The service is installed separately from Tara and must be running to accept calls. It returns a structured response, for example, {"house_number_match": true,"road_match": true,"city_match": true,"state_match": false,"country_match": true,"postal_code_match": false}. If the house number, road, city, and country all match, the addresses are considered a match.

    In the External address service endpoint field, set the service endpoint. You can use the following endpoints for testing: https://v125---address-verification-e6afplakwq-uc.a.run.app or https://address-verification-lk-1041123399231.us-east4.run.app. In case of failure or if no result is returned from the call, String comparator is used.

  10. In the Country from IDs section, the Extract country codes from IDs for location matching option is selected by default for Tara to extract country codes from known ID types. For example, in IT26S0306933090100000003191, IT is extracted for Italy. To disable the feature, deselect the option.

  11. In the Blacklisted entities section, configure specific blacklisted entities for Tara to automatically escalate hits if such entities are detected. Otherwise, select No for Do you wish to provide blacklist configurations?.

    • In the Blacklisted keywords field, enter keywords that should trigger a blacklist-based search.

      • Select where to search for blacklisted entities to trigger an escalation: Tag content or Entity name.

    • In the Blacklisted countries field, the listed countries are considered restricted. By default, the following countries are included in the blacklist: Iran, Cuba, Syria, North Korea, and Russia.

      You can manually add more blacklisted entities. Start typing a country name and select it from the pre-populated list. Mind that the fewer entries are blacklisted, the higher the automation rate is.

      • Select where to search for blacklisted country names:

        • None. Tara always checks the screened country field and NER-detected countries in the tag content.

        • Tag content. In addition to the default checks, Tara scans the entire tag content for explicitly mentioned blacklisted country names.

        • Entity name. Tara searches for blacklisted countries in the entity name field.

          Tara automatically escalates if a blacklisted country from the provided list appears in a hit.

Data enrichment​

In Data enrichment > Address verifier, specify external data sources to retrieve additional data. Select Google Web Services and provide a valid access token:

  1. In the Google Maps API Key field, enter your Google Maps API key for address verification. For more details on getting a key for a Google Cloud account, see Using the Google Maps Platform.

  2. In the Secrets Vault Alias field, provide the alias that identifies your secure entry.

For more details, see Perform location validation.

Reapplication data​

In Reapplication Data > Enable DR Processing, select yes to enable the decision reapplication flow. By default, the feature is disabled.

When enabled, configure the following settings:

  1. Add message tags.

    1. In the Message Format drop-down list, specify the message type to target for decision reapplication. Supported formats include FUF, SWIFT_MT, ISO20022(SWIFT_MX), and SWIFT_NPP.

    2. In the Tags field (optional), enter tag names from an alert as comma-separated values. The tags are compared against historical data together with hashed hit content. TYPE is recommended.

    To add additional message types, click Add another.

    If message types are added, they are used in decision reapplication. If the configuration changes, you must reload historical alerts for the changes to take effect.

  2. Select the Decision Level option. Specify the level at which the decision reapplication will be applied:

    • Hit Level resolves individual hits that match historical decisions.
    • Alert Level resolves the entire message if all hits match historical decisions.

  3. Select Include auto-escalation of hits to use decision reapplication to automatically escalate hits on historically escalated or disabled hits. For more details, refer to Apply continuous learning.

  4. In the Search timeframe (in days) field, specify the maximum number of past days to search for historical data. Older decisions will not be considered for reapplication. If the field is left blank, the default value of 365 days is applied. The field is only used during historical uploads.

  5. In the Minimum event counter field, specify the minimum occurence of the same hash found in historical data. The condition must be satisfied before applying a CLDS decision.

  6. In the Minimum analysts counter field, define the minimum number of analysts who made decisions on the same alert found in historical data. The condition must also be met before applying a CLDS decision.

  7. Select Require tag content match for decision reapplication to enforce strict tag content suitable for decision reapplication. Enabling this option reduces reapplication rates.

  8. Select Require Message sub-type for decision reapplication to treat tag content as part of the hash for successful decision reapplication. Enabling this option also reduces reapplication rates. If the configuration changes, you must reload historical alerts for the changes to take effect.

  9. Set historical decision types to be treated as resolved by an analyst. Specify decision codes from historical files to mark alerts as RESOLVE (released) during historical data uploads. If the value is modified, reload historical alerts for the changes to apply.

  10. Set analyst or operator names to be excluded from continuous learning decision calculations. The specified names are excluded from the analyst count when determining whether a hit is suitable for reapplication. If the values change, you do not need to reload historical data. The setting does not affect hashes that are already enabled.

  11. Select the Use message-level analyst comments for every hit option to apply analyst comments from the messages.csv file to all hits, not just records with a single hit. If analyst comments are not recorded, the default narrative is used.

For more details on the feature, see Business Process overview | Ingest Historical Decisions for Reapplication Business Process and Apply continuous learning.

Output​

In the Output section, enable generating HTML, quality control (QC), or CLDS reports after a BP run.

  1. In the S3 bucket name field, specify a custom S3 bucket to securely store reports and historical data. The option also restricts access to the specified bucket.

  2. Select Include detailed narrative in response to generate and add a comprehensive explanation in the response. The HTML report contains this detailed narrative by default.

    A sample response with the additionalInfo field
    {
    "decision": {
            "messageId": "1",
            "suggestedAction": "RESOLVE",
            "comment": "RESOLVE: all hits resolved by [name_country_mismatch_strong]; ",
            "hitDecisions": [
                {
                    "reasons": [
                        {
                            "score": 0.5593499999999999,
                            "code": "name_country_mismatch_strong",
                            "description": "Name and country mismatch. Strong. Screened name (INVESTMENT HOLDINGS INC) does not match sanctioned name (CONSOLIDATED INVESTMENTS LLC) and aliases. Screened location (US) does not match sanctioned location (RU)"
                        }
                    ],
                    "hitId": "1",
                    "additionalInfo": "TYPE MATCH:true; Input type = 'ORGANIZATION' with confidence score = 1.000000; Sanctioned type = 'ORGANIZATION'.\nNAME MATCH:false; Screened input = 'INVESTMENT HOLDINGS INC' Sanctioned input = 'CONSOLIDATED INVESTMENTS LLC' Matching score = 0.559350.\nCOUNTRY MATCH: false; Screened input = '555 EAST STREET, NEW YORK 10500 USA'; Sanctioned input = 'MOSCOW RU'\nID MATCH:null; Screened input = '0000123456'  Sanctioned input = ''.\n",
                    "suggestedAction": "RESOLVE",
                    "comment": "Name and country mismatch. Strong. Screened name (INVESTMENT HOLDINGS INC) does not match sanctioned name (CONSOLIDATED INVESTMENTS LLC) and aliases. Screened location (US) does not match sanctioned location (RU)"
                }
            ]
        },
        "requestId": "e7c7b331-853e-4e15-b5f3-de618766d668",
        "statusDetails": "",
        "status": "COMPLETED"
    }

  3. To enable generating HTML reports, select Yes for Do you want to generate HTML report?.

    1. Do you want to generate a single page combined HTML report?. Select Yes to generate a single report file for all sanctioned hits. Otherwise, select No to generate separate files for each sanctions hit.

    For more details on how to find a generated report, see Run screening | View results.

  4. To enable generating QC reports, select Yes for Do you want Quality control report to be generated?. A QC report provides a snapshot of all the data fields of messages and their corresponding hits in the CSV format. If enabled, you can run the PSS QC report BP manually or on schedule.

    1. Do you want to generate the report with standard columns?. Select Yes to generate a report using standard columns provided in the file in S3, for example, doc-upload/payment_sanctions_screening/reports/templates/qc_report_template.csv.

      If you select No, upload a custom qc_report_template_custom.csv file to the same S3 location as above. In the file, you can use a truncated version of the original template file, selecting the columns required for your reporting purposes.

    2. Choose the time range or business process execution ID for data collection. Select one of the following options:

      • Today. Collect data from 12 AM to the current time.

      • Last x days. Specify a range that includes the current date. In the Number of passed days field, enter a value between 1 and 31.

      • Last x months. Specify a range that includes the current date. In the Number of passed months field, enter a value between 1 and 12.

      • Custom. In the From and To calendar widgets, define a date range.

      • Business process execution IDs. In the UUIDs field, enter one or more BP run UUIDS to limit results to specific executions.

    3. In the Maximum file size (MB) field, set the maximum file size (up to 100 MB). If exceeded, multiple files are created.

  5. To enable generating CLDS reports, select Yes for Do you want CLDS report to be generated?.

    1. Do you want to generate the report with standard columns?. Select Yes to generate a report using standard columns provided in the file in S3, for example, doc-upload/payment_sanctions_screening/reports/templates/clds_report_template.csv.

      If you select No, upload a custom clds_report_template_custom.csv file to the same S3 location as above. In the file, you can use a truncated version of the original template file, selecting the columns required for your reporting purposes.

    2. Choose the time range or business process execution ID for data collection. Select one of the following options:

      • Today. Collect data from 12 AM to the current time.

      • Last x days. Specify a range that includes the current date. In the Number of passed days field, enter a value between 1 and 31.

      • Last x months. Specify a range that includes the current date. In the Number of passed months field, enter a value between 1 and 12.

      • Custom. In the From and To calendar widgets, define a date range.

      • Business process execution IDs. In the UUIDs field, enter one or more BP run UUIDS to limit results to specific executions.

    3. In the Maximum file size (MB) field, set the maximum file size (up to 100 MB). If exceeded, multiple files are created.

    For more details on CLDS reports, refer to Apply continuous learning | View CLDS report.

Customize configuration settings​

During the AI Agent configuration phase, a BP starts with reading the settings from the configuration.json file that contains all parameters required to load data and control a data flow.

Default configuration.json
{
  "input": {
    "source": "file",
    "message_datastore_name": "pss_request_processing_v1",
    "ml_thresholds_datastore_name": "pss_payment_transfer_thresholds_v1",
    "fuf_tag_datastore_name": "pss_fuf_tags_list_v1",
    "swift_tag_datastore_name": "pss_swift_tags_list_v1",
    "iso20022_tag_datastore_name": "pss_iso20022_tags_list_v1",
    "maximumHits": 100
  },
  "model": {
    "model_id": "",
    "ner_model_id": "",
    "go_forward_on_failure": "false",
    "default_model_Id": "pss-classification-model-5.1.3",
    "default_ner_model_Id": "named-entity-recognition-2.3.0",
    "nameMatchThreshold": 0.75,
    "dobMatchThreshold": 365,
    "matchIfRareTokenOverlap": "none",
    "nameMatcherIgnoreMiddleNames": false,
    "idPrefixMatch": false,
    "extractCountryFromId": true,
    "blacklistConfig": "yes",
    "blacklistedKeywords": "",
    "blacklistedKeywordsSource": "tagContent",
    "blacklistedCountries": "Russia,Cuba,North Korea,Iran,Syria",
    "additionalBlackListedCountrySource": "tagContent"
  },
  "geocoder": {
    "alwaysRun": false
  },
  "addressMatcher": {
    "matcher": "string"
  },
  "useExternalNameMatchingServiceBabel": false,
  "configureForEachTypes": false,
  "qcReport": {
    "StandardColumns": "yes",
    "searchBy": "TODAY",
    "maxVolume": 50
  },
  "cldsReport": {
    "StandardColumns": "yes",
    "searchBy": "TODAY",
    "maxVolume": 50
  },
  "output": {
    "generate_report": false,
    "onePageReport": false
  },
  "decisionReapplication": {
    "isEnabled": false,
    "tagsToCompare": "",
    "numDaysToLookBack": "365",
    "level": "hit",
    "matchTagContent": false,
    "matchSubType": false,
    "minimumCounter": 5,
    "minimumAnalysts": 2,
    "resolveType": "Released",
    "setupDataGrid": [
      {
        "drMessageType": "swift_mt",
        "tagsToCompare": "TYPE"
      },
      {
        "drMessageType": "fuf",
        "tagsToCompare": "TYPE"
      },
      {
        "drMessageType": "swift_mx",
        "tagsToCompare": "TYPE"
      },
      {
        "drMessageType": "swift_npp",
        "tagsToCompare": "TYPE"
      }
    ]
  },
  "container": {}
}

Default configuration parameters​

You can customize some settings, some are hidden from the user interface and cannot be changed. All Data Stores are built during the bundle import stage, and you cannot change their names.

The default configuration parameters are listed below.

Input parameters
  • message_datastore_name contains processing data, including new and updated messages during BP execution.
  • ml_thresholds_datastore_name contains the mapping of decision codes, such as definitions, confidence thresholds, and decisions.
  • fuf_tag_datastore_name contains the FUF dictionary of entity attributes and their associated types.
  • swift_tag_datastore_name contains the SWIFT dictionary of entity attributes and their associated types.
  • iso20022_tag_datastore_name contains the ISO20022 dictionary of entity attributes and their associated types.
  • maximumHits refers to the maximum number of hits per alert. Alerts exceeding this limit are auto-dispositioned as no decision.
Model parameters
  • model_id is the ML model for processing input data to determine possible false positive hits. If not provided, the default_model_Id value is used.
  • ner_model_id is the NER ML model for processing input data to determine possible entity types. If not provided, the default_ner_model_Id value is used.
  • go_forward_on_failure is required to run Execute AutoML Model.
  • default_model_Id is the model version that comes with the bundle during the release.
  • default_ner_model_Id is the model version that comes with the bundle during the release.
  • nameMatchThreshold controls the outcome of the name matcher score and name match and mismatch decision.
  • dobMatchThreshold controls the outcome of the date of birth (DOB) matcher and DOB match and mismatch decision.
  • matchIfRareTokenOverlap influences the name matcher score calculation. The default value is none. When set to true, a hit on a rare token increases the score, lowering the error and automation rates.
  • nameMatcherIgnoreMiddleNames influences the name matcher score calculation. The default value is false.
  • idPrefixMatch influences the ID matching logic based on prefix similarity. The default value is none.
  • extractCountryFromId extracts country data from IDs for location matching. The default value is true.
  • addressMatcher.matcher compares addresses. The default is a string. Geocoder and AV Service are available.
  • blacklistConfig, blacklistedKeywords, blacklistedKeywordsSource, blacklistedCountries, and additionalBlackListedCountrySource are used to configure countries or entities that need to be escalated if found in the screened data.
HTML report output parameters
  • generate_report generates HTML reports stored on the MinIO server. The default value is false.
  • onePageReport determines whether reports should be single-page or multi-page.
QC report parameters
  • StandardColumns uses the default report template. The default value is yes. Otherwise, provide a custom file.
  • searchBy specifies the search scope. The default value is TODAY.
  • splitReportBy limits the report size. The default value is SIZE, with the maximum file size value (maxVolume) of 50 MB.
CLDS report parameters
  • StandardColumns uses the default report template. The default value is yes. Otherwise, provide a custom file.
  • searchBy specifies the search scope. The default value is TODAY.
  • splitReportBy limits the report size. The default value is SIZE, with the maximum file size value (maxVolume) of 50 MB.
CLDS parameters
  • isEnabled enables the data reapplication functionality, when set to true.
  • drMessageType and tagsToCompare target specific message types and tags to be included in the CLDS processing. The supported formats are SWIFT_MT, SWIFT_MX, SWIFT_NPP, and FUF.
  • numDaysToLookBack defines the range to search historical data for matching records. The default values is 365 days.
  • level specifies a decision reapplication level. The default value is hit.
  • escalate allows decision reapplication to automatically escalate decisions on historically escalated or disabled hits. The default value is false.
  • matchTagContent determines if the tag content must match. The default value is false.
  • resolveType sets a historical decision type that should be treated as resolved. The default value is Released.

Data Stores​

All Data Stores used in the Transaction Screening processes are built during the bundle import stage. Their names cannot be changed.

Data StoreDescription
pss_request_processing_v1The main Data Store that stores all requests, processing updates, and decisions.
pss_payment_transfer_filtering_rules_v1Not used; empty. Remains for backward compatibility.
pss_alerts_analytics_v1Contains per alert analytics.
pss_messages_analytics_v1Contains per message analytics.
pss_fuf_tags_list_v1Contains FUF tags versus type data dictionary. Used when parsing FUF messages.
pss_iso20022_tags_list_v1Contains ISO20022 tags versus type data dictionary. Used when parsing ISO20022 messages.
pss_swift_tags_list_v1Contains SWIFT tags versus type data dictionary. Used when parsing SWIFT messages.
pss_de_analytics_v1Contains analytics of data enrichment service calls for Open Corporates and Geocoder.
pss_reapplication_hashcodes_v1Contains historical data for decision reapplication on the hit level.
pss_dr_file_analytics_data_v1Contains analytics of loading CLDS historical data.
pss_clds_hash_analytics_v1Contains summary information about each hit hash of historical data.
pss_request_processing_test_v20_4000 and similar test filesContains synthetic data generated for testing.
Also, see

Dictionaries​

The pss_swift_tags_list_v1, pss_fuf_tags_list_v1, and pss_iso20022_tags_list_v1 dictionaries are used for assigning TagType and parsing tagContent. A dictionary has limited entries, so the tagType value is usually FREETEXT. You can update a dictionary and add a particular field parser if needed. Currently, treat it as a framework with limited functionality. If any tag is empty, it cannot have a hit on its value. Thus, empty tagContent is considered as invalid input.

  • If the Type tag is FREETEXT, the tag content is passed to the NER model. NER marks each token with a predicted type (IND, ORG, LOC, OTHER). Then, a predicted name is calculated based on a provided hit text or sanctioned name.

  • If the Type tag is NAME, the model treats the tag content as an entity name.

  • If the Type tag is NAMEADDRESS of ADDRESS, the model finds an address and parses it to determine a country.

Create test dataset​

To add a test dataset to your model, complete the following steps:

  1. Go to AutoML > Datasets and create a test dataset. Memorize its name as you need it in further steps. For instructions, refer to the Manage datasets topic.

  2. Go to AutoML > Models and find your model in the list.

  3. Click the model's Actions menu and select Copy to modify.

  4. On the Modify window > Prototype > Model ID, specify a new name of the model variant and click Next to continue. Mind that the name must start with pss-classification-model.

  5. On the Testing tab, select the dataset from step 1.

  6. Click Start to build a new model.

  7. Go to AutoML > Models. The model appears in the list, and you can choose it during the AI Agent configuration.

Last updated on