Hello World

The most basic Caliper SDK extension is a simple custom form in Online Banking. Let’s go through a quick walk through of creating a form and installing it into an environment.

Initial Setup

Be sure to check out our Setup Guides page before you begin coding.

Defining Terms

Let’s define some terms we’re going to use before we get going. It can be helpful to pair this with the Q2 architecture diagram.

  • Platform: The Q2 product you’re making your extension for. We have products for retail banking customers, commercial customers, banking customer service and many others. You can also extend some of the internal projects that serve those platforms, e.g. Ardent.

  • Online Banking: aka OLB, Online, Ngam, UUX. That’s the platform this tutorial is for, and what the majority of extensions are built for.

  • Ardent: part of the Online Banking stack, a web application that loads UUX and handles routing to our internal business logic.

  • Stack: The layers of software and infrastructure setup to provide an environment (e.g. Staging, Test, or Production) for an FI

  • Tecton: Tecton is the jelly to Caliper’s peanut butter, the JS frontend libraries that pull in webcomponents for you to use and custom APIs to interact with the platform you’re on (e.g. Online Banking) and your own Caliper server. We’re going to be using it a good bit in this tutorial.

Start Coding

Before we get started, let’s make sure we’re working on the same version this tutorial was written for:

$ q2 upgrade -p sdk

This will prompt you to upgrade your SDK version. If you are already on the latest version, great! You can press CTRL+C to leave the menu.

Now, let’s create a new “Accounts Dashboard” extension that allows users to see all their accounts at a glance.

Note

Throughout this documentation, we will use an indented block starting with $ to represent typing at the command line. This will be the command line on the box the sdk code is running from. If using Pycharm, you can get there with Tools -> Start SSH Session -> The Deployment Configuration name you chose in your IDE setup

We’ll call this extension AccountDashboard:

$ q2 create_extension AccountDashboard

Warning

Only one extension named “AccountDashboard” can exist in the database! If other developers at your organization are working through this tutorial, be sure to give your extension a unique name.

At this point you will be presented with a list of the different types of extensions you can create with the Caliper SDK. For the purposes of this tutorial we will select the first option and focus on Online extensions. After selecting Online you will be presented with two different options for building your extension. Please consider which option is best for your project and skill set. The choice you make here will determine the tab you reference in the code blocks in the rest of this tutorial.

Note

Server Side Rendered

This option will use server-side-rendered HTML from jinja templates. This paradigm is a more traditional web application approach where each page is generated from an incoming HTTP request where the server gathers the data it plans to render and then runs that data through a jinja template. The resulting HTML is then returned to the browser. Any subsequent page navigation follows the same pattern. If you are just getting started this is the recommended option.

Client Side Rendered

This option will use a javascript framework (react, ember, vue, angular, etc) to load an initial static HTML page and fetch any data from the server via API calls. Any additional page navigation or UI renderings would be done using the chosen javascript frameworks conventions. It is recommended to only choose this option if you are familiar with single page javascript applications or want to learn about building applications in that way. You should follow the remaining steps on this page but go to Client Side Rendering Tutorial once these steps are completed.

Next, you will be prompted to select the type of Online integration you would like to generate. For the purposes of this tutorial we will select the first option, Authenticated, but we encourage you to explore the other options in our documentation to see which one best suits your needs.

You should see some output scroll by verifying that a handful of files were generated to support the new extension.

Note

Troubleshooting tip: If q2 create_extension fails, you might need to run q2 setup in this directory to generate a settings file.

Open up the resulting AccountDashboard/extension.py file, and let’s see what was created for us.

Note

If using Pycharm for your editor, be sure to sync the generated folder by clicking Tools -> Deployment -> Browse Remote Host, right clicking the folder AccountDashboard and selecting ‘Download from here’. Also be sure to sync configuration/settings.py.

A complete, working extension has been created for us with plenty of hooks for the special functionality that we will be adding.

Let’s go ahead and install this extension as a form in the Online environment to see our work as we make changes:

The file configuration/settings.py holds all the extensions that the sdk will serve up. Our AccountDashboard should appear here, since we elected to register our new extension:

INSTALLED_EXTENSIONS = [
    "AccountDashboard"
]

Now we register and install the extension into the database with a single command:

$ q2 install

Fill out the information when prompted. The custom name you choose here will be the label added to the navigation menu in the next step.

Note

A word about the groups you’re enabling in this step. The DB structure works like this: logins belong to users, users belong to a customer, customers belong to a group. Every FI has multiple user groups, each with a set of what we call “entitlements”. Selecting these groups in this command “entitles” certain users to see your extension. These entitlements can and do vary across stacks, so enabling Retail users to see your extension here won’t automatically allow people in production to see the test version. But knowing the group/user relationship is important to knowing that your test user is going to be able to see your extension.

Note

Troubleshooting tip: If you are not using the shared dev machine, q2 install will add your local IP to the database, which Online will query when the form is called for render. If your IP changes for any reason, you will need to use q2 update_installed and set the URL to reference your new IP.

When that is completed, our form is now installed and we can navigate directly to its URL after running q2 run. That URL would look something like this (Example Only):

https://<yourstack>/ardent/uux.aspx#/extension/AccountDashboard/Main

But, let’s take it one step further and add an item to the navigation menu to give our users easy access to this form. For that, we have one more command:

$ q2 add_to_nav

The CLI will guide you through selecting a place in the nav menu for your extension. Next time you log in to the Online environment, your menu item should appear.

Finally, we need to run our server so when we make requests, our Caliper SDK server returns a response.

Run the server with the following command:

$ q2 run

Let’s head over to our Online environment and see it in action! An Online user and password should’ve been provided for you during the sdk registration.

That’s all it takes to get a form up and running in the Caliper SDK! Now we have a fully functional foundation on which to construct our extension. Once installed into an environment, the changes we make to our extension will automatically restart our server, and we can see them in Online simply by reloading. No re-installation required!

The Caliper SDK makes use of the same powerful financial APIs we use internally.

For the next step, we’ll start using them to display useful information to our users. If you chose the Client Side Rendered option you can jump over to the Client Side Rendering tutorial here: Client Side Rendering Tutorial.