Build Your First Plugin

This Quickstart guides you through building your first plugin using our example project, Simple Plugin Example.


Prerequisites

Before you get started, you'll need the following:

  • The back office administrator at your financial institution who has access to Banno People

When referencing Banno People, we mean your financial institution's deployment of Banno People.


Configure the Plugin

External Application

You'll need to configure an External Application in the External applications section of the Banno People app.

For this example, change the following values:

  1. Create a new external app
  2. Enter a custom name (ex. First demo plugin)
  3. Uncheck User consent required (since we are building a Plugin Card)
  4. Click Save

    • After clicking Save, you will be redirected back to the list of external apps, open your new app from the list

Create new external app

  1. Select PluginCard as the link type
  2. Enter a title for the link (ex. Test Plugin)
  3. Enter http://localhost:8080/static for the redirect URI (Note: You may need to change this if you alter the port number later)
  4. Select Enabled to enable the plugin for users

Configure the plugin

When you click the save button, the credentials will be saved along with these auto-generated values that you will need in later steps:

  • Client ID
  • Client Secret

Client ID and Client Secret

Plugin Configuration

Required Steps

You'll need to create the Plugin Configuration in the Dashboard configuration section of the Banno People app.

  1. Click Add an item to add a new item to the dashboard configuration
  2. Click Create a plugin

Create a plugin for dashboard

  • Title: Test plugin
  • Description: Demo quickstart plugin
  • External Application: First demo plugin - Test Plugin (This is the name we used when configuring the external application above)
  • Initial height: 200
  • Icon: heart (this can be anything)

Optional Steps

For this example, change the following values:

  • Label: View more
  • External Application: First demo plugin - Test Plugin

Configure dashboard app details

Dashboard Configuration

Clicking the save button will create the plugin configuration.

The administrator can make it available for your users to add to their dashboard.

Note: Since we did not enable the option Available to everyone, we will need to enable the plugin for specific users. While building and testing your plugin, you will likely want to utilize this option. Enabling for all users will make the plugin available globally to every user in your institution.

Save dashboard configuration

Enable Plugin Card for User

As mentioned in the note above, if you don't want the plugin enabled for ALL users, we need to select which users to enable the Plugin Card for.

  • From Banno People, click the Users and search by username. Search Users
  • Click on the user
  • Click Permissions
  • Find and enable the plugin under Plugin cards Enable Plugin for User

The user will now have the plugin available to them in the Banno Online dashboard.


Running the Plugin

Simple Plugin Example

Start by cloning the repository, Simple Plugin Example.

The Code

This is, as the name describes, a very simple plugin example. It's designed to showcase the essential parts of building a plugin, and equip you to get started building your own. Let's break down a few key parts of the code.

config-EXAMPLE.js - you will want to rename this file to config.js, we will provide the necessary configuration elements in the step below.

server.js is the primary driver of the entire plugin, it is an Express.js server application. We have exposed a /static and /dynamic endpoint to the server which are used as the callback URI (the static endpoint we will use to make sure everything is configured correctly, then we will use the dynamic endpoint to make API calls and fill the plugin with dynamic data). When a request is sent to /static a simple, static HTML page is rendered in response. When a request is sent to the /dynamic endpoint, we'll do a series of operations to authenticate the user, then retrieve information about the authenticated user.

get_tokens.js, in this file we are simply calling the API in order to get the authentication token. Within this token we are providing the API keys from the config.js file as a base64 hash, and the API's /a/consumer/api/v0/oidc/token endpoint responds back with an authentication token that we will use to make subsequential API calls. The response has two parts, the Authentication Token (used to make other authenticated requests) and an Identity Token (used to extract information about the user).

One we have received the auth_token we will make an authenticated request to the v0/users/${user_id}/accounts endpoint to get a list of accounts associated with the user.

Finally we use all of this data to render the front end, which the user will see in their dashboard. Now that you have an idea of how the app works, let's get it running!

Setup

Before we run the application, we need to make sure that all the dependencies are available.

  • Install dependencies

    npm install
    

Running the static plugin

  • Start the server.

    npm run start
    

The server will now be running locally. You'll see this log statement in the terminal:

App running at http://localhost:8080

Banno Online

User's Dashboard

You'll need to add the plugin to your user's dashboard.

Do these steps:

  • Log into Banno Online
  • Click on Organize dashboard
  • Click on Add a card
  • Click on Test plugin
  • Click the back arrow on Add a card in the navigation header
  • Click the done button on Organize dashboard

Back to Banno Online

When you navigate back to Banno Online, you can see that the plugin now displays the static HTML.

Static plugin running

Running the dynamic plugin

Configuration

Now that the static plugin is running, let's make it dynamic! First, we need the Client ID and Client Secret from the External Application that was configured above.

Find the config.js (make sure you have already renamed the example config file to just config.js) in the project's folder. Change the following values in that file:

  • client_id: Use your Client ID value
  • client_secret: Use your Client Secret value
  • environment: Use your Banno environment deployment location

Now, return to the Banno People External Application, change the redirect URI from http://localhost:8080/static to http://localhost:8080/dynamic

Finally, restart the plugin server.

npm run start

Now, navigate back to Banno Online dashboard, you can see that the plugin now greets the authenicated user by name and displays the number of accounts associated with the user.

You have successfully built your first plugin!

Final plugin running


Next Steps

Congratulations! Continue your learning journey: