7. Manage Critical Events

Overview

The Account Summary component (mstar-aggregation-consumer-accountsummary) and the Account Linking component (mstar-aggregation-consumer-accountsetup) issue events in response to user actions and system conditions. Events fall into two categories:

❗️
Critical events
Must be monitored and managed by the parent page. They signal errors the component cannot resolve, completion of user work, or a parameter that must be passed between components.

ℹ️
Standard (informational) events
Occur in Account Linking only. Handled by the component, but the parent page may monitor them to keep its back-end in sync.

Instructions

The parent page must monitor each critical event and provide a handler that responds appropriately. The required handler behavior is described in the event detail sections below.

Standard events are handled by Account Linking. The parent page may optionally monitor them — for example, to keep its own back-end in sync.

1. Set up monitoring for events

Both components must be monitored for critical events.

View the event listener code sample

mstarWebcomp.addEventListener('userExit', function (event) {
  console.log(' @@@@ userExit event is called. detail: ' + event.detail);
});

2. Implement handlers for events

The components issue nine events that the parent page can listen for. Five are critical and require a handler to be implemented; four are standard and informational, and the parent page may optionally handle them to keep its own state in sync.

Events summary

The summary table below lists every event at a glance.

Name	Type	Scope	Description
`accountSetup`	Critical	Account Summary	A user action requires the parent page to pass route information to Account Linking.
`badAuthentication`	Critical	Both components	The user's authentication context is no longer valid.
`badConfiguration`	Critical	Both components	The component is not licensed.
`internalError`	Critical	Both components	A server error or internal code error occurred.
`userExit`	Critical	Account Linking	The user completed an action and/or exited the workflow.
`dataChanged`	Standard	Account Linking	A change was made to a credential or account.
`dataChangedAsync`	Standard	Account Linking	An aggregation operation was initiated.
`dataChangedAsyncAuthenticate`	Standard	Account Linking	An authentication operation was initiated.
`userDeclinedAgreement`	Standard	Account Linking	The user did not accept the terms of the user agreement.

Event details

Each event below describes what it signals, what triggers it, and what the parent page must do in response. Critical events require handler implementation; standard events are informational and the handler is optional.

accountSetup

Required handler behavior: Pass the event detail string as the parameter on the route attribute when invoking Account Linking, telling it where in its workflow to open.

Type: Critical
Scope: Account Summary only
Trigger: A user action in Account Summary that requires the parent page to provide route information to Account Linking
Event detail string: A string to pass as a parameter value to Account Linking on the route attribute

The parent page must monitor for accountSetup and provide the glue logic to handle it.

User actions that fire this event:

The "Link More Accounts" button
The "Connect Accounts" menu option, then the "Enter New Credential" button in the dialog
The "Connect Accounts" menu option, then the "Link More Accounts" button in the dialog
The "Re-Authenticate" menu action
The edit pending request action
The account name

badAuthentication

Required handler behavior: Re-authenticate the user and call setAttribute("auth-context", ...) with the refreshed values before the user can proceed.
Type: Critical
Scope: Both components
Trigger: A request to the server returns a 401 Unauthorized response
Event detail string: "Unauthorized access". A badAuthentication event indicates the user's authentication context is no longer valid. The session may have timed out or the authentication may have expired. The user cannot interact with the component until the parent page re-authenticates and provides a new auth-context value. The user's authentication can end at any time. Whenever the parent page receives badAuthentication, it must re-authenticate before the user can proceed. Note: When authentication fails for either component, reestablish it for both.
Blocked component state: While the component is in a blocked state, it appears greyed out on the parent page. Once authentication is reestablished, the user can proceed from where they left off.

badConfiguration

Required handler behavior: Recognize the licensing error and remedy the problem.Type: Critical
Scope: Both components
Trigger: The component is not licensed
Event detail string: "User not licensed". 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, the same way it appears for a badAuthentication event.

internalError

Required handler behavior: Recognize the error and remedy the problem. The parent page may also pass a message to the user describing the type of error.
Type: Critical
Scope: Both components
Trigger: A server request returned an error other than 401, or an internal code error occurred
Event detail string: One of: "Forbidden access", "Service unavailable", "Unknown server error", "Unknown error", "Resource not found" When an internalError event occurs, the component's user interface remains static. 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.
Specific error causes:

Forbidden access: The user does not have the necessary permissions; they may have read-only permissions.
Service unavailable: Possibly an intermittent service interruption.
Resource not found: Could be a misnamed path or file.

userExit

Required handler behavior: Hide Account Linking, or activate it again by setting the route attribute to reopen at a specified point in the workflow (if the authorization context is still valid).
Type: Critical
Scope: Account Linking only
Trigger: The user completes an action or exits the workflow
Event detail string: "User exit" A component sends userExit when the user does one of the following: completes adding an account, completes editing an account, cancels out of the workflow, or declines the user agreement.

dataChanged

Optional handler behavior: Refresh any display of account, credential, position, and transaction data in the parent page.
Type: Standard
Scope: Account Linking only
Trigger: The user makes a change to a credential or account
Event detail string: "Data changed" The dataChanged event lets the parent page know something has changed in Account Linking. Changes may affect any or all of the following: authentication status, accounts linked to the credential, and financial data for those accounts. The event is emitted each time one of these data changes occurs, so the parent page may receive this event multiple times during a single session of Account Linking.

dataChangedAsync

Optional handler behavior: Poll for asynchronous activity completion, then query the API to obtain the changed data.
Type: Standard
Scope: Account Linking only
Trigger: The user initiates an aggregation operation
Event detail string: "Async Data change" The dataChangedAsync event lets the parent page know the user submitted a composite "aggregate" in Account Linking that triggered the service to run a complex and long-running process asynchronously. The composite "aggregate" can be discover/add/aggregate, add/aggregate, or just aggregate.

dataChangedAsyncAuthenticate

Optional handler behavior: Poll for asynchronous activity completion, then query the API to obtain the authentication status.
Type: Standard
Scope: Account Linking only
Trigger: The user initiates an authentication operation
Event detail string: "Async Authenticate Data change". 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.

userDeclinedAgreement

Optional handler behavior: No required response. The parent page may track that the user did not accept the agreement, depending on the integration's needs.
Type: Standard
Scope: Account Linking only
Trigger: The user does not accept the terms of the user agreement
Event detail string: "User declined user agreement" A userDeclinedAgreement event occurs when a user does not accept the terms of the latest user agreement when prompted in Account Linking.

👍
Success Criteria
Upon successful implementation, you will have:

Event listeners set up on the components for each critical event the parent page must handle

Handlers implemented for each of the five critical events: accountSetup, badAuthentication, badConfiguration, internalError, and userExit

The accountSetup handler passing event detail strings to Account Linking via the route attribute

The badAuthentication handler re-authenticating the user and refreshing auth-context for both components when authentication fails

Optional listeners and handlers for any standard events the parent page wants to react to