CMS

Scope

The CMS is a multi-tenant application that manages editing and rendering websites for many of our clients. It uses the Play framework, currently version 2.4.x.

The CMS itself is a single deployable with several supporting libraries but does interact with a couple other deployables as well.

• banno-cms - primary repository
• banno-cms-forms - library that supports forms for the websites
• messenger - handles interactions with email and Twilio to support conversations between FI’s and clients, integrated with some of the forms
• history-client - tracks FI user events that will be displayed in the History application
• sentinel-client - used to set up maintenance windows for Monitor our site defacement monitoring tool
• users-and-groups - library used to manage FI users and permissions
• optimalblue-client - integration with a third party api Optimal Blue to retrieve mortgage rate quotes
• scala-sitemap - library to help generate a sitemap.xml file
• americano - usually referred to as the “old editor” this coffeescript library provided formatting tooling for editing pages
• editor - javascript library that provides formatting and tooling to edit pages using TinyMCE. Sometimes referred to as the “new editor”.
• history - application that stores user events, can be accessed at /a/history on our environments
• monitor - application that will crawl websites, take a snapshot of the current site and check for unexpected changes, can be accessed at /a/monitor on our environments
• forms - application that supports building forms and accepting form submissions. Successor to banno-cms-forms. Can be accessed at /a/cms/<institution short id>/form-list on our environments.
• marketing - application that serves targeted ads to site visitors can be accessed at /a/marketing
• microsites - small single page static sites that we fail over to in order to provide online banking access in the case that banno-cms experiences downtime

There are a couple demo sites set up that can be used to test things out on.

• https://demo-stag.banno.com
• https://demo-uat.banno.com
• the production equivalent does exist but please keep modifications to a minimum as it is used as a sales demo site

There are a couple sales demo sites as well, avoid making changes on these.

• Bloom UAT
• Bloom production
• Garden UAT
• Garden production

Glossary

To be fleshed out as we go

• transformer - an html tag usually in the format of <banno:*></banno:*> where * is the name of the transformer. The tag is swapped out for the HTML/CSS/Javascript that will actually be rendered. Essentially a shortcut building block for site builders.

Features

Assets

The assets management view can be accessed on the Assets tab. These are FI user managed assets (images, pdfs, and other documents) that the users may want to insert into their content.

Assets can be inserted into content either by inserting it as an image or it can be linked to as a file.

When inserting an image onto a page there are some basic image editing capabilities available through the use of the TinyMCE image editor.

Calculators

The CMS makes use of a third party Javascript package of financial calculators from KJE Computer Solutions. These calculators are placed into a page by use of the calculator transformers in the page’s template. There’s no administrative functionality to them so there are no backend features in the editor for it.

Some example calculators can be viewed on one of the template sites.

We receive quarterly updates and from time to time additional bug fix releases for them. Details on performing an update can be found here.

Forms

The forms feature manages any html form on the site where the clients want to manage the submitted data. So something like a Contact Us form but not a third party form like online banking.

Submissions can be viewed and managed on the Forms tab in the CMS. There they can be exported in a CSV or PDF or viewed in HTML. They can be archived (which retains the submission but removes it from the inbox) or deleted. Deletions are not tombstoned in this case, the data is permanently deleted for compliance.

The current process of creating forms requires scala dev work more details on the process are here.

Form Builder

The form builder lets users construct their own custom forms that can be inserted into content areas on a CMS page. This requires no development time from either the services team or the web team. This will eventually be replacing the Forms system above.

Submissions through this system can be managed at /a/support.

Forms and form-blocks are the relevant repositories for this feature.

Locations

Troubleshooting steps

The location editor is found on the Locations tab in the CMS. It allows the client to manage what ATM or branch/service center locations are displayed to site visitors through the locator components.

We categorize locations into two types: ATMs and branches. ATM locations are places where an ATM can be found. While branch locations are where the bank or credit union has a physical presence.

A location will consist of an optional name, street address, city, state, zip, latitude and longitude.

Branch locations currently allow for a details field which is free form text that the user can put in any info they’d like, usually used for location hours. They also can have an image assigned to them to be display along with the details. And they may also have a phone number for the location.

ATM locations don’t have much more than the base fields. They are assigned to what we call a Network. Networks are essentially just a group of ATMs that belong to an organization or brand. These can be public and shared with other FI’s like in the case of Shazam or MoneyPass or they can be private and only for the institution they’re linked with. Any given FI may be assigned any number of networks although the map will quickly become cluttered as more public networks are assigned.

There is a restriction of 500 locations being retrieved on any given search.

To take a look at the customer facing components you can head to the demo site.

Members

Essentially a striped down version of Users and Groups. This feature manages users that may need access to protected content on the site. These members do not have authorization to log into the CMS editor. It can be accessed at on the Members Only tab in the CMS.

Both pages and assets have Visibility properties that can be assigned to one of these member groups. When a user attempts to view one of these items they must be signed in as a member to view them. By default all pages and assets are set to a Public setting where anyone can view it.

Pages

The primary feature of the CMS. When we talk about the “Pages” feature we’re referring to the portion that directly manages editing pages in a website.

The page management view can be accessed on any site at the Pages tab, it’s also the default page once logging into the editor on a site. Controls for adding, editing, deleting, submitting for approval, and publishing are on this page.

In general any created or edited page goes to a modified state and changes are not rendered on the live site until the changes have gone through the approval process (if one was set up, more on that in the Users and Groups section) or published by a user.

Page models are versioned and only one version should be Live at any given point in time.

Template Assets

This refers to the collection of assets that webdevs / site builders use to create a site. These files are bundled together in a zip file which is then uploaded to the site being built and stored in the database in versioned models.

These zip files include static assets like javascript, css, and images as well as the mustache files used as the template for all pages within the site.

Only one of these versioned models is considered active at a time, generally the most recent one taking priority unless someone specfically activates an older one.

Downloading the existing template or uploading a new one can be done with the template manager located on the Settings tab –> Templates.

Rates (aka Treasury)

The rates (aka treasury) feature allows user management of various rates including CDs, checking, mortgage, etc… The user can set up a product and then plug in the values that relate to it i.e.: APY, APR, or period. With this users can manage rates in one place even if the values end up getting spread across the site and duplicated in different places. The editor can be accessed on the Rates tab in the CMS.

These products can also be grouped into markets if the FI has more than one area with differing rates between them to manage.

Product data is also versioned which means that it requires publishing and potentially approvals if they are set up before changes are sent live.

Once the client has some products entered any of the individual components of the products can be inserted dynamically into the content with the editor. Once linked into the content the CMS will pull the current live version of that product field into the content.

Approvals

Approval flows are sometimes desired for modifications to pages or treasury rates where one user may be allowed to make changes but not publish them to the live site until they’ve been reviewed by other users. This is managed through the Settings app (/a/settings) groups Reports To and Needs approval from fields. A group reporting to anything other than Nobody will start an approval flow with their changes which will send approval request emails to members of the reported to groups. This request can either require approval from all members of the group or just a single person. Having publish rights overrides the need for approvals.

Deployment

Build and deployment details are here.

Scaffolding a site just for Locations access

We’re running into a few situations where we want to give Mobile clients access to the locations editor. To do so we need to set up a dummy site configuration for the institution. We basically strip the scaffold down to the bare minimum requirements only leaving required pieces and the location configuration intact.

To prepare the scaffold take and edit the json object below.

• We do need values for domains even though the client may not have an actual website with us. They must be unique as well.
• preferredDomains values can be left null.
• databaseName should use underscores for whitespace.
• googleMapsKey will need to be procurred from an account manager or implementation. Usage will contribute a small amount to our monthly charges for Google Maps api usage if we use one of our keys. A key from the client would likely not exceed Google’s free usage quotas for a single institution.
• bannoApiToken should be generated and recorded with the same atm locator setup done via https://trello.com/b/EGdSYxcE/atm-locator

{
  "site": {
    "domains": [
      "make up a uat domain here",
      "make up a production domain here"
    ],
    "preferredDomains": {
      "production": null,
      "uat": null,
      "staging": null,
      "dev": null,
      "local": null
    },
    "databaseName": "demo_bank",
    "name": "Bank name goes here",
    "themeId": "default",
    "bannoInstitutionId": "Institution uuid goes here",
    "features": [
      "LOCATION_MANAGER"
    ],
    "config": {
      "atm": {
        "defaultLocation": {
          "name": "Bank",
          "address": "123 Main St",
          "city": "Cedar Falls",
          "zip": "50613",
          "state": "IA"
        },
        "defaultRadius": 500,
        "googleMapsKey": "google maps api key goes here"
      },
      "banno": {
        "bannoApiToken": "c820aa53-44e9-4c14-8f30-4a1569e77f64"
      },
      "categories": [],
      "showSharedContentFeature": true,
      "useTinyMCE": true,
      "enable2fa": true
    }
  }
}

When ready, submit the JSON using the Platform CMS Postman Collection see installation instructions here. The relevant section is Scaffold –> Create on UAT and Production to create the site. After that, the location editor should be accessible for that institution in the CMS.

Header & Footer code

Header and footer code can be injected into pages either globally or on a page by page basis. Clients can use this to inject any javascript snippets they desire to into pages. The interface to do so globally can be found at /a/cms/<institution short id>/site-settings/general. The interface to add it to just a single page can be found by editing the desired page and then clicking the page settings gear wheel in the upper left hand corner of the screen.

Disclaimers

Disclaimers can be attached to links to alert users that they are leaving the site. They will appear as a pop up box after the link is clicked and wait for user confirmation to proceed.

Disclaimers can be managed at /a/cms/<institution short id>/site-settings/disclaimers where they may be created, edited or deleted. Disclaimers can also be created when inserting links in content areas.

Redirects

Users can self service setting up redirects for their site if needed at /a/cms/<institution short id>/site-settings/redirects. They can be set up individually or bulk via a CSV import/export service.

Shared Content Areas

Shared content areas are used as a means of linking areas across multiple pages so that they show the same content. Once linked, updating one instance will update all of them. They do count as multiple changes though so each page changed will need to be published for all instances of the change to go live (ie: you make one change and multiple pages will show as modified and will need to be published).

Shared content areas can be managed by clicking the gear icon in the top left corner of a content area. An existing group can be selected or a new one created from the drop down menu. Once the content area is part of a group the border will turn purple instead of blue and the name of the group it belongs to will display in the top left corner of the content area. Changes will propagate to other members of the group once edits are made and the page has been saved. Once a content area is part of a shared content group it may be removed by using the Remove from group option in the drop down list. There is an interface to view and delete shared content areas at /a/cms/<institution short id>/site-settings/shared-content as well.

Admin Settings

A link on the bottom of the left hand side of the settings page will take you to yet another settings page with options available just to internal (LDAP) users.

Settings

Located at /a/cms/api/site/<domain>/settings/site, this page contains several generic site related settings.

• Banno History Product Status: originally used to activate the History product for the FI. Probably is no longer necessary as it should be activated when the FI is set up anymore.
• Editor: used at one point to toggle between using the old editor (Americano) and the new editor (TinyMCE). Probably can be removed at this point as all sites should remain on the new editor now.
• Lock institution users from logging into site: this is used during the window of migrating the site from UAT to production. Account managers lock the users out to prevent any interference with prepping the site for launch.
• Send user creation notifications to all users for this site: clicking this button will send out password reset emails to all users with CMS permissions on the FI. Users will need to reset their password after migration if they did not already have a production account prior to site migration.

Emails

Located at /a/cms/api/site/<domain>/emails, this page provides a simple lookup interface to see what CMS emails have been sent out to users and when.

Duplicate/Migrate Site

Located at /a/cms/api/site/<domain>/migrate, this page provides an interface to migrate a site from one environment to another. This page should be accessed on the environment you want to migrate the site to. You will need to provide login credentials to the form. It will login on your behalf to the source environment where you are migrating from to pull the data across to the target environment.

There a couple of extra options that may come in handy occassionally revealed by clicking Show Optional. New site json (optional) provides a text area where an alternate institution json model can be provided. This is used if a direct copy of the institution model is not desired. Migrate Live Page Versions Only: with this checked only the live versions of pages are migrated, modified versions and deactivated pages are excluded.

After filling out the form and clicking the migrate button you should see the progress start to display below. If you happen to run into errors and the migration is incomplete you may need to clear out partial site data from the mongo database before attempting the migration again. Steps can be found here to remove a site.

Asset Search

Located at /a/cms/api/site/<domain>/asset/search, this page is a simple lookup tool that lets a user find all pages that a given asset is located on either by the asset id or by the file name.

Create a form

Located at /a/cms/api/site/<domain>/forms/create, this page provides a form to add a new form instance to the site. This would be for the legacy form system and not the form builder. This is typically used by the web team when they are ready to start implementing the front end for a form.

Location config

Located at /a/cms/api/site/<domain>/locations, this page provides an interface to the location section of the institution configuration. Various configuration items that control the behavior of the atm locator are found here. Most importantly are probably Google Maps API key and Banno consumer api token.

The Google maps api key should be set up and provided by the client to us, usually facilitated by communication with the account manager or support team. If this value is not set requests will fall back on a default configuration key registered on our accounts which incurs costs on us. Individual clients with their own keys will generally not exceed Google’s free usage each month but our bulk usage across multiple clients does.

The Banno consumer api token must be set to allow the site to access the consumer api for network, atms, and branches info. This token is generally provided as part of the atm setup process and should be on cards on either Trello for older setup requests or JIRA for newer requests. If nothing is found either on either board a new token can be generated by the atms-repository using the process below.

  sbt
  project atms-repository
  test:run <institution uuid>

This will generate a password which is the token that should be entered as the Banno consumer api token. It will also generate an SQL insert statement. This should be run on the UAT and production banno_all databases.

Additional information on the other configuration items can be found here