Bank Direct Connect Implementation Guide

This guide is meant to provide an understanding of the general Accounting Seed Bank Direct Connect (BDC) Structure and to suggest techniques for implementing new interfaces for pulling bank transactions via Http protocol.

Current Implementations

There are currently 3 ways to acquire transactions via a BDC interface: Yodlee, Plaid, and via file upload. The code has been structured to be repeatable for different future interfaces.

Purpose of a BDC interface

The primary goal of a BDC interface is to retrieve transactions from a banking service and represent those transactions in a ledger. Functions that do not directly retrieve transaction information are used to either display information in the interface or extract extra information to be added to transactions.

Description Of Work

To implement a new BDC Interface, the user will need to implement 4 interfaces. The abstract classes for these interfaces are listed below.

AbstractBDCConnector - The connector’s purpose is to retrieve information from an external banking service. Generally, these functions will return HttpResponses to later be parsed.

AbstractBDCConverter- The converter takes http responses that were retrieved by the connector and converts them into Account Seed’s custom defined objects. The list of responses gives flexibility to functions that may require responses from multiple calls, such as retrieving accounts before transactions can be retrieved. These objects are generally named as BDCObjectName, such as BDCAccount or BDCTransaction. Converting the responses into a common structure allows for easy translation into Salesforce objects that are eventually represented in a ledger.

AbstractBDCTransactionBulk - This implementation’s purpose is to retrieve any number of Transactions. Given the number of possible transactions and limits that may exist for the number of transaction pulled from an api or the number of records that can be created in Salesforce, it it strongly recommended that this function uses some sort of asynchronous process to pull transactions in batches, such as a chained queueable. This implementation (or the classes called by this implementation) will almost certainly use the transaction code in the both the connector and converter to retrieve and convert those transactions. Only the startTransacitonProcess function should be overloaded, and the other global functions in the class are meant to be used by this function to perform some common operations in the inherited class.

AbstractBDCRouter - The Router is simply an object that chooses the correct implementation of the other interfaces. Implementing this interface is easy and each function should simply return an instance of the above interfaces.

Supporting Classes and Structure

All other global classes exposed are designed to support the 4 implementations above. This section gives context on these classes, but implementors should not need to modify these classes. They can be grouped into the following distinctions. For more detailed information on the specific classes, see the documentation. For a broad view of the object structure see the BDC ERD Class diagram.

The ERD Class Diagram

The ERD class diagram shows the structure of a BDC implementation. The classes are loosely arranged from left to right in a way that indicates order of operation. Inputs to services (BDCOptions) are generally shown on the left and outputs (BDCServiceResult) on the right. The top to bottom order loosely represents which classes are high level (top) and the lower functions that these classes call are toward the bottom.

Accounting Seed Bank Direct Connect ERD

Classes

BDCServiceOptions was created to allow flexibility in customizing how a process behaves for an implementation. For example, when implementing the getTransactions function in the BDCConnector, the implementer can choose the date range. BDCServiceResult can hold any objects returned by the api and converted by the converter, as well as any errors the process created.

BDCServiceOptions

BDCServiceResult

BDCDataModel

BDCServiceResult.BDCError

Intermediary BDC Objects

These objects are returned by the converter and aid in converting data into Salesforce objects or displaying information on the BDC interface.

BDCTransaction

BDCAccount

BDCFinancialInstitution

BDCFinancialInstitutionIdentity

High level classes that structure the implementations

These classes tie all the classes together into a structure. The BDCService represents the highest level entry points to run an implementation. Notice that a binding is often passed to these functions to access any implementation. Furthermore, the BDCService class contains high level errors that will likely be useful in any implementation and provide a consistent way to report common errors.

BDCService

Even though the BDCRouter is technically an implementation and not a support class, it is listed as a high level class to indicate its purpose of linking the BDCService to the implementation classes.

Implementation of:

AbstractBDCConnector

AbstractBDCConverter

AbstractBDCRouter

AbstractBDCTransactionBulk

Debits and Credits in BDC

This section describes how bank transaction data is retrieved from an aggregation provider, saved as bank transaction records in Salesforce, and then displayed on the Bank Direct Connect user interface.

The Base Type field on the Bank Transaction object represents how the transaction appears on the Financial Institution Account (FIA), in other words, from the FIA's point of view. There are two types of FIAs - a depository account (such as a checking account) and a liability account (such as a credit card account). When a checking account is increased, from the FIA's point of view it is credited. On the other hand, when a credit card liability account is increased, from the FIA's point of view it is debited.

Important! When implementing another aggregation provider/service, you will need to scrutinize the bank transaction data coming in and based on the type of account (depository or credit card) make the determination of what the Base Type should be set to.

If the FIA type is:	And the FIA transaction represents an:	Then set the Base Type to:
Depository	Increase	Credit
Depository	Decrease	Debit
Liability	Increase	Debit
Liability	Decrease	Credit

Furthermore, you will need to determine whether the amounts being retrieved from the FIA are positive or negative, set the Base Type accordingly, and set the amounts to positive.

Once imported into Bank Direct Connect, the bank transaction amounts are displayed in the user interface based on the Base Type field:

Depository account increases (Credit) are shown as positive amounts and decreases (Debit) as negative.

Conversely for a Credit card account, increases (Debit) are shown as negative amounts and decreases (Credit) as positive.

BDC Activation

Active BDC providers are controlled by a Salesforce protected custom setting. Please contact Accounting Seed support and provide a BDC service/provider name and the name of the class that extends the AbstractBDCRouter class. With proper access, the support team will setup the appropriate custom setting and the new BDC provider will be visible in the Accounting Seed Bank Direct Connect component.