@finagraph/strongbox-finconnect-react v0.1.83

Overview

This package contains a React Component (Widget) that makes it simple for a consuming application to use Finagraph Strongbox for connecting to a customer's accounting system and securely importing information from multiple systems into a normalized model. You can then benefit from the strong analysis and SDK provided by Strongbox for interacting with this data.

This document assumes and in fact requires some familiarity with the Finagraph Strongbox SDK (SDK). To fully use the Widget, you will need to register as an SDK customer and be in possession of a Client ID and Secret that allow the Widget to interact with the SDK on your behalf.

More information about the SDK can be found in Strongbox Developer Portal

Getting started

This document assumes that you have the Strongbox Sample Application that demonstrates using the Strongbox React Widget. In addition to simply illustrating how to use the Widget, the Sample Application is fully documented in comments and clearly demonstrates how to use the SDK to generate security tokens required to use the Widget.

This is by far the easiest way to get started using the Widget. If you don't already have the Sample Application, you can download it here.

Therefore, this document focuses primarily on a few details specific to using the Widget. These are:

• Using general options that control what financial data is imported.
• Customizing the accounting packages that are available to the end user.
• Theming or changing the appearance of the Widget such as which colors are used.
• Content Customization or changing the content of descriptions to be more specific to your company.

As with the basic use of the Widget, the easiest way to understand theming and content customization is to use the Sample Application. The Sample Application includes a comment containing a sample theme and customized content that you can experiment with to see how the Widget is affected.

Using the Widget

Install the Widget into your project:

npm install @finagraph/strongbox-finconnect-react

import Strongbox from '@finagraph/strongbox-finconnect-react';

Finally add it to your application's render function:

    <Strongbox
        accessToken={<access token>}
        disabled={<boolean>}
        language={'<language code'>}
        orgId={'<Provide an ID that uniquely identifies the customer/business to you>'}
        orgName={'<Provide a name that you will recognize>'}
        onJobCreated={<function that receives a financialRecordId that identifies the job for importing financials and generating a spreadsheet>}
        partnerName={<Consumer's (i.e. your) organization name.) For example, 'XYZ Bank'>}
        showConnectionDialog={<boolean>}
        financialImportOptions={see below}
    >
        {(props) => {
            return undefined;
        }}
    </Strongbox>

FinancialImportOptions

type FinancialImportOptions = {       
	mostRecentDate?: {
		month: number;
		day: number;
		year: number;
	};
	anonymizeCustomersAndVendors: boolean;
	financialStatementsPeriod?: {
		reportingPeriod: "Months" | "FiscalQuarters" | "FiscalYears";
		numberOfPeriods: number;
	},
	transactionsPeriod?: {
		reportingPeriod: "Months" | "FiscalQuarters" | "FiscalYears";
		numberOfPeriods: number;
	},
	payablesPeriod?: {
		reportingPeriod: "Months" | "FiscalQuarters" | "FiscalYears";
		numberOfPeriods: number;
	},
	receivablesPeriod?: {
		reportingPeriod: "Months" | "FiscalQuarters" | "FiscalYears";
		numberOfPeriods: number;
	}

Customizing available accounting packages

By default, the Strongbox Widget will show all the accounting packages it is capable of showing when the user chooses to connect with their accounting system. Further, for some packages that have multiple 'types' a small descriptor is shown under the package icon that describes more specifically which package it applies to. An example would be QuickBooks where the user may have either QuickBooks Online or QuickBooks Desktop.

The packages displayed and the descriptor that shows under the icons are configured through the accountingPackages property.

If no value is provided, all available accounting packages are shown using their default descriptors.

Use the accountingPackages property to configure which accounting packages are shown to the user and what descriptors are used. accountingPackages is an array of JSON objects. For Typescript users, the elements are of type AccountingPackageToShow. The full definition is as follows:

type AccountingPackageToShow = {
    package: SupportedAccountingPackages;
    descriptor?: string;
}

Using the 'theme' property

The Strongbox Widget has an optional property called theme. This is how you pass settings that will change the appearance of the Widget.

The theme property is a JSON object. The type for theme is exported from the module as Theme. The full definition is as follows:

type Theme = {
    palette?: ThemePalette;
    font?: ThemeFont;
    container?: ThemeContainer;
    controls?: ThemeControls;
}

ThemePalette

Controls what colors are used for various aspects of the Widget.

type ThemePalette = {
    windowBackground?: string;
    borrowerInteractionBackground?: string;
    controlBackground?: string;
    controlForeground?: string;
    progressBarForeground?: string;
    modalBackground?: string;
    modalText?: string;
    modalTitle?: string;
}

ThemeFont

Defines the appearance of fonts in the Widget.

type ThemeFont = {
    family?: string;
    size?: string;
    controlSize?: string;
    size_h1?: string;
    weight?: string;
    controlWeight?: string;
    weight_h1?: string;
    modalFamily?: string;
    modalTitleSize?: string;
    modalTitleWeight?: string;
    modalRegularSize?: string;
    modalRegularWeight?: string;
    modalSecuritySize?: string;
    modalSecurityWeight?: string;
}

ThemeContainer

Defines aspects of the appearance of the region that contains the Widget when it opens up after the user has pressed the button to link an accounting package.

type ThemeContainer = {
    paddingLeft?: string;
    paddingTop?: string;
    paddingBottom?: string;
    paddingRight?: string;
    height?: string;
    width?: string;
}

ThemeControls

Defines aspects of the user input elements displayed to the user in the Widget such as buttons and progress bars.

type ThemeControls = {
    borderRadius?: string;
}

Content Customization

You can customize most of the content that appears during the various steps of the Widget. This would allow you to change the messsaging to be more specific to your organization for instance.

A sample of using the Widget earlier in this document is:

<Strongbox
    orgId={'<Provide an ID that uniquely identifies the end user to you>'}
    orgName={'<Provide a name that you will recognize>'}
    accessToken={<access token>}
>
    {(props) => {
        return undefined;
    }}
</Strongbox>

Content customization is accomplished by replacing the child block and returning something other than undefined. When undefined is returned default content is used. So for example if you replace it with:

{(props) => {
        return (<p>I like pie.</p>);
}}

The result would be that you would see "I like pie" on every step. It isn't likely that it would be tremendously useful to have the same content displayed on every step so there is a mechanism for handling this. The type definitions for props are as follows:

enum BorrowerSteps {
    choosePackage,
    configureAccounting,
    progress,
    congratulations,
}

type SBLinkAccountingPackageChildProps = {
    step: BorrowerSteps;
    pctComplete?: number;
};

As you might expect step is the current step the user is on. pctComplete is valid when step is equal to progress. This helps you customize the content shown while the progress bar is moving. A more realistic example for replacing this content would be:

{(props) => {
    if (props.step === BorrowerSteps.choosePackage) {
        return (
            <div style={{ marginTop: '15px' }}>
                <p>Submitting your documents to us electronically will</p>
                <p>really make it faster and easier to process your application</p>
            </div>
        );
    } else if (props.step === BorrowerSteps.progress) {
        return (
            <div>
                <p>Setting up a secure connection to our servers</p>
                <p>We'll be getting back to you shortly</p>
            </div>
        )
    } else if (props.step === BorrowerSteps.congratulations) {
        return (
            <p>You're all done.  Thank you for considering us.</p>
        )
    } else {
        return undefined;
    }
}}