Account Details Adapter Extension Tutorial
The Account Details adapter provides a way of loading Host Account Data Elements (HADEs) for accounts, such as Available Balance and
Current Balance. These values are shown on the account tile on the dashboard, as well as within the account details page. This adapter does
not provide the list of accounts for a user (AccountList), or the transactions for an account (AccountHistory).
Prerequisites
Adapters can be applied to all accounts, or only to a subset of accounts. In this case, we only want our adapter to be used for our special accounts.
We achieve this by creating a custom ProductType, Product, and HostAccount.
First, we create our
ProductType:$ q2 db add_product_type 'Lucky Stars' Y D 'LuckyStars' --is_external # | | | | | # | | | | This is an account not found on the core # | | | The short name that HQ will use for identity # | | This is a deposit account # | APY # Product Type Name
This
ProductTypewill also need some configurations so HQ knows which HADEs to expect$ q2 db add_system_property_data HadeToDisplay1 1 --product_type_name 'Lucky Stars' # | | # | HostAccountDataElement for 'Available Balance' # First slot on the account tile $ q2 db add_system_property_data HadeToDisplay2 4 --product_type_name 'Lucky Stars' # | | # | HostAccountDataElement for 'Current Balance' # Second slot on the account tile $ q2 invalidate_hq_cache --type SystemProperties
Next, we create our
Product:$ q2 db add_product 'Lucky Stars' 'LuckyStars' 'All Tran Codes' 'Lucky Stars' C # | | | | | # | | | | HQ code for Checking # | | | Product Type name from above # | | This product supports all tran codes # | The short name that HQ will use for identity # Product Name
(Optional) For the account tile to also function as an SSO, first make sure to mark
--is_externalas True inProductTypeand link vendor to this product as below:$ q2 db link_vendor_to_product 'ssoforclickable' 12 1 # | | | # | | User ID # | Product ID # | # Vendor Name
Finally, let’s create a new
HostAccount, tied to ourProduct, set as external, with no hardcoded HADEs, linked to our login, with view-only rights:$ q2 add_new_account Querying products from database Select Product 1) External Savings 2) Q2 BUSINESS CHECKING 3) Q2 BASIC CHECKING 4) Q2 VALUE CHECKING 5) Q2 PREMIER CHECKING 6) Q2 ULTIMATE CHECKING 7) Q2 BUSINESS SAVINGS 8) Q2 BASIC CHECKING 9) Q2 VALUE SAVINGS 10) Q2 PREMIER SAVINGS 11) Q2 ULTIMATE SAVINGS 12) Q2 6 MONTH SHARE CERTIFICATE Page 1 of 2. Select 'n' for next page. Please make a selection and press Return: n Select Product 1) Q2 12 MONTH SHARE CERTIFICATE 2) Q2 18 MONTH SHARE CERTIFICATE 3) Q2 24 MONTH SHARE CERTIFICATE 4) Q2 36 MONTH SHARE CERTIFICATE 5) Q2 LINE OF CREDIT 6) Q2 HELOC 7) Q2 NEW VEHICLE 8) Q2 USED VEHICLE 9) Q2 STUDENT LOAN 10) Q2 BASIC CREDIT CARD 11) Q2 PREMIER CREDIT CARD 12) Lucky Stars <--------- Page 2 of 2. Select 'p' for previous page. Please make a selection and press Return: 12 Lucky Stars Account Number Internal? For Credit Unions, this is usually a share number (S01 or L02). For Banks this is typically a full account number: 1234 Account Number External? For Credit Unions, this is usually a full MICR number. For Banks, This is a full account number like the internal number: 1234 CIF? For Credit Unions, this is usually a member number. For Banks, this is typically the customer number: 5678 Account Description? This will be what shows up on the landing page: My Lucky Stars Is External Account? : [y/N] y <--------- New Account created with ID: 5084 Do you want to add HADEs to this account? [Y/n] n <--------- Do you want to link this account now? [Y/n] <--------- What login do you want to link this account to?: retail0 <--------- What account access do you want to grant? [7]: 2 <--------- Successfully linked acount
Log in UUX (with the user
retail0if you followed the above steps). On the dashboard, you should see the new account:
If you linked Vendor to the Product. The SSO extension can be opened with the clickable
Externalbutton.
Create the Extension
Now that the prerequisites are out of the way, we can get working on your extension itself. Thankfully, there’s not much to it!
Generate the boilerplate using the
q2 create_extensioncommand:$ q2 create_extension New Extension Name: LuckyStarsAdapter What type of extension are you creating? 1) Online (default) 2) SSO (Third Party Integration) 3) Ardent (API) 4) Q2Console (Backoffice) 5) Central (Legacy Backoffice) 6) Adapter <--------- 7) Audit Action 8) Custom Health Check 9) Message Bus 10) Caliper API Custom Endpoint 11) Base Extension Please make a selection and press Return [1]: 6 Adapter Select adapter type to generate 1) Account Details <-------- 2) Authentication Token 3) Check Image 4) Domestic Wire 5) Deposit Item Image 6) FX Rate 7) Instant Payments 8) International Wire 9) Remote Deposit 10) Statement Image Please make a selection and press Return: 5 Account Details
Register the adapter for account details in the stack:
Get the
ProductTypeID$ q2 db get_product_types ProductTypeID ProductTypeName HydraProductTypeCode HostProductTypeCode 4 External Deposit Accounts D DExt 5 Q2 Checking D Q2checking 6 Q2 Savings D Q2savings 7 Q2 Certificate D Q2certificate 8 Q2 Loan L Q2loan 9 Q2 Credit Card C Q2creditcard 18 <---- Lucky Stars D LuckyStars
Install the adapter, tied to our
ProductTypeID$ q2 install Which Extension would you like to install? 1) LuckyStarsAdapter <--------- Please make a selection and press Return: 1 LuckyStarsAdapter Please provide a description for this AccountDetails adapter. [SDK AccountDetails Adapter: LuckyStarsAdapter]: If your adapter has a Product Type ID, please provide it, or leave blank for NULL: 18 <--------- Successfully installed adapter at 39.
By default, your extension is generated with a generic response:
async def get_account_details(self, account_details_request: AccountDetailsRequest) -> AccountDetails: '''Using the information provided in `account_details_request` param, return AccountDetails''' return AccountDetails( account_details=[ AccountDetail( name='AvailBal', value='1000.12' ), AccountDetail( name='CurBal', value='2000.34' ) ] )
There’s no need to change that for the moment. Let’s see how it works in the next step.
Testing the Extension
From the code above, we should be see a successful flow right away, and we’ll know it worked if we see Available Balance: $1,000.12, Current
Balance $2,000.34.
Let’s try it out! Boot up your server:
$ q2 run
Log in UUX. On the dashboard, you should see the new account, along with it’s details:
You should see logs in your locally running server. Here’s an example:
2024-07-17T09:01:45.930 tornado.access INFO 200 b9ba67d7accc4083a7373656e62b5418 POST /LuckyStarsAdapter (::1) 3.14ms
Summary
And that’s it! Try playing around with the response. You can change the values of the HADEs returned, return different HADEs, or even create your own custom named HADEs. Remember, all we’ve done with this extension is return static values. What is still up to you is actually retrieving the correct values based on the account information.