Firco PI Continuity connector

The Firco Continuity Prediction Integration (PI) v5 connector allows you to integrate the Firco Continuity transaction screening solution into Tara's workflow. The connector is used to receive alerts from the screening system and send alert-decision responses.

Installation

info

You must have your own Firco Continuity license to communicate with the system.

Obtain the connector installation files from your account manager or the Support team. Then, install the connector and set up the environment by following the steps below:

On the master node of the installation, create the /opt/workfusion/firco-pi-connector directory as the wfuser.
Copy the following files to the newly created directory:
- firco-continuity-pi-connector-*.jar
- startup.sh
- firco-pi-connector.yml
Grant execute permissions to the copied files by running the chmod +x command.
Edit the firco-pi-connector.yml file to replace all occurrences of the server name with the correct server name for your environment.
In the same directory (/opt/workfusion/firco-pi-connector), create a subdirectory named logs for storing log files.

To support accessing the connector over HTTPS, update the HAProxy frontend configuration. Open the 01_frontends.cfg file located at /opt/workfusion/haproxy/conf and apply the following changes:

acl client_cert    ssl_c_used
 
+    acl to_firco                        path_beg -i /firco-service
     acl to_ags                          path_beg -i /automl-gateway-service
     acl to_ams                          path_beg -i /automl-model-service

# Define criteria for passing requests
-    use_backend CT                           if to_ct ! to_ags ! to_ams ! to_abs ! to_amms ! to_wms ! to_tds ! to_sqc ! to_dataset_management ! to_dataset_management_internal ! to_labeling_service ! to_zoonavigator ! to_manual_task_renderer ! to_task_designer ! to_input_connector_rest    
+    use_backend CT                           if to_ct ! to_firco ! to_ags ! to_ams ! to_abs ! to_amms ! to_wms ! to_tds ! to_sqc ! to_dataset_management ! to_dataset_management_internal ! to_labeling_service ! to_zoonavigator ! to_manual_task_renderer ! to_task_designer ! to_input_connector_rest    
     use_backend WS                           if to_ws
     use_backend BOT_MANAGER                  if to_bot_manager

     use_backend MESOS                        if to_mesos
     use_backend KEYCLOAK                     if to_keycloak
+    use_backend FIRCO                        if to_firco  to_ct
     use_backend AGS                          if to_ags  to_ct
     use_backend AMS                          if to_ams  to_ct

To update the HAProxy backend configuration, open the 02_backends.cfg file located at /opt/workfusion/haproxy/conf and modify it as per the diffs below. Replace my-connector.cloud.workfusion.com with the correct hostname for your environment.

 backend KES
     # try to use HTTP health check; MTLS certificate is required
     option tcp-check
     mode tcp
         server my-connector.cloud.workfusion.com my-connector.cloud.workfusion.com:7373 verify none on-marked-down shutdown-sessions check port 7373 inter 20000 rise 1 fall 1
 
+# Firco
+backend FIRCO
+    mode http
+    http-check expect status 200
+        server my-connector.cloud.workfusion.com my-connector.cloud.workfusion.com:9168 ssl verify none on-marked-down shutdown-sessions check check-ssl port 9168 inter 7000 rise 1 fall 3
+
+
 # TEAPOT
 # Default backend for non-existing DNS
 # https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/418
 backend TEAPOT
   http-request return status 418

To update the Nginx configuration, create the firco-pi-connector.conf file at /opt/workfusion/nginx/sites with the following contents. Replace my-connector.cloud.workfusion.com with the correct hostname for your environment.

# Receives requests for Firco
  
server {
  server_name            my-connector.cloud.workfusion.com;
  listen                 9168 ssl;
  gzip                   off;
  include                snippets/ssl_params;
  include                snippets/proxy_params;
  ssl_certificate        /opt/workfusion/ssl/server.crt;
  ssl_certificate_key    /opt/workfusion/ssl/server.key;
  # Increase large_client_header_buffers because headers and cookies may be so large
  large_client_header_buffers 4 10m;

  # blocking forbidden user agents
  if ($blockedagent) {
      return 444;
  }

  if ($request_method !~ ^(GET|HEAD|POST|PUT|PATCH|DELETE)$) {
      return 405;
  }

  location /firco-service {
    proxy_pass            http://127.0.0.1:9169;
    proxy_redirect        off;
    proxy_send_timeout    600;
    proxy_read_timeout    600;
    proxy_connect_timeout 600;
    send_timeout          600;
    # Increase client_max_body_size for large requests to template-service
    client_max_body_size 1024m;
   }
}

Restart the Nginx and HAProxy services.
Create a dedicated user in Control Tower that the Firco PI application will use to authenticate for every payload.
In Secrets Vault, add a secret entry with firco-credentials-alias to store the username and password created in the previous step.

In Marathon, deploy the Firco PI application by clicking Create Application > JSON Mode. Replace the default content with the following JSON configuration:

{
  "id": "/ia-cloud/firco-pi-connector",
  "cmd": "exec /opt/workfusion/firco-pi-connector/startup.sh >> /opt/workfusion/firco-pi-connector/logs/firco-pi-connector-startup.log 2>&1",
  "cpus": 1,
  "mem": 128,
  "disk": 0,
  "instances": 1,
  "constraints": [
    [
      "bep-worker",
      "CLUSTER",
      "false"
    ]
  ],
  "acceptedResourceRoles": [
    "*"
  ],
  "healthChecks": [
    {
      "command": {
        "value": "curl -s -w '%{http_code}' -o /dev/null http://127.0.0.1:9169/firco-service/actuator/health | grep 200"
      },
      "gracePeriodSeconds": 300,
      "intervalSeconds": 20,
      "maxConsecutiveFailures": 0,
      "protocol": "COMMAND",
      "ipProtocol": "IPv4",
      "timeoutSeconds": 20,
      "delaySeconds": 15
    }
  ],
  "labels": {
    "MARATHON_SINGLE_INSTANCE_APP": "true"
  },
  "portDefinitions": [],
  "taskKillGracePeriodSeconds": 20,
  "upgradeStrategy": {
    "maximumOverCapacity": 0,
    "minimumHealthCapacity": 0
  }
}

Once the application is deployed, encrypt the password for the Control Tower user. Use cURL or Postman to send the password encryption request. The URL format is https://<host>/firco-service/rest/pi/encrypt, with the password as the payload.
Add the user identifier, encrypted password, and the environment, URL, and SSL certificate to your configuration file.

example config

Update the bolded parameters only:

http-client HTTPS_PDClient workfusion_env_host_name 443s /firco-service/rest/pi/sendMessage default-content-type 'application/json' ssl-certificate ../conf/workfusion.pem ssl-verify-cacert ../conf/Microsoft.pem ssl-verify-depth 0 managed-error request-timeout 1800000 retry 0 interval 10000 connect-timeout 60000 retry 2 interval 10000

Configuration

You can configure the Firco PI connector in the firco-pi-connector.yml file.

connector:
    raw-headers-to-ignore: ''
    record-queue: ct-record-queue
    record-status-queue: ct-record-status-queue
    response-timeout: 5m
    signal-id: test-bp-10
    tenant-id: WorkfusionRealm
    auth-url: https://conn-dev-10273.cloud.workfusion.com/workfusion/api/dologin
    firco-credentials-alias: firco-credentials-alias
    resolve-status-value: PASSED
    no-decision-status-value: BLOCKING
    continuous-learning-enabled: false
    continuous-learning-status-value: ContinuousLearning
    continuous-learning-partial-status-value: ContinuousLearning_TARA
    additional-statuses:
      "[name mismatch]": NAME_MISMATCH
    cache:
        expiration:
            password: 5m
            auth-users: 5m
        max-size:
            auth-users: 200

The configuration properties are as follows:

response-timeout: the timeout value for receiving a response from Tara. The default is 5 minutes.
signal-id: the signal identifier of the Tara Business Process to which the connector sends requests.
auth-url: the Keycloak URL used for authenticating the request's user and password.
firco-credentials-alias: the Secrets Vault alias where the raw userId and password are stored for authentication.
resolve-status-value: the status value to include in a PI response for Tara's Resolve status at both the alert and hit levels. The default is PASSED.
no-decision-status-value: the status value to include in a PI response for Tara's No decision status at both the alert and hit levels. The default is BLOCKING.
continuous-learning-enabled: the flag indicating whether continuous learning is enabled. The default is false.
continuous-learning-status-value: the status value to include in a PI response at the hit level when continuous learning is enabled and Tara evaluated the hit with the continuous-learning reason code. If all hits are evaluated with this reason code, the status is also applied at the alert level. The default is ContinuousLearning.
continuous-learning-partial-status-value: the status value to include in a PI response at the alert level when continuous learning is enabled and Tara evaluated some (but not all) hits with the continuous-learning reason code. This value does not apply at the hit level. The default is ContinuousLearning_TARA.
additional-statuses: additional status values to apply in a PI response at the hit level. The key is Tara's rule name, and the value is the status to use when that rule name appears in Tara's response in the reason code array. If a rule name contains a space, enclose the key in double quotes within square brackets.

Installation​

Configuration​

Installation

Configuration