Compliance Safety Net Implementation Guide

Important Note: The API has changed in a way that breaks old code. Unless you are starting afresh consult the Required Updates section below.

About Compliance Safety Net

This document is intended for partners who are integrating the Compliance Safety Net into their platform system.

The Compliance Safety Net is a dynamic workflow software component that takes administrative and transaction data from a platform system and guides the end user through a CSi data collection workflow that gathers all necessary data to complete all logic requirements of the IntelleDoc library in order to fully document financial transactions. Workflow also supports reintegration of the resulting data back into the platform system.

Application Architecture for Compliance Safety Net

Two Layers and an API

The platform system must wrap the Workflow into its application. This is the top layer of the pyramid (image below). This may be managed in several ways, such as

• a button that opens the browser,
• a tab that displays the workflow within the application,
• or, in a Windows-based application, the user interface can be directly folded into the application.

This User Interface layer must be separate from the underlying Logic Layer, which contains the Compliance Safety Net application and logic. This separation best supports multiple and varying platform technology environments. It also provides CSi with the ability to create a testing layer for DCL-based workflows.

These APIs work through an endpoint accepting POSTs of JSON data. (See below.)

The following sections provide more detail on the architecture of the underlying logic layer functionality. This functionality is part of the Compliance Safety Net application, but it relies upon the Data Collection Logic (DCL) component, which is available to use directly for other purposes.

User Interface Layer

The User Interface Layer is only responsible for interpreting the information coming from the API between the layers and turning that into the appropriate interface representation. Please refer to the API Between Layers section of this document for more information.

The representation of the control type, the UI label, an indicator of whether the field is required, and the metadata to provide help content is provided.

Logic Layer

All “controller-esque” functionality runs in the Logic Layer. This includes interaction with the DCL.

In the case of the Compliance Safety Net application, this layer also includes:

• the application configuration control,
• the encoded logic overrides,
• and other features unique to the Compliance Safety Net.

While in the same application, these are separated to enough to avoid causing difficulty with reusing the core functionality (DCL-in-a-box).

API Between Layers

A clearly defined API between the User Interface and Logic Layers is critical to the success of this architecture and making it modular for varying partner technology environments.

For this to be efficient, it also needs some means to recall the previous submission so that data already provided, in particular metadata help content, does not need to be retransmitted.

Compliance Safety Net Logic and Data Grouping Overrides (Logic Layer)

Compliance Safety Net work at a transaction level. This is a key conceptual difference to CSi Simplicity. A different model is used to group data into tabs in the user interface.

This is where data grouping overrides occur. Whereas Simplicity orders and groups data according to the logic that brings individual modules into play and the sequence of those modules within the Simplicity workflow FXL, data grouping overrides are managed through ciguring the Library Data Dictionary (LDD) structure within the Compliance Safety Net application. The LDD is not configurable by the partner.

If partners are using the DCL in other areas of their application, thenthe following model applies:

• The grouping consists of setting a group with an ID and a label.

• A list of data elements references each one back to a group ID.

• The order of the list determines the order on the data collection screen.

The User Interface layer uses this information to optimally organize the interface for collecting the data.

Session Initiation

A Compliance Safety Net session is the platform system’s initiated workflow on behalf of one of their financial institution users for the purpose of completing a transaction for the institution’s customer.

Session Authentication

The Workflow does not have any user accounts. Instead, the platform must provide a valid license key with each startsession request. When the license key is valid the Workflow will reply with a JSON object that includes a response URL. You will use response/session URL for the remainder of the session as a whole or until it expires.

Simplicity Supplemental Execution

To ensure that all the data required is included in the session (such as data configuring headers and footers and other administrative level setup data), Workflow must execute the client’s Simplicity Supplemental FXL file first.

You supply the client’s license key and the directory of FXL files in the request to initiate a session, and the Workflow executes the Simplicity Supplemental FXL to select data to be used within the workflow.

DSL Inclusion

Workflow is unlike CSi Simplicity data collection in that it is uses the DCL in conjunctino with an entire transaction. This includes using the DSL to select documents. Core DSL data is always required to start a session. In particular, the RMD for the type of transaction you are working on should serve as a start-point.

Document Versions

The Compliance Safety Net needs to execute with the platform’s current library of FXL files with which rendering will take place to ensure that there is no possibility of mismatched versions. You do this via setting the documentLibraryVersion in your JSON.

{
    ...
    "documentLibraryVersion": "2017.95.0"
    ...
}

Save and Exit

Workflow enables users to both Save and Save and Exit. This feature returns the user to the platform to fully render the transaction. The save notification URL will be supplied by the platform and the Compliance Safety Net application will send an HTTP POST notification to that URL when the user completes the process.

Consider the following JSON request to start a session. In particular, it includes a notification URL, and a redirect URL that indicate where subsequent operations should be directed for that session.

 {
    "client":
    {
        "licenseKey": "<<your license key goes here>>"
    },
    "notificationUrl": "https://objectrepository.test.compliancesystems.cloud/repositorywebservices/publish/simplicitypublish",
    "redirectUrl": "https://www.google.com",
    "configuration": {
        "id": "1dfb86bc-3995-4b1b-a89d"
    },
    "documentLibraryVersion": "2017.102.0",
    "transactionData":["<<your base64 encoded RMD data goes here>>"
    ]
}

This prompts the platform to get the final state of the transaction data and use it to render the transaction.

Example Request

The following is a sample request to initiate a session (HTTP POST) with the Compliance Safety Net application.

{
    "session": {
        "user": {
            "firstName": "Jimmy",
            "lastName": "Johnson"
        }
    },
    "client":
    {
        "licenseKey": "<<your license key goes here>>"
    },
    "configuration": {
        "id": "1dfb86bc-3995-4b1b-a89d"
    },
    "notificationUrl": "<https://platform/Listener>",
    "redirectUrl": "https://www.google.com",
    "fxlLocation": "C:\\Path\\To\\FXLs\\",
    "documentLibraryVersion": "2017.102.0",
    "transactionData":["<<your base64 encoded RMD data goes here>>"]
}

You must specify the desired workflow in the startSession endpoint, e.g.

• /api/startsession/deposit

• /api/startsession/lending

• /api/startsession/tfa

• /api/startsession/paymentcalculation

Session Conclusion

At any point, the platform can make an API call with a session id that returns the current transaction data. This call is also used at the conclusion of the session when the user invokes the Save and Exit feature.

This is important. The session ID has a renewal period. After so many minutes a new API session ID will be assigned. It is the responsibility of the caller to retain the new session ID when assigned. For example, suppose the session renewal period is 5 minutes.

• Call to StartSession API –> new session and ID is generated - Call to Session API 4 minutes later –> same session ID is returned

• Call to Session API 3 more minutes later –> a new session ID is returned and the old session ID is no longer valid.

With a valid (unexpired) session ID, you can post the following JSON to https://workflow.test.compliancesystems.cloud/1.0/api/session like this:

{
  "session": {
    "id": "<<API session ID from initial start request or last API call>>"
  }
}

In response, Workflow will reply with something like this:

{
    "transactionData": "<<updated transaction values>>>",
    "messages": [],
    "session": {
        "id": "<<API session ID from initial start request or last API call"
    }
}

In the unlikely event of an error, you may see one or more error messages.

The application returns the updated transaction data.

A separate operation is available for removing a session when applicable. This may be done, for example, if the user did not really want to start that action.

Session State

This section describes the functional integration of the Compliance Safety Net.

User Connection Issues

If users are disconnected from the Compliance Safety Net before they have completed it due to connectivity issues, accidental tab closure, etc., then the platform needs to manage resumption of the workflow. This is done through the Save and Resume method.

Save and Resume

In order to save the user’s place in the workflow, the Save button initiates a notification (please refer to the topic Save and Exit) to the platform. This allows the platform to make the call to get the current TXL data from the Compliance Safety Net application.

By sending a notification rather than the data, the amount of data going over the wire is limited to just those instances when the platform application is ready to handle it.

The platform can call API/“session” after receiving a save notification to get the current session data.

Session Persistence

The session data will persist only in memory. If the application server is restarted, all sessions will be lost and users will have to restart the Compliance Safety Net. The session data will persist in memory for a limited time. The default session persistence is 60 minutes.

Session Expiration Notification

If a session is within 10% of the total time prior to its removal, a notification is sent to saveNotificationUrl that the session is about to expire. This does not extend the session’s life.

Data Persistence in the Platform

System of Record

If data collected in the Compliance Safety Net is required to be booked back to the system of record, then the platform development team must map that data from the TXL format back to the appropriate system data structure.

Other Data

All other data is most easily persisted in its original TXL format associated with the transaction that occurred at the financial institution. That allows it to be recalled in the future to re-render or modify the data by sending it back to the Compliance Safety Net.

Distribution and Deployment Models

Within the Platform System

Some partners may embed the User Interface Layer directly and not use the Logic Application Layer. Instead, they may use their DCL application code and leverage the User Interface Layer only.

Linked from the Platform, Running Separately

Partners may elect to treat the Compliance Safety Net as an independent application that they link to within their application in a manner similar to what happens with CSi Simplicity today. This requires them to have both the User Interface Layer and the Logic layer running together as a separate application on IIS.

Data Inputs and Outputs

By default, the Compliance Safety Net is configured so that only the data that is modified in a session is returned, but this can be changed so that the application returns all session data, including data passed to the Compliance Safety Net that is not modified in the session.

Required Updates

Start Session for Specific Workflow

To start a session the HTTP POST that heretofore went to /api/startsession has changed. You must specify the desired workflow. For example, use one of these end-points:

• /api/startsession/deposit
• /api/startsession/lending
• /api/startsession/tfa

Change the last part according to the workflow you are using.

This change enables more effective routing through a load balancer in the CSi Cloud Utility to deliver better performance to you.

Change saveNotificationUrl to notificationUrl

The saveNotificationUrl now does more than just saves data. To reflect this fact, it is now renamed notificationUrl.

Specify the documentLibraryVersion

The API now requires a new property: documentLibraryVersion. This setting needs the Year and ChangeVersion portions of the CSi Document Library version such as shown here:

{
    ...
    "documentLibraryVersion": "2017.95.0"
}

Important Note: Currently this setting is not operational behind-the-scenes.

The Compliance Safety Net app is using the latest tested and approved version of the document library for each workflow. This will continue to be the case for a number of weeks as some updates to the documents are tightly coupled to finalizing the Compliance Safety Net functionality.

Specifying the document library will be key to production version stability and eliminating the tight coupling between the Compliance Safety Net app layer and the IntelleDoc Solutions components.

Optional Updates

Multiple TXLs

The startsession API request can now include multiple TXLs by sending an array of TXL strings to the transactionData property.

Current functionality is maintained where a single TXL can be sent in to start a new Compliance Safety Net session.

{
    ...
    "transactionData": "<TransactionValues><!-- whole txl --></TransactionValues>"
}

Now a collection of TXL data can be sent like:

{
    ...
    "transactionData": [
        "<TransactionValues><!-- default txl --></TransactionValues>",
        "<TransactionValues><!-- workflow data from a previous session --></TransactionValues>",
        "<TransactionValues><!-- mapped TXL with new data from platform --></TransactionValues>"
    ]
}

If there are any conflicting data values, the last TXL wins. This is designed to support a pattern where you may have a fixed TXL with defaulted values, possibly data collected from a previous session, and newly generated TXL data from your system.

URL Response

This item is only informational. In order to accommodate a Load Balancer the Compliance Safety Net session URL will respond with a URL set in a configuration property plus the session details. If the URL returned only has the “/Session/{Workflow}/{key}” portion it is because CSi has not configured the endpointURL setting.

Configuration

A new, optional section configuration and property id has been added to support specifying a specific configuration set for the Compliance Safety Net session to run. These configuration settings include things like:

• Configuration options – available buttons, rules on locking/hiding data, some layout configuration, et cetera.
• Themes for the UI
• Any future configuration options added

We will work with you to set all of the configuration options and give that set a specific id which you can specify:

{
    ...
    "configurationId": { "id": "e210973d" }
}

This architecture we believe can lead to both good performance (caching of these settings) as well as flexibility. For example, some clients may need special configuration settings just for them. You can manage that by changing to the appropriate configuration and id whenever that Financial Institution is using the Compliance Safety Net.

Security Updates

The session id no longer needs to be specified. Instead, the Compliance Safety Net will generate a new, cryptographically secure session identifier. By using this generated id, calls to /api/session will no longer require the client license key both streamlining the api communication and improving security.

The session id will be included in the response when starting a session and can be used in this same structure to get data from a session.

{
    ...
    "session": { "id": "1234567" }
}

Test Cloud Compliance Safety Net Endpoints

These endpoints will be running this new version of the Compliance Safety Net starting April 11. Your existing test server with the current API will continue to run for the next 2 or 3 weeks.

• https://workflow.dev.compliancesystems.cloud
• https://workflow.test.compliancesystems.cloud
• https://workflow.prod.compliancesystems.cloud (coming soon)

Testing

Testing this API is as simple as composing (or modifying) a JSON string then posting it to one of the endpoints named above. It is possible that during testing/transitional moments, we may employ port 4515 or 4516. If these tests do not work, try changing the ports first.

For example, let’s do start a TFA session. Post to http://csi.test.workflow.compliancesystems.cloud:4516/api/startsession/tfa the following JSON:

{
    "client": {
        "licenseKey": "<<your license key goes here>>"
    },
    "notificationUrl": "https://objectrepository.test.compliancesystems.cloud/repositorywebservices/publish/simplicitypublish",
    "redirectUrl": "https://www.google.com",
    "configuration": {
        "id": "1dfb86bc-3995-4b1b-a89d"
    },
    "documentLibraryVersion": "2017.95.0",
    "transactionData": "<<your session data goes here>>"
}

The workflow server will reply to this with a JSON string that expands upon this:

{
  "url": "http://csi.test.workflow.compliancesystems.cloud:4516/Session/TFA/d151bd4b-4e8b-4b5c-8ad7-b1c7f00b2c0b",
  "messages": [
    "Success"
  ],
  "dclResponse": {
    "Id": "73c7ce85-6e2d-4cbc-b2d8-6686935e116e",
    "DataElements": [
      {
        "Key": "C_GNL_ADDR_INST_InstitutionState",
        "Value": "AK",
        "DocumentReferences": [
          "DD8000"
        ],
        "Trigger": false,
        "EvaluationStatus": 1,
        "Supplemental": false,
        "KeepValue": false,
        "ValidValues": [],
        "InvalidValues": [],
        "AssociatedId": null,
        "TransactionValuePath": "/TransactionValues/datavalues/datavalue [@name=\"C_GNL_ADDR_INST_InstitutionState\"]",
        "Calculated": false,
        "Note": "",
        "Source": 3,
        "Locked": false
      },
      ...
    ]
    ...
  }
}

Look for a Status object at the bottom of the response. Let’s hope you see SUCCESS.

Now, repeat the experiment sending instead JSON without the documentLibraryVersion. Let’s hope you see a helpful error response like this:

{
  "url": null,
  "messages": [
    "The request is missing a document library version. Please provide a version (documentLibraryVersion)."
  ],
  "dclResponse": null
}

Feel free to repeat this experiment with different JSON strings and different endpoints.