Introduction to the Custom Element for Account Setup Version 2
←
→
Page content transcription
If your browser does not render page correctly, please read the page content below
Introduction to the Custom
Element for Account Setup
Version 2
CEASdoc-2.10-20210923©2021 Morningstar. All Rights Reserved. AccountView Version: 2.10 Custom Element Version: 2.10 Document Version: CEASdoc-2.10-20210923 Document Issue Date: September 23, 2021 Technical Support: (866) 856-4951 Telephone: (781) 376-0801 Fax: (781) 376-8040 Web: byallaccounts.morningstar.com
Table of Contents
About this document................................................................................................... 1
Changes in this version ........................................................................................... 1
Custom Element for Account Setup............................................................................... 1
Known limitations ....................................................................................................... 1
User types ............................................................................................................. 1
Browser support ..................................................................................................... 1
Authentication ........................................................................................................... 2
Download and install the custom element ...................................................................... 2
Incorporate the custom element into your parent page ................................................... 2
Minimum example .................................................................................................. 3
Example setting common attributes .......................................................................... 3
Example for MaaS .................................................................................................. 4
Attributes .............................................................................................................. 5
Events .................................................................................................................. 8
Monitoring for events ........................................................................................ 11
Managing critical events in the workflow ............................................................. 11
badAuthentication .......................................................................................... 11
badConfiguration ............................................................................................ 11
internalError .................................................................................................. 11
userExit ........................................................................................................ 12
Managing informational events in the workflow .................................................... 12
dataChanged ................................................................................................. 12
dataChangedAsync ......................................................................................... 12
dataChangedAsyncAuthenticate ....................................................................... 12
userDeclinedAgreement .................................................................................. 12
Customizations to the user interface ........................................................................... 12
Applying the customizations .................................................................................. 13
Appendix A. Cumulative changes to the Custom Element .......................................... A-1
iIntroduction to the Custom Element for Account Setup About this document This document provides a preliminary overview of the custom element for Account Setup which is currently under development for Morningstar® ByAllAccountsSM (BAA) aggregation service. Changes in this version This document is evolving along with the Custom Element Version 2 (CEV2) which is currently at version 2.9. The changes in this are described in Appendix A Cumulative changes to the Custom Element along with important information about other recent changes. Custom Element for Account Setup Morningstar® ByAllAccountsSM aggregation service provides a W3C custom HTML element that implements the ByAllAccounts Consumer User Interface (CUI) account setup functionality for aggregation within another application without the use of iframes or browser tabs. The custom element (mstar-aggregation-consumer-accountsetup) enables account setup. The main features are selecting financial institutions (FI), entering FI credentials, discovering accounts, and aggregating the account data. The aggregated account data, which can include balance, holding, and transaction information from the FI, are available via other Morningstar ByAllAccounts applications and APIs. The custom element can be fully customized to integrate into your parent page, with customizations to terminology, styles, and features. This document describes the custom element, steps for embedding it in a web application, methods of authentication, and ways to customize it. Known limitations The capabilities, interfaces, and behaviors of the Account Setup custom element are subject to change as we make refinements based on customer feedback. This section describes the known limitations for the Account Setup custom element. User types The Account Setup custom element can only be used with BAA Investor users and those users must: ▪ have full Read-Write permission to their own data ▪ be Single Sign On (SSO) users ▪ be in a BAA Firm configured to use ConsumerUI V2.0. Note that a BAA Firm can be configured to use only one version of ConsumerUI. Browser support ▪ Chrome (including incognito mode), Firefox, Microsoft Edge, Safari, and Safari, Microsoft Edge, and Internet Explorer (IE) 11 are fully supported ByAllAccounts, Inc. 1 CEASdoc-2.10-20210923
Introduction to the Custom Element for Account Setup Authentication Authentication is handled by the parent page before it invokes the custom element; authentication can be accomplished via SSO (via DataConnect) or UIM JWT SSO. By default, the custom element makes service calls to www.byallaccounts.net. For MaaS, it makes service calls to https://www.us-api.morningstar.com/aggapi/v1. To allow these calls within the user’s browser, the parent page’s domain(s) must be configured in the custom element’s CORS whitelist within the ByAllAccounts service. Your Morningstar Implementation Manager will assist you with getting this configuration established. ▪ SSO – The parent page acquires values for jsessionid and csrftoken and must pass them to the custom element using the auth-context attribute. ▪ UIM JWT SSO – The parent page acquires the UIM JWT token and passes it to the custom element using the auth-context attribute. Although it provides many details not relevant to the custom element, the guide for AccountView SSO may provide some helpful information about SSO. http://www.byallaccounts.net/Manuals/Accountview/AccountView_SingleSignOn.pdf. Download and install the custom element Note: Ultimately the custom element will be distributed via the npm repository as a versioned npm package named mstar-aggregation-consumer-accountsetup. However, for now it is available as a packaged file (with a .tgz extension) from Morningstar ByAllAccounts. In the installation instructions below, use the name of the .tgz file you receive from ByAllAccounts. The mstar-aggregation-consumer-accountsetup custom element is built with Angular and can be used in frameworks such as React, and Vue, or in vanilla JS applications. Install the package by running the following command in your development environment: npm install .tgz After the npm package is installed, there is a mstar-aggregation-consumer-accountsetup folder under the node_modules directory. The folder contains: ▪ mstar-aggregation-consumer-accountsetup.js – Main JavaScript bundle for the Account Setup custom element. ▪ assets – Folder containing various configuration files and images for the custom element. ▪ package.json – File that describes the npm package. Depending on your build system/framework, there may be different steps to take to get Web Components loaded. In any case, the build system should ensure that the assets folder and the main JS file (mstar-aggregation-consumer-accountsetup.js) of the custom element are placed under the application’s distribution (/dist) folder from where it is being served. Incorporate the custom element into your parent page Import the necessary JavaScript files into your HTML page and create an instance of the mstar-aggregation-consumer-accountsetup tag element. Then add code to: ▪ Load the custom element. ▪ Instantiate the element in the page. ▪ Set attributes. Minimally set auth-context, which is required. If the route attribute is used, set it after the auth-context. That is, the user authentication must be set before the element can attempt the operation. ByAllAccounts, Inc. 2 CEASdoc-2.10-20210923
Introduction to the Custom Element for Account Setup
▪ Make the custom element visible in the page.
The following sections include:
▪ A simple code example showing the minimum requirements
▪ A more detailed example showing all the attributes
Additionally, consider how to handle the events described in Events on page 8.
Minimum example
At a minimum you must define the auth-context attribute for authentication, as shown here.
By default, the custom element starts with add accounts. To begin with editing credentials,
use the route attribute as shown in the next section.
mstarWebComp = document.createElement(“mstar-aggregation-consumer-accountsetup”);
mstarWebComp.setAttribute(“auth-context”, JSON.stringify(
{ jsessionId: “212764322EB9DBEBED880425DE3216EB.s1a”,
csrfToken: “DBC63BDE361C192B3CEF641B4C551DD8AC27B4A0276E91”
}));
content.appendChild(mstarWebComp);
Example setting common attributes
This example uses most available attributes for the custom element. It does not include the
URL attributes; those are shown in Example for MaaS, page 4.
Because the attributes that customize the user interface (ui-config-file, translate-file-path,
override-css-file, and custom-fonts) typically do not change during the lifetime of a parent
page, for simplicity they are defined first.
The other attributes (auth-context, route) may be reset any number of times during the life
of the parent page. In this example, hostname.com should be replaced with your host name
for those files.
For more information about the attributes, refer to Attributes, below.
mstarWebComp = document.createElement(“mstar-aggregation-consumer-accountsetup”);
mstarWebComp.setAttribute(“ui-config-file”, “https://hostname.com/customassets/config/ui-
config.json”);
mstarWebComp.setAttribute(“translate-file-path”, “https://hostname.com/customassets/i18n/”);
mstarWebComp.setAttribute(“override-css-file”,
“https://hostname.com/customassets/css/corporatestyle.css”);
mstarWebComp.setAttribute(“custom-fonts'”, “https://fonts.googleapis.com/css?family=Lobster”);
mstarWebComp.setAttribute(“auth-context”, JSON.stringify(
ByAllAccounts, Inc. 3 CEASdoc-2.10-20210923Introduction to the Custom Element for Account Setup
{ jsessionId: “212764322EB9DBEBED880425DE3216EB.s1a”,
csrfToken: “DBC63BDE361C192B3CEF641B4C551DD8AC27B4A0276E91”
}));
mstarWebComp.setAttribute(“route”, “/edit-credential;credentialId=21911”);
content.appendChild(mstarWebComp);
Example for MaaS
This example is based on the code in Example setting common attributes page 3, but
additionally shows the URL attributes for MaaS.
To use Morningstar as a Service (MaaS) with Custom Element you must set the rest-url
attribute. For non-production environments you must also set the corece-base-url attribute.
Consult with your BAA contact for non-production settings. Set those attributes near the
beginning because they do not change during the lifetime of a parent page.
This example assumes UIM JWT authentication, which is required for MaaS, so the auth-
context section shows a JWT token.
In this example, hostname.com should be replaced with your host name for those files.
mstarWebComp = document.createElement(“mstar-aggregation-consumer-accountsetup”);
mstarWebComp.setAttribute(“rest-url”, "https://www.us-api.morningstar.com/aggapi/v1");
mstarWebComp.setAttribute(“corece-base-url”, “https://www.byallaccounts.net");
mstarWebComp.setAttribute(“ui-config-file”, “https://hostname.com/customassets/config/ui-
config.json”);
mstarWebComp.setAttribute(“translate-file-path”, “https://hostname.com/customassets/i18n/”);
mstarWebComp.setAttribute(“override-css-file”,
“https://hostname.com/customassets/css/corporatestyle.css”);
mstarWebComp.setAttribute(“custom-fonts'”, “https://fonts.googleapis.com/css?family=Lobster”);
mstarWebComp.setAttribute(“auth-context”, JSON.stringify(
{ jwt:
"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI2M0Y2RjMzMS1FREMwLTRGMjktQjcxQS1
CNkMxMEFCMkYwQTgiLCJjdXN0b206dWltX3JvbGVzIjoiIiwiaXNzIjoiVUlNIiwiZXhwIjoxNTk0NzU0O
Tk3LCJpYXQiOjE1OTQ3NTEzOTd9.tBwuBrBIFhAwWmMxeM3Sqgq90dXaduZP4_GmCqLyGzJNcdj
WII9NfsJB3JUtjVHXpVS53n84RYwM1gFgI6gzHwCQmHNPSbjbqasNIwsYumv7FIUMJoqRdkeFkDIz
WdpHOf85nd5uRuwZXJs78pCJY3s-
EVdQ3j0qkc9JiV8vwlcf32K3sVbx6f772LApmMy3Mm8qaWaaIukdTZ_Xt4BfelYBMy1u7NgCB6hVAdE
SQ5A_svR94R7Nd7IaF-
TXD5gDYDO_sL6ccGC1UbDSFZCTA1MIeLj14bUwADfJ79HlpPmMQ_9F0mS5EiNpdFbI-
FIMXxT2MsdjG9Xdr8eqKFbN5Q"”
}));
mstarWebComp.setAttribute(“route”, “/edit-credential;credentialId=21911”);
content.appendChild(mstarWebComp);
ByAllAccounts, Inc. 4 CEASdoc-2.10-20210923Introduction to the Custom Element for Account Setup
Attributes
The following table describes the attributes for the custom element. The only required
attribute is auth-context. The only requirement for order of attributes is that if you use
route, you must set it after setting auth-context. Refer to the table below for details.
Any of these attributes can be set (and reset) at any time but ui-config-file, translate-file-
path, and override-css-file typically do not change during the lifetime of a parent page. An
example of when auth-context and route might be reset during the lifetime of a parent
would be handling of an error event. For information about events, see
Events page 8.
Attribute Req’d? Parameters and Description
auth-context
Yes Possible Parameters
Must contain one of:
▪ {jwt: }
▪ { jsessionId: , csrfToken: }
▪ {}
Description
The auth-context attribute is used for user authentication. It is required and
may be reset any number of times during the lifetime of the parent page.
For example, it would need to be reset after a timeout.
It must contain one of the possible parameters: UIM JWT token, the
jsessionId/csrfToken pair, or an empty object.
If the user was authenticated via UIM SSO, then the parent page acquires
the UIM JWT token and passes it to the custom element using the attribute.
{jwt: }
If the user was authenticated via SSO then the jsessionId and csrfToken
pair must be included, using the form:
{ jsessionId: , csrfToken: }
To prevent further use of the element by the user, use the empty value to
clear the authentication data from the element:
{}
Note that if more than one field contains a value, an auth-context will be
evaluated based on the precedence order 1) UIM JWT, 2)
jsessionId+csrfToken.
ByAllAccounts, Inc. 5 CEASdoc-2.10-20210923Introduction to the Custom Element for Account Setup
Attribute Req’d? Parameters and Description
rest-url
No* Possible Parameters
A full URL that to the REST backend. For MaaS, using the production
environment:
https://www.us-api.morningstar.com/aggapi/v1
* Only required if using MaaS or non-production environments
Description
Used for MaaS implementations, this attribute provides the full base URL to
REST back end.
If it is not defined, it defaults to (production):
https://www.byallaccounts.net/api/v1
corece-base-url
No** Possible Parameters
The attribute has the form protocol/server/port, though port is typically not
used. For example: https://www.byallaccounts.net/.
**Only required to be set if using MaaS in a non-production environment.
Description
This attribute identifies the base URL from where the core custom element
content is served and is currently only used for MaaS implementations.
This attribute only needs to be set for MaaS when used in an environment
other than production. When not set, it defaults to
https://www.byallaccounts.net/.
route
No Possible Parameters
▪ /add-account
▪ /edit-credential;credentialId=
▪ /discover-accounts;credentialId=
To allow the user to select which discovered accounts to save, set the
optional discoveredAccountSelect parameter to true, as shown:
▪ /add-account;discoveredAccountSelect=true
▪ /edit-credential;credentialId=;discoveredAccountSelect=true
▪ /discover-accounts;credentialId=;discoveredAccountSelect=true
To suppress the progress step, set the optional showProgressStep
parameter to false, as shown:
▪ /add-account;showProgressStep=false
▪ /edit-credential;credentialId=;showProgressStep=false
▪ /discover-accounts;credentialId=;showProgressStep=false
To launch the custom element directly into the FI Login page, use the fiId
parameter, as shown:
▪ /add-account;fiId=
ByAllAccounts, Inc. 6 CEASdoc-2.10-20210923Introduction to the Custom Element for Account Setup
Attribute Req’d? Parameters and Description
Description
The route attribute specifies the operation to be initiated, so:
▪ /add-account
will cause the first step (FI selection) to be displayed. This value is the
default.
▪ /edit-credential;credentialId=
where is the ByAllAccounts unique internal identifier for the
Account Credential to be edited. This route will display the form
containing the current login and password.
▪ /discover-accounts;credentialId=
where is the ByAllAccounts unique internal identifier for the
Account Credential for which accounts are to be discovered. This route
will display the account discovery step.
Use the optional parameter
discoveredAccountSelection=true
with each route for which you want to allow the user to select which
discovered accounts to save.
Use the optional parameter
showProgressStep=false
with each route for which you want to suppress the final progress step that
appears after a successful account add, edit, or discover.
Use the optional parameter
fiId=< BAA internal ID for the institution>
with /add-account to launch the custom element directly into the FI Login
page. This route will skip the FI selection step.
You can set any number of the optional parameters for each route. The
order is irrelevant.
The custom element defaults to the Add account page when it is first made
visible in the parent page. If you want to suppress the progress step for
that, you must explicitly set route and set showProgressStep=false.
The route attribute may be set any number of times during the life of the
parent page. For example, you would set a route to add an account then
could have another route to edit the account.
Note: If you set the route attribute, you must set it after the auth-context
attribute because user authentication must be set before the element can
attempt the operation. Otherwise, a badAuthentication event will occur.
translate-file-path
No Possible Parameters
The path to the custom en.json file.
Description
The translate-file-path attribute identifies the URL that is the path to the
en.json file that you created to provide custom terminology for certain text
and labels displayed by the custom element. The path is relative to the
base href of the deployed application.
ByAllAccounts, Inc. 7 CEASdoc-2.10-20210923Introduction to the Custom Element for Account Setup
Attribute Req’d? Parameters and Description
ui-config-file
No Possible Parameters
Path and file name to your custom user interface (UI) configuration file.
Description
The ui-config-file attribute identifies the URL that is the path to and the
name of the file that contains options for turning on/off UI sections in the
custom element. The path is relative to the base href of the deployed
application.
override-css-file
No Possible Parameters
The path and file name for your custom cascading style sheet (CSS) file.
Description
The override-css-file attribute identifies the URL that is the path to and file
name of a custom CSS file containing overrides to the default Morningstar
Design System (MDS) styles.
custom-fonts
No Possible Parameters
The path and name for your font definitions.
Description
The custom-fonts attribute identifies the URL that is the path to and file
name of a custom font definition file that will override to the default
Morningstar Design System (MDS) fonts.
Events
The mstar-aggregation-consumer-accountsetup custom element communicates with the
parent page using events caused by a trigger action. Some of these events are resolved by
the custom element but others must be managed by the parent page.
Critical events that must be monitored and managed by the parent page. These events
signal that the user has completed their work with the custom element or there is an error
that the custom element cannot resolve.
Other events that occur within the custom element are resolved by the custom element
itself. For example, the custom element handles any problems that occur when the
credentials entered by a user for a Financial Institution cannot be used to successfully
authenticate to that institution.
Monitoring for events on page 11 provides a code sample for monitoring or a specific event.
Managing critical events in the workflow on page 11 describes ways in which the parent
page may need to handle the critical events. Managing informational events in the workflow
on page 12 describes managing the informational events.
ByAllAccounts, Inc. 8 CEASdoc-2.10-20210923Introduction to the Custom Element for Account Setup
Trigger Name Event Detail Description
String
Critical Events
A request to badAuthentication “Unauthorized User’s authentication context is
server finds access” either not valid, the session
user’s timed out, or their
authentication authentication expired. The
context is not user will no longer be able to
valid (resulted interact with the element after
in a 401 a badAuthentication (401) event
Unauthorized) until the element receives
changes to the auth-context
attribute that provide valid
authentication data.
The user’s authentication could
end at any time. Whenever the
parent page receives a
badAuthentication event it must
re-authenticate and invoke a
setAttribute auth-context with
the refreshed header
information before the user can
proceed with the operation
they had started.
Custom badConfiguration “User not If the custom element is not
element is not licensed” licensed at initiation, there will
licensed be a blank area in the parent
page where the custom element
is expected. If the configuration
changes while the custom
element is in use the custom
element will be in a blocked
state and greyed out.
ByAllAccounts, Inc. 9 CEASdoc-2.10-20210923Introduction to the Custom Element for Account Setup
Trigger Name Event Detail Description
String
A request to internalError One of: An unexpected error occurred
the server “Forbidden during user’s interaction with
resulted in an access” the element. The parent page
error other “Service must remedy the problem and
than 401 or an unavailable” possibly display a message to
internal code “Unknown the user.
error occurred server error” Some causes include:
“Unknown Forbidden access: User does not
error” have the necessary permissions;
“Resource not user may have read only
found” permissions.
Service unavailable: Possibly an
intermittent service
interruption.
Resource not found: Could be a
misnamed path or file.
User completes userExit “User exit” User has 1) completed the
action and/or account add,
exits the 2) completed the account edit,
operation 3) canceled out of the workflow,
or 4) declined user agreement
Standard Events
User makes a dataChanged “Data changed” The user made a change to a
change to credential or account that may
credential or have resulted in synchronous
account changes to any or all of the
following: authentication status,
accounts linked to the
credential, financial data for
those accounts.
User initiates dataChangedAsync “Async Data The user initiates the service to
an aggregation change” run the asynchronous process
operation of composite “aggregate” which
can be discover/add/aggregate,
add/aggregate, or just
aggregate.
User initiates dataChangedAsyncAuthenticate “Async The user initiates an
an authenticate Authenticate authentication operation, which
operation Data change” causes the service to run the
asynchronous process of
attempting to authenticate.
User declines userDeclinedAgreement “User declined User did not accept the terms of
user agreement user the latest user agreement when
agreement” prompted.
ByAllAccounts, Inc. 10 CEASdoc-2.10-20210923Introduction to the Custom Element for Account Setup
Monitoring for events
This code sample shows how to listen for a specific event.
mstarWebcomp.addEventListener('userExit', function (event) {
console.log(' @@@@ userExit event is called. detail: ' + event.detail);
});
Managing critical events in the workflow
This section describes managing the critical trigger events listed in Events on page 8. These
critical events must be monitored and managed by the parent page.
badAuthentication
A badAuthentication event can be caused by:
▪ timeout: the user stops interacting with the custom element for a period of time and the
session for the auth-context times out.
▪ authentication ended: the authorized connection ended. For UIM SSO, it could mean the
JWT token is not valid or has expired.
For badAuthentication events, the parent page must reauthenticate the user and set a new
auth-context. Until the reauthentication happens, the custom element is in a blocked state
and is greyed out.
When the authentication is reestablished, the user may proceed from where they left off.
badConfiguration
A badConfiguration event is caused by an unlicensed the custom element.
If the custom element is not licensed at initiation, there will be a blank area in the parent
page where the custom element is expected. If the configuration changes while the custom
element is in use the custom element will be in a blocked state and greyed out as it is for a
badAuthentication event. The parent page needs to recognize that error and remedy the
problem.
internalError
The internalError event can happen for several reasons. For example, a “Resource not
found” error would occur if the parent page provided an invalid credential identifier when
requesting a route to edit-credential.
When an internalError occurs, the user interface for the custom element remains static. The
parent page needs to recognize that error and remedy the problem. The parent page can
pass a message to the user, describing the type of error.
ByAllAccounts, Inc. 11 CEASdoc-2.10-20210923Introduction to the Custom Element for Account Setup
userExit
The custom element sends the userExit event when the user exits the custom element, such
as by completing adding an account, completing editing an account, cancelling out of the
workflow, or declining the user agreement. The userExit event can also occur when an
account add or edit credential successfully completes and the progress step is suppressed.
Upon userExit, the parent page could hide the custom element or activate it again. To
activate it again, if the authorization context is still valid, the parent page can set the route
attribute to reopen the custom element at set point in the workflow.
Managing informational events in the workflow
This section describes managing the informational trigger events listed in Events on page 8.
These events that may be monitored by the parent page but are handled by the custom
element.
dataChanged
The dataChanged event lets the parent page know something has changed and they should
refresh any display of account, credential, position, and transaction data. The event is
emitted each time one of these data changes occurs, so the parent page could receive this
event multiple times during a single session of the custom element.
dataChangedAsync
The dataChangedAsync event lets the parent page know the user submitted a composite
“aggregate” that triggered the service to run the complex and long-running process
asynchronously. The composite "aggregate" can be discover/add/aggregate or just
aggregate. When the parent page receives this event it can poll for asynchronous activity
completion and then query the API to obtain the changed data.
dataChangedAsyncAuthenticate
The dataChangedAsyncAuthenticate event lets the parent page know that an authentication
was initiated. The asynchronous process can be complex and long-running. When the parent
page receives this event, it can poll for asynchronous activity completion and then query the
API to obtain the authentication status.
userDeclinedAgreement
A userDeclinedAgreement event occurs when a user does not accept the terms of a user
agreement when it is presented.
Customizations to the user interface
There are multiple types of customization you can optionally provide for the custom
element. You apply these customizations using the files provided in the assets folder.
▪ Terminology – the i18n/en.json translation file contains all the static text displayed on
pages, dialogs, and buttons within the interface. Edit this file to customize text and
terminology. Configure the element to user your custom terminology file by setting the
translate-file-path attribute.
▪ Styles – define an optional CSS file to override the default Morningstar Design System
(MDS) styles and adjust fonts, colors, and backgrounds for elements in the display.
Configure the element to use your custom CSS file by setting the override-css-file
attribute.
To use fonts other than the MDS Univers font, you can add a global entry like this to
your CSS file:
*{
font-family: YourFont, Verdana, sans-serif !important;
}
ByAllAccounts, Inc. 12 CEASdoc-2.10-20210923Introduction to the Custom Element for Account Setup
▪ Fonts – define an optional fonts file to override the default Morningstar Design System
(MDS) fonts for elements in the display. Configure the element to use your custom fonts
by setting the custom-fonts attribute. These new fonts are then available to be set using
the CSS file specified using the override-css-file attribute.
▪ Optional features – the config/ui-config.json contains options that enable you to turn
on/off UI features in the custom element. Configure the element to user your custom
configuration file by setting the ui-config-file attribute. Only a subset of the options
currently applies to the custom element. These options are:
"cui-fi-select": {
"fiLogosVisible": false,
"includeURLinSearch": false
}
Note that:
▪ "fiLogosVisible” - controls whether the popular institution logos are available in the FI
selection step
▪ "includeURLinSearch" - controls whether the FI URLs are included in the search criteria
when the user is searching for an institution
Applying the customizations
Use these instructions to customize terminology, styles, fonts, and optional features. If you
are using MaaS, use the MaaS domain www.us-api.morningstar.com
instead of www.byallaccounts.net.
1. Edit the files provided in the assets folder. These files and edits are described in
Customizations to the user interface on page 12.
2. Modify your web server to allow our origin (www.byallaccounts.net for production) to
access those files. We suggest the following:
▪ Header set Access-Control-Allow-Origin “www.byallaccounts.net”
▪ Header set Access-Control-Allow-Headers "Cache-Control,Content-
Type,Accept,Referer,User-Agent,Sec-Fetch-Dest"
▪ Header set Access-Control-Allow-Methods "GET,OPTIONS"
If this access is not allowed, then the custom element will not be able to access the
customization files and will have to use its own version of those files.
3. Set the appropriate attribute for each custom file. For attribute information see
Attributes, page 5.
ByAllAccounts, Inc. 13 CEASdoc-2.10-20210923Introduction to the Custom Element for Account Setup
Appendix A. Cumulative changes to the Custom Element
This appendix keeps a running list of released versions and a summary of the changes in
each version starting with version 1.11.
WARNING: When a release is required, you must use the latest version of the custom
element. If you do not, any project you have that uses the custom element will fail
because the new version has changes to the underlying API.
Date Version Required? Summary of Changes
December 5, 2019 1.11 No ▪ The custom element now supports
financial institution (FI) requests.
▪ The dataChangedAsync event is now
issued after credential authentication is
initiated. This response is in addition to
other situations, such as initiated
aggregation, that also cause
dataChangedAsync to be issued.
▪ Refinements were made so that
unanswered security questions are
handled more efficiently.
▪ The custom element is now built with
Morningstar Design System MDS 2.31.
▪ Document change December 9, 2019 to
add name of SAML cookie.
December 19, 1.12 No ▪ When authentication is initiated, the new
2019 event dataChangedAsyncAuthenticate is
initiated instead of dataChangedAsync
(BAPP-2277)
▪ When adding accounts for a financial
institution (FI) that does not support
account discovery, both account number
fields how have a “?” icon for the
account number instructions (BAPP-
2207)
▪ Users can now tab to the “?” info icon on
the FI Request page (BAPP-2230)
▪ A spacing issue was fixed on the
Financial Institution (FI) request form
(BAPP-2210)
▪ When a user clicks Exit during
aggregation with Security Questions and
Answers (SQAs), the Polling for status
now stops as expected (BAPP-1785)
▪ Document change January 9, 2020 to
add the cookie named amlbcookie
ByAllAccounts, Inc. A-1 CEASdoc-2.10-20210923Introduction to the Custom Element for Account Setup
Date Version Required? Summary of Changes
February 20, 2020 1.13 No ▪ The website URL is now searched in
addition to the user login URL (BAPP-
2436)
▪ Documentation change: the s1a suffix
was added to the jsessionid values in the
code examples
March 13, 2020 1.14 No To better help users identify the correct
financial institution during a financial
institution (FI) search, the home website
URL is now shown instead of the user
login URL if it is available. When
submitting credentials, both the website
URL and the user login URL are shown if
both are available (BAPP-2502)
May 14, 2020 2.1 No This release introduces Custom Element
Version 2 (CEV2) which replaces the
original Custom Element. In addition to
new underlying technology, changes
include:
▪ A new attribute for setting custom fonts.
▪ No longer set the required font faces
using a stylesheet reference.
▪ Now provide the hostname (URL) for the
customization files when setting the
attributes that customize the user
interface.
▪ To enable authentication service calls to
www.byallaccounts.net, the parent
page’s domain(s) must be configured in
the custom element’s CORS whitelist
within the ByAllAccounts service.
▪ The whitelist requirement now applies to
non-SAML SSO in addition to SAML SSO.
June 5, 2020 2.2 No * As of this release, by default new users
are presented with a user agreement. A
new userDeclinedAgreement event occurs
if the user does not accept the terms of
the user agreement and the userExit
event is triggered. The user agreement
feature can be disabled at the Firm level.
Disabling it at the Firm level disables it
globally for all ByAllAccounts services
including AccountView.
* Although this release is not required,
the userDeclinedAgreement event will not
be available unless you pick up the new
version.
June 25, 2020 2.3 No The changes in this release are internal
only and do not affect the user
experience.
ByAllAccounts, Inc. A-2 CEASdoc-2.10-20210923Introduction to the Custom Element for Account Setup
Date Version Required? Summary of Changes
July 17, 2020 2.4 No ▪ Safari, Microsoft Edge, and Internet
Explorer (IE) 11 are now fully supported
▪ When searching for a Financial
Institution, a “Cannot find institution…”
message no longer appears before the
results are displayed.
▪ The custom element is now built with
Angular 9.
▪ UIM SSO authentication is now
supported.
▪ Changes to support Morningstar as a
Service (MaaS), including the rest-url
and corece-base-url attributes.
August 14, 2020 2.5 No An error has been fixed that occurred
when the user selected a radio button
item while validating their identity at an
institution that requires In Session
Activation Codes (ISAC) (BAPP-3073)
October 29, 2020 2.6 No ▪ The browser web component registry is
now checked prior to registering the BAA
Custom Element component to avoid
duplicate registration requests.
▪ The zone.js dependency has been
removed for the BAA Web Component. It
was no longer needed and in some cases
was causing conflicts with parent pages.
▪ Web components polyfills were added to
support legacy Edge browsers.
▪ More checks were added to the route
attribute resolution logic and auth-
context to protect against invalid values.
November 19, 2.7 No A new badConfiguration event was added.
2020 It indicates that the custom element
license is not enabled for the firm.
December 10, 2.7 No Accessibility support changes were made,
2020 including placing focus on the first
interactable element when the custom
element launches or the page changes.
January 14, 2021 2.7 No Customer notifications for known
connectivity issues at financial institutions
are now displayed.
February 4, 2021 2.8 No ▪ Chrome Incognito mode is now
supported.
▪ Institution logo buttons now have
descriptive alt tags to support
accessibility according to Web Content
Accessibility Guidelines (WCAG).
▪ A loading issue when embedded for
Angular 10 was resolved.
ByAllAccounts, Inc. A-3 CEASdoc-2.10-20210923Introduction to the Custom Element for Account Setup
Date Version Required? Summary of Changes
February 25, 2021 2.8 No ▪ When creating an account, the account
authorization window for some financial
institutions would not open in a new tab
due to the browser's pop up blocker.
This issue has been fixed.
▪ Improvements have been made to
handling of error cases for editing
accounts, adding accounts, and editing
credentials at institutions that use OAuth
authorization.
▪ When connecting an account, the
progress bar now provides audible
indication of work in progress to
assistive technology users according to
Web Content Accessibility Guidelines
(WCAG) standards.
▪ In some cases, new users adding an
account would encounter an erroneous
invalid input error. This issue has been
fixed.
March 18, 2021 2.8 No When a user clicks the Done button while
in the progress page, the userExit event is
now sent for the parent page to manage
the workflow, rather than returning to the
FI selection page.
April 8, 2021 2.8 No Now when a user selects Cancel while in
the process of logging into a Financial
Institution, aggregating, etc. the progress
page or main view will no longer continue
to show the 'Connecting..." status.
April 29, 2021 2.9 No New parameter fiId for the add-account
route, enables a direct route to the
financial institution (FI) login page,
bypassing the FI selection page.
June 10, 2021 2.9 No ▪ Users who do not have an email address
now do not see the option to request an
FI.
▪ The styling of the text when requesting a
new financial institution (FI) is now
consistent with the rest of the interface.
▪ Documentation change: a code sample
for event listener was added on page 11.
ByAllAccounts, Inc. A-4 CEASdoc-2.10-20210923Introduction to the Custom Element for Account Setup
Date Version Required? Summary of Changes
July 2, 2021 2.10 No ▪ SAML is no longer supported, so
references to SAML SSO have been
removed.
▪ The custom element is now built with
Angular 12.
▪ There are several new error messages
for OAuth authorization cases.
▪ The message type
cannotConnectOauthAcctNotAuthorized,
with the message “Cannot connect.
Account is not authorized.” appears
when an account is missing data needed
to identify it, such as AccountNumber2.
▪ The icon for Fidelity Investments seen
when adding an account now directs to
Fidelity.com – Quicken.
July 22, 2021 2.10 No Two of the popular institution icons seen when
adding an account have been swapped for
other financial institutions. Chase and Wells
Fargo have been removed and replaced by
E*TRADE (Investment) and T. Rowe Price
(Investment).
September 23, 2021 2.10 No ▪ A new /discover-
accounts;credentialId= parameter
was added to the route attribute. The
description for the dataChangedAsync trigger
was updated.
▪ When entering the financial institution
password, the last typed character of the
password is visible for a brief time, and there
is a show/hide option for a newly entered
password.
▪ In some cases, authentication during account
setup was taking extra time. This condition
has been improved.
ByAllAccounts, Inc. A-5 CEASdoc-2.10-20210923You can also read
