Sparky - Inventory UI Service

alternate text

Overview

Sparky is a service that interacts with resources and traversal microservices, and provides users with a user interface to view and analyze AAI data. The main goal behind Sparky is to provide a clear and user friendly view of AAI data.

The key AAI repos for running the Sparky UI are:

  • aai/sparky-fe: This holds the code that constructs the GUI

  • aai/sparky-be: This holds the Java code and other technologies that provide the front-end with its data.

Platform

Sparky is a user interface that currently exists in the AAI ecosystem. Sparky provides users the ability to view and analyze data that is present in A&AI.

Architecture

Sparky Architecture in AAI

The Sparky microservice is built on a spring platform. The table below highlights Sparky’s interaction with various microservices that exist in the AAI ecosystem. .. _architecture:

_images/sparky-interaction.png

Sparky - Browse

Browse Overview

Browse provides a way to easily browse the inventory items in A&AI

alternate text
Browse Features
With Browse UI, users can:

  • Click on a tile for a configured node-type and view the instance data

  • The user can view the information on the subsequent page in a paginated format (50 results per page)

  • The user can filter down the results by attributes on the top of the page (exact string matching only)

  • The user can download their results to xslx (500 results at a time)

  • The user can opt to download a range of pages to download to xslx

  • The user can view results in card-based format

  • The user can view results in a tabular-based format

  • The user can choose a defaulted format (saved in local storage)

  • The user can view & traverse relationships of an element

  • The user can build a query giving the element and all related elements (1 hop) by clicking >>BYOQ

How to use Browse

  1. On the Browse page click a desired node type to view, in this case I chose generic virtual network functions

alternate text

  1. On the resulting page you can see the results in card format

alternate text

  1. Or in tabular format

alternate text

  1. A user could view the relationships of an element on the card format by clicking the relationships button,

Clicking a relationship will traverse that relationship to the item

alternate text

  1. A user could view the relationships of an element on the tabular format by clicking the + to expand the row

Clicking a relationship will traverse that relationship to the item

alternate text

  1. A user could filter their results by adding filters at the top of the screen

alternate text

  1. A user could build a query giving the element and all related elements (1 hop) by clicking >>BYOQ

alternate text

  1. A user could switch between view types using the blue and grey buttons here, they can also set their default view here

alternate text

Sparky - BYOQ

BYOQ Overview

BYOQ provides a way for users to build their own traversal queries in A&AI

alternate text
BYOQ Features
With BYOQ UI, users can:

  • Create queries to extract information using typeahead help functionality

  • The user can view help menus on the DSL syntax

  • The user can view the information in a paginated format (50 results per page)

  • The user can filter down the results in the tabular view on the column headers (exact string matching only)

  • The user can download their results to xslx (500 results at a time)

  • The user can opt to download a range of pages to download to xslx

  • The user can view results in card-based format

  • The user can view results in a tabular-based format

  • The user can view results in a visual format

  • The user can pinch/zoom in the visual format and double click on the elements to get additional info in a modal

  • The user can choose a defaulted format (saved in local storage)

  • The user can view & traverse relationships on an element

  • The user can build a query giving the element and all related elements (1 hop) by clicking >>BYOQ

How to use BYOQ

  1. On the BYOQ page click in the dsl query input box and start creating a query

Typeahead will help with creating connections or filters as the query is being typed out (it can be configured off)

In this case I started from a generic-vnf with a specific filter and selected a few elements directly connected to it and ran the query

The results can be seen below in card format

alternate text

  1. We have the option to view the output in tabular format

alternate text

  1. As well as visual graph format

alternate text

  1. You can pinch/zoom & drag/drop in the visual view and double clicking an item brings up its details in a modal

alternate text

  1. The user can access the syntax help documentation from the accordions

alternate text

Sparky - BYOQ Builder

BYOQ Builder Overview

BYOQ Builder provides a way to easily create complex queries through a visual builder

alternate text
BYOQ Builder Features
With BYOQ Builder UI, users can:

  • Click on a tile for a configured node-type and view the instance data

How to use BYOQ Builder

  1. On the BYOQ Builder page click ‘Start Building’ to open the modal with all node types, to choose a starting node for your query

alternate text

  1. In this example I chose generic-vnf and decided to filter on one of it’s properties by clicking options and entering a filter

alternate text

The little blue + box allows for adding OR filter values (but I don’t use it here)

alternate text

  1. Scroll the modal to the bottom and click submit, you will see the element you chose and a DSL query being built

alternate text

  1. From here you can add, remove, or edit via the icons on the node, in this case I choose + for add check a few more nodes in my query path

alternate text

  1. After submitting that I can see the query being built at the top and it showing the same visually

alternate text

  1. You can continue this process of adding/deleting/editing and adding filters until you have the final query for your desired output.

At this point you would click Run Query or Manually Edit and Run Query if you want to make manual edits.

After this is done, your qury will be ran and results returned.

alternate text alternate text

Installation and Developer Setup

Project Structure

Sparky is structured with a top level project that contains two sub-projects (application and service projects). The application project contains the configuration and spring application code that customizes and runs sparky as an application. The service project contains the core sparky code that provides functionality for sparky-fe requests and synchronization.

In regards to the front-end (sparky-fe), sparky-be serves up the sparky-fe web content and sparky-be deals with all inter-microservice communications.

Clone, Build, & Configure

Clone & Build

Clone the sparky-be repository into a directory of your choice.

git clone ssh://<username>@gerrit.onap.org:29418/aai/sparky-be

After cloning the project (sparky-be), build the project by executing the following Maven command from the project’s top level directory:

mvn clean install
Configuration

All configuration for running sparky is found in <working directory>/sparkybe-onap-application/config.

Profiles

application.properties is the main configuration point for the sparky application. Within this file the spring.profiles are set. Each spring profile has configuration that will be loaded into an associated spring bean. The currently available profiles:

  • camel

  • http | ssl

  • fe-dev | fe-prod

  • oxm-default | oxm-override

  • resources

  • oxm-schema-dev | oxm-schema-prod

  • aai-proxy

  • gizmo (retired)

  • sync (retired)

  • portal (partially retired, only use if needing aaf auth and portal integration)

Profile descriptions:

  • camel - Enables spring-boot camel routing rules

  • http - Sets Sparky’s communication protocol to HTTP

  • ssl - Sets Sparky’s communication protocol to HTTPS

  • portal - Adds ONAP portal processing to Sparky’s flow (currently removed from oom)

  • fe-dev - Exposes the static folder for UI development when running Sparky locally (target/static)

  • fe-prod - Exposes the standard path for the UI in the docker container

  • oxm-default - Sets the default version and version list of OXM files to be used

  • oxm-override - Sets a custom version and version list of OXM files to be used

  • resources - Sparky will use aai-resources (microservice) as the primary source of inventory information

  • gizmo - Sparky will use gizmo (microservice) as the primary source of inventory information (retired)

  • sync - Will cause Sparky to run any configured synchronizers to populate index data in a single large transaction (retired)

  • oxm-schema-dev - Sets the location to find the OXM files within a development environment

  • oxm-schema-prod - Sets the location to find the OXM files within a deployed environment

  • aai-proxy - Proxies call made from the UI to resources or traversal microservices

The idea behind the profiles is to create a simple approach to adjusting runtime behavior without needing to edit large xml files (see Spring Beans below). Ahead of running Sparky, some of the profiles will need to be edited to work within your environment (e.g. set where your custom OXM files need to be loaded from).

Spring Beans

The spring-beans directory contains all the .xml bean representations that will be auto-wired at runtime. Some of the beans are associated with a single profile (see “profile=” in header of bean declaration), and others will be loaded with differing values depending the profile used.

Scanning through the beans and cross-referencing with their associated Java classes is a good way of getting familiar with the startup and runtime of Sparky.

Authorization

Within the “auth” directory are any certs needed to communicate within the environment you are currently working in (remember Sparky can be configured to run using HTTP).

Filters

The “filters” directory contains the JSON descriptor files that describe the filters used in the VNFs view.

Logging

Sparky uses the Logback framework to generate logs. The logback.xml is contained in the “logging” directory.

Running Locally

The configuration described in this section will be in reference to running Sparky through Eclipse. The same steps can be applied to running via bash/cmd with minor tweaks.

Sparky should be built ahead of running (mvn clean install). It’s useful to add a build configuration to Eclipse to build Sparky.

The run configuration should contain the following:

  • The configuration should be created based off of the “Maven Build” template

  • “Main” tab

    • Build directory - ${workspace_loc:/sparky-be/sparkybe-onap-application}

    • Goals - spring-boot:run

    • Parameter table

      • name: CONFIG_HOME value: ${workspace_loc:/sparky-be/sparkybe-onap-application}/config

      • name: APP_HOME value: ${workspace_loc:/sparky-be/sparkybe-onap-application}

Deploying Sparky

At time of writing (Oct 2018) Sparky is primarily deployed into a Kubernetes environment or a “pure” docker environment using custom chef parametrization. How you want to deploy Sparky is up to you. At a high level, the cleanest approach is ensuring your configured property (profiles) files are copied into the docker container so the Spring context has access to the values which will in turn start Sparky using your configured values.

See sparky-be/sparkybe-onap-application/src/main/docker -> Dockerfile for details on how Sparky runs within a Docker container.

Front-End (sparky-fe) Details

Clone, Build, & Configure

Clone the sparky-fe repository into a directory of your choice.

Dependencies

You will need to install the following tools:

  • node.js, including the Node Package Manager (NPM) (if there issues installing the latest version, try 6.10.1)

  • Python 2.7.13

After installing node.js and NPM, you need to install the required node.js packages by navigating to the top level sparky-fe directory and executing:

npm install
Build

To build sparky-fe (generate a .war file):

Execute:

gulp build

The build will create a directory called dist and add the aai.war file to it.

If changes to the build flow are required, updating webpack.config.js and gulpfile.js will likely provide any build tuning that is required.

Running sparky-fe Locally

Execute:

npm start

By default the local instance of the UI will be served to http(s)://localhost:8001/#/browse.

If deploying through OOM use {host}:30220/services/aai/webapp/index.html#/browse

Deploy sparky-fe

If you have access to a container repository (e.g. Nexus), push the .war image that you have built to your repository and configure your sparky-be sparkybe-onap-application/pom.xml to pull your sparky-fe image.