7. Manage Critical Events
Overview
The Account Summary component (mstar-aggregation-consumer-accountsummary) and the Account Linking component (mstar-aggregation-consumer-accountsetup) can issue two types of events, which are caused by a trigger action.
How an event is resolved depends on the type of event:
- Critical events must be monitored for and managed by the parent page. Typically, these events signal that there is an error that the component cannot resolve or that the user has completed their work. Additionally, the Account Summary component can issue an event that signals there is a parameter value that the parent page must pass to Account Linking.
- Standard (informational) events occur in Account Linking only and provide information for the parent page. Informational events may be monitored, but are managed by the component. For example, Account Linking handles any problems that occur when the credentials entered for a financial institution cannot be used to successfully authenticate at that institution.
The Monitoring for events section provides a code sample for monitoring for a specific event. The Managing critical events section describes ways in which the parent page may need to handle the critical events. The Managing standard events in Account Linking section describes managing the informational events.
Events
Critical Event Only in Account Summary
The following critical event only occurs in Account Summary.
| Trigger | Name | Event Detail String | Description |
|---|---|---|---|
| A user action in the Account Summary component requires the parent page to provide route information to the Account Linking component | accountSetup | A string to pass as a parameter value to Account Linking on the route attribute. | This event is triggered by a user action in Account Summary. The parent page must pass the resulting event detail string as the parameter on the route parameter for Account Linking to tell Account Linking what workflow to open. Examples that can cause the event to fire include when user clicks: - "Link More Accounts" button. - "Connect Accounts" menu option and selects "Enter New Credential" button in the dialog. - "Connect Accounts" menu option and selects "Link More Accounts" button in the dialog. - "Re-Authenticate" menu action. - The edit pending request action. - The account name. For information about managing this event, refer to accountSetup. |
Critical Events in Both Components
| Trigger | Name | Event Detail String | Description |
|---|---|---|---|
| A request to the server finds user's authentication context is not valid (resulted in a 401 Unauthorized) | badAuthentication | "Unauthorized access" | User's authentication context is either not valid, the session timed out, or their authentication expired. The user will no longer be able to interact with the component after a badAuthentication (401) event until the component 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. Note: When authentication fails for either component, it is recommended that authentication is reestablished for both. For information about managing this event, refer to badAuthentication. |
| Component is not licensed | badConfiguration | "User not licensed" | If the component is not licensed at initiation, there will be a blank area in the parent page where the component is expected. If the configuration changes while the component is in use, the component will be in a blocked state and greyed out on the parent page. For information about managing this event, refer to badConfiguration. |
| A request to the server resulted in an error other than 401 or an internal code error occurred | internalError | One of: "Forbidden access" "Service unavailable" "Unknown server error" "Unknown error""Resource not found" | An unexpected error occurred during the user's interaction with the component. The parent page must remedy the problem and possibly display a message to the user. Some causes include: - Forbidden access: User does not have the necessary permissions; user may have read only permissions. - Service unavailable: Possibly an intermittent service interruption. - Resource not found: Could be a misnamed path or file. For information about managing this event, refer internalError. |
Critical Event Only in Account Linking
The following critical event must be monitored in Account Linking.
| Trigger | Name | Event Detail String | Description |
|---|---|---|---|
| User completes action and/or exits the operation | userExit | "User exit" | User has done one of the following: completed the account add, completed the account edit, canceled out of the workflow, or declined the user agreement. For information about managing this event, refer to userExit. |
Standard Events in Account Linking
The following standard events can occur in Account Linking. These events that may be monitored by the parent page but are handled by the Account Linking component.
| Trigger | Name | Event Detail String | Description |
|---|---|---|---|
| User makes a change to credential or account | dataChanged | "Data changed" | User makes a change to a credential or account that may result in synchronous changes to any or all of the following: authentication status, accounts linked to the credential, and/or financial data for those accounts. |
| User initiates an aggregation operation | dataChangedAsync | "Async Data change" | User initiates the service to run the asynchronous process of composite "aggregate" which can be discover/add/aggregate, add/aggregate, or just aggregate. |
| User initiates an authenticate operation | dataChangedAsyncAuthenticate | "Async Authenticate Data change" | User initiates an authentication operation, which causes the service to run the asynchronous process of attempting to authenticate. |
| User declines user agreement | userDeclinedAgreement | "User declined user agreement" | User does not accept the terms of the latest user agreement when prompted. |
Monitoring for Events
This code sample shows how to listen for a specific event. Both components must be monitored for critical events.
mstarWebcomp.addEventListener('userExit', function (event) {
console.log(' @@@@ userExit event is called. detail: ' + event.detail);
});
Managing Critical Events
This section describes managing the critical trigger events listed in Events. These critical events must be monitored and managed by the parent page.
Standard events, such as dataChanged _and _userDeclinedAgreement, are resolved by Account Linking. For details about standard events refer to Managing standard events in Account Linking.
accountSetup
Applies to Account Summary only.
Some user actions in the Account Summary component cause it to fire its _accountSetup _ event which the Account Linking component should respond to. To effect that response, the parent page must monitor for that event and provide the glue logic to handle it. The parent page must pass event detail string of the _accountSetup _ event as the parameter on the route attribute when invoking the Account Linking component to tell the Account Linking component where in its workflow to open.
badAuthentication
A badAuthentication event can be caused by:
- timeout: the user stops interacting with a component for a period of time and the session for the auth-context times out.
- authentication ended: the authorized connection ended.
For badAuthentication _events, the parent page must reauthenticate the user and set a new _auth-context. Until the reauthentication happens, the component is in a blocked state and is greyed out.
When the authentication is reestablished, the user may proceed from where they left off.
Note: When authentication fails for either component, reestablish it for both.
badConfiguration
A badConfiguration event is caused by an unlicensed component.
If the component is not licensed at initiation, there will be a blank area in the parent page where the component is expected. If the configuration changes while the component is in use, the component 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 event occurs, the user interface for the component 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.
userExit
Applies to Account Linking only.
A component sends the userExit event when the user exits it, such as by completing adding an account, completing editing an account, canceling out of the workflow, or declining the user agreement.
Upon an userExit event, the parent page could hide Account Linking 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 Account Linking at a set point in the workflow.
Managing Standard Events in Account Linking
These events apply to the Account Linking component only.
This section describes managing the standard (informational) trigger events listed in Events.
These events that may be monitored by the parent page but are handled by the Account Linking component. You may want to monitor standard events to update your own back end.
dataChanged
The dataChanged event lets the parent page know something has changed in Account Linking. The parent page 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 Account Linking component.
dataChangedAsync
The dataChangedAsync event lets the parent page know the user submitted a composite “aggregate” in Account Linking 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 should 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 in Account Linking. 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 in Account Linking.
Updated 11 months ago