Guides

Source Control Management

Key Features

Source Control Management (SCM) Integration & Tooling

Integration with GIT and Perforce. Conveniently check-in/out, diff history within the AMI web-based dashboard builder.

Multi-file Linker

Dashboards can be comprised of multiple files meaning components can be logically separated for independent management/version control.

Abstraction

Functionality can be marked virtual and overridden in another file, allowing for dashboard designers to abstract out functionality for custom implementation.

Refactoring Tool

Components can safely be renamed and/or moved between files. The tool automatically updates and moves dependencies as necessary with naming conflict resolution.

Dashboard File Stabilization

Changes to a dashboard result in minimum/localized changes to the underlying file. Components can be set to defaults to avoid noisy/unintended changes.

Benefits

Team Collaboration

By logically dividing a dashboard across files, Teams can simultaneously work on sub-components of the dashboard.

Reusable Components

Scripts, datamodels, widgets and entire dashboards can be written once and then reused across dashboards.

Dashboard Tracking, Versioning, Branching

As AMI files are managed by source control, they can be used to label versions of a dashboard, compare versions and manage branching.

Merging Independent Projects

Existing dashboards can be incorporated into new dashboards making it easy to build super-dashboards cross-incorporating functionality

Enterprise Deployment Strategy

Treat AMI files just like any other resources that are managed through deployment strategies, such as uDeploy, TeamCity, etc.

Dashboard Extension

Extend existing dashboards for regional/business line specific usage without needing to maintain multiple near duplicate dashboards.

Full Backwards Compatibility

File

Loads existing dashboards and automatically converts to the new format. Note: files are still json with the same general structure, just less clutter/redundancy.

Usage

Users & dashboard developers can continue to develop/maintain dashboards without change. Changes are purely additive, existing functionality has not been changed nor removed.

Split Dashboards

Split existing dashboards into separate files for better SCM management.

Combine Dashboards

Utilize multiple existing dashboards to create a single super-dashboard.

Key Concepts

Dashboards vs. Layout

Prior to Source Control Management (SCM), a Dashboard was backed by a single Layout file, so the terms were interchangeable. With SCM, a Dashboard can be an amalgamation of multiple Layout files so the distinction matters:

• Layout: an individual .ami file which contains a set of source definitions such as Panels, Datamodels, Relationships, AmiScript, etc. 
• Dashboard (Root Layout): the .ami file that is directly opened (ex: File > Absolute File - Open) is considered a Dashboard, or more specifically the Root Layout

Included Layouts

A layout file can also include pointers to other .ami Layout FIles (Dashboard > Included Layouts). This forms a Parent Layout/Child Layout Relationship.

Hidden Panels

A layout file can define panels that are not directly referenced in the dashboard. If a layout includes a child layout, all of the child layout's panels are hidden by default. In order to make a child layout's panel(s) visible, you need to specifically unhide it (Blank Window > Green Button > Unhide Panel). In effect, this is how linking a panel from one layout to another is achieved.

Getting Started

Please ensure this property is set before continuing: ami.scm.plugins=com.f1.ami.plugins.git.AmiGitScmPlugin

Connecting to Source Control Management (SCM)

Navigate to Account > Source Control Settings, select the appropriate source control type and fill in your user credentials. The base path tells AMI where it expects files to reside which are managed under source control, including sub directories. (files outside that directory will not have source control functionality)

Loading/Saving Dashboards in SCM

Traditionally, layouts could only be stored under “my layouts” or “cloud”. Now there is an “Absolute” (File > Absolute File - Open) option which allows you to load/save files anywhere on the host. If you wish to use SCM to manage a layout file, it should be located under the SCM base path (Account > Source Control Settings > Base Path). Tip: To move a layout from my layouts into SCM, simply load it (File > My Layouts - Open) and then save it under said SCM base path (File > Absolute File - Save As).

Link multiple files to a dashboard

Open the project browser (Dashboard > Include Files)

To add an existing file:

Right click on the project > Add Child Link from > Existing File > select the file to add.

To add a new file:

Right click on the project > Add Child Link From > New File > Enter the name of the new, blank file to create.

Notes:

• The alias defines how objects (panels, datamodels, etc.) within this will be referenced within the main dashboard.
• Read-only: If selected then, you will not be able to save changes made to the objects within the selected file.
• Relative Path: If true, then the file will be referenced using a path relative to the parent file; otherwise it will be an absolute path. Relative is preferred for portability.

Link to a panel from another file

Be sure the other file has been included (see Link Multiple files to a dashboard). Create a blank Panel (Window > New Window), click the blank panel’s green button > unhide panel > choose the panel to display

Refactoring

To Move a panel (and it’s dependent objects) from one file to another, click on the panels green button > Move to Different Layout > select the layout to move the panel to.

Using Source Control

• Open the project Browser (Dashboard > Included Layouts), right click > Add Child Link From > Choose the appropriate action
• To see most recent changes : File > Diff against last save

Additions to Layout Editor

Hiding Panels

Panel's Green Button > Hide Highlighted Panels

Unhiding Panels

Windows > New Window > Green Button > Unhide Panel > Choose panel to unhide (Note, any blank panel can be used to link to a hidden panel

Tab Per Layout 

Several Resource editor tools are now organized such that there is one editor panel per layout.

• Custom methods:
  • Dashboard > Custom methods…
• Custom css
  • Dashboard > Css…
• Custom callbacks
  • Dashboard > Callbacks…

Owning Layout

All resources now have the concept of an owning layout:

• Variables: 
  • Adding/editing global variables now allows you to choose an owning layout (Dashboard > Variables Table… > Right Click > Add/Edit/Copy > Owning Layout)
• Relationships: 
  • Ability to choose which file owns the relationship (Green Button > Add/Edit Relationship > Owning Layout dropdown).
• Datamodels: 
  • Dashboard > Datamodeler… > Right Click on Datamodel > Config Tab > Owning Layout
• Panels: 
  • Green Button -> Move To Different Layout File -> Move To Layout

Data Modeler

There is a list of checkboxes on the left to choose which layout’s datamodels/panels to show (Dashboard -> Datamodeler)

Dashboard Objects

View for seeing all relationships (Dashboard > Dashboard Objects). Note: This was added to allow access to hidden relationships, which is a new concept. A relationship is hidden if its source or target panel’s are hidden.

Advanced Concepts

LAYOUT FILE

Previously an .ami json file was considered a fully-contained dashboard. Now, an .ami file should be thought of as a collection of resources such as panels, datamodels, code, etc. and can contain references to other .ami files. An individual .ami file is referred to as a layout. There are a few key points:

Root Layout

This is the file that was directly loaded (ex: File > Absolute File - Open) and is used as the “bootstrap” to determine which windows are loaded and displayed within the desktop.

Parent/Child Layout Relationship

A layout can include any number of child layouts such that each included layout must have a uniquely identifying alias. Note that the root Layout has no parent

Layout Alias

Each layout (.ami file) within the dashboard is uniquely identified using an alias (note that when you attach a child layout, you are prompted to choose a unique alias). This alias is used to reference objects within the layout.

Layout Nesting

Because layouts can recursively include other layouts, it’s possible to have child layouts, grandchild layouts, etc. In this case the alias is constructed by dotconcatenation, ex: a.b.c

Complex Nesting

Circular references are not supported (ex; A.ami -> B.ami -> A.ami). Diamond references are supported (A.ami -> B.ami -> C.ami & A.ami -> D.ami -> C.ami).

Read-only/Locked

A layout file can be marked as read-only (Dashboard > Included Layouts > (right click) > Permissions). If the same file is referenced multiple times (as with the diamond pattern) then only one instance will be editable, and the others will be locked.

ALIAS-DOT-NAME (ADN)

Previously, all panels where identified by a unique panel ID. Now, uniqueness is enforced by combining a panel’s owning layout’s fully qualified alias plus the Panel Id. Same goes for uniquely identifying datamodels and relationships.

SCOPING

Parent layouts have access to the resources of child layouts but child layouts do not have visibility to parent objects. This is an important concept that enforces clean modularization.

CUSTOM AMISCRIPT METHODS & VARIABLE SCOPING

Because a dashboard can incorporate multiple layout files, it’s possible for the same method definition to exist in duplicate. Depending on where the AmiScript is getting executed, the appropriate version of the method will be run. For example, a parent layout could import two child layouts, each with their own onButton() method. Datamodels (or other resources) in child1 calling onButton() will get child1’s method and Datamodels in child2 calling onButton() will get child2’s version of the method. A subtle detail, if the parent layout did not define its own onButton() method and were to call onButton(), it will get the child with the higher priorities version… (See Dashboard > Included Layouts > (right click) > Move Up Higher Priority/Move Down Lower Priority)

AMISCRIPT LAYOUT OBJECT

A new, important Layout class has been introduced, which is used to represent each layout file loaded within the dashboard. The layout variable is automatically visible within AmiScript (like the session variable) and is associated with the layout that the AmiScript is owned by. This is important because it maintains relative consistency when referencing other objects with AmiScript. Note, this has replaced several methods from the session class and when loading old layouts AMI will automatically convert the code to use the layout object instead.

For example, let’s consider a layout B.ami that has two datamodels dm1 and dm2:

B.ami

→dm1

→dm2

Inside dm1, if we want to get access to dm2 we would write:

//I’m inside dm1 Datamodel dm2=layout.getDatamodel(“dm2”);

Say that we have another layout A.ami that includes B.ami with the alias b and has its own datamodel dm0:

A.ami

→dm0

→b

→dm1

→dm2

First, keep in mind the above code will continue to work because its inside dm1 which is owned by layout b so the layout instant represents b. But now, let’s say we want to get dm2 from code inside dm0. We could do either of these:

//I’m inside dm0, all three of these result in same value

Datamodel dm2;

dm2=layout.getChild(“b”).

getDatamodel(“dm2”);

dm2=layout.getDatamodel(“b.dm2”);

dm2=layout.getDatamodel(“b.dm1”).

getLayout().getDatamodel(“dm2”);

The 3rd method is needlessly complex but highlights the relative nature of layouts and resources… We’re grabbing b’s dm1 datamodel. Then because dm1 and dm2 are in the same layout we can simply do getLayout(). getDatamodel(“dm2”) on dm1.

VIRTUAL METHODS

With regards to scoping, it was mentioned that AmiScript within a child layout does not have access to it’s parent’s AmiScript. While generally true, if the layout were to explicitly define a function as virtual and the parent layout were to also define the same method, then the parent’s function will get called instead. In the example below, if we were to call doit() in the child layout, we would see the alerts parent1 and child2 because test1() was marked as virtual, but test2 was not:

Child Layout:

virtual String test1() {
     session.alert(“child1”);
}
String test2() {
     session.alert(“child2”);
}
Object doit() {
     test1();
     test2();
}

Root Layout:

String test1() {
     session.alert(“parent1”);
}
String test2() {
     session.alert(“parent2”);
}

Connecting to an Excel Datasource

Our goal in this tutorial is to import excel data into AMI and create a visualization. In this example we have an Excel spreadsheet, sine.xlsx, with two columns: Degrees and Sine.

1. The first step is to add a new Excel Datasource. In developer mode, click on Dashboard from the menu and open the Data Modeler.

2. Inside the Data Modeler, click on Attach Datasource. This will bring up the Attach Datasource Window. Select the MS Excel icon from the list of available datasource types.

3. In the provided fields, fill out the Name and URL fields. In the Name field, put in the desired name of the new datasource. And in the URL field, provide the full file name (including the path) of the Excel file.

(Warning: prior to adding as a datasource, the Excel file must be closed and saved)

4. The successful addition of the MS Excel datasource will be confirmed with a prompt and the appearance of the Excel datasource in the Data Modeler

(Note: each sheet in the Excel file will be added as a table to the datasource)

5. Double click on the datasource (or right-click and select Add Datamodel to excel) in order to see the tables under the datasource. Select the table and  follow the wizard in order to create a datamodel

6. Once the datamodel is created, we can create a visualization (please refer to GUI > Creating Your First Visualization). In this example, we will create a line chart. In the wizard, select the appropriate variables for the X and Y axis (i.e, X: Degree, Y: Sine)

(Hint: on the right side of the wizard, click Refresh to get a preview of the chart or View Data in order to view the data that is being used)

7. Click Finish in order to create the line chart based on the data in our Excel sheet

AMI WebManager User Guide

The AMI WebManager is a centralized server for deployments with multiple AMI Web Servers. Its purpose is to store and send requested layouts and preferences. The WebManager is used in conjunction with AMI Web Servers or the AMI WebBalancer. See the WebBalancer User Guide for more details.

Setup for AmiWeb Manager

1. Download AMIOne

2. Navigate to the installation directory and open amione/config/local.properties

a. If does not exist local.properties, manually create it in amione/config

3. For a minimal configuration, add the following properties:

# Starts up AMI WebManager

ami.components

Instructions for Using Python with AMI Script

How to load Python Modules in AMI Script

To import python modules, place the import statements inside the python extern block.

By default AMI looks for Python Libraries in the lib/Lib directory of amione.

Alternatively, you can also set the JYTHONPATH environmental variable and AMI will load libraries from there.

{
 CREATE TABLE _TABLE AS USE EXECUTE SELECT TableName, Broadcast, RefreshPeriodMs, SourceTableNames, PersistEngine, OnUndefColumn, DefinedBy FROM __TABLE WHERE ${WHERE};

  double n = 0;
  extern python {{
    import math
    n = math.pow(2,3)
  }};
  session.log(n);
}

How to use Python in AMI Script

Below is an example of how you can pass in variables and tables and modify and return them:

{
 CREATE TABLE inTable AS USE ds=AMI EXECUTE SELECT * FROM __TABLE;
 //INPUT VARIABLES
 String findEngine="TEXT";
 Table inTable=select * from inTable;
 //OUTPUT VARIABLES
 int foundCount;
 Table outTable=new Table("out","Name String");
 //Loop through each row of inTable and add TableName to outTable for records that have a PersistEngine equal to findEngine Variable
 //foundCount is incremented for each record added to outTable
 extern python{{
   foundCount = 0
   for row in inTable.getRows():
     if(row.get("PersistEngine") == "TEXT"):
       outTable.getRows().add(outTable.newRow(row.get("TableName")))
       foundCount+=1
 }};
 create table outTable=outTable;
 session.log("found: "+foundCount);
}

Using JDBC adapter to connect to AMIDB

Sample JDBC connection to AMI Center

import java.sql.*;
public class AmiJdbcSample {
//IMPORTANT NOTE: be sure to include out.jar in your java classpath. The out.jar file is located in the lib folder of your ami installation
    public static final String NEW_LINE = System.getProperty("line.separator");
    public static void main(String a[]) throws SQLException, ClassNotFoundException {
        Class.forName("com.f1.ami.amidb.jdbc.AmiDbJdbcDriver");
        final String url = "jdbc:amisql:localhost:3280?username=demo&password=demo123";
        final Connection conn = DriverManager.getConnection(url);
        try {
            final ResultSet rs = conn. createStatement().executeQuery("select * from __TABLE");
            System.out.println(resultSetToString(rs));
        } finally {
            conn.close();
        }
    }
    public static String resultSetToString(ResultSet rs) throws SQLException {
        final StringBuilder r = new StringBuilder();
        final ResultSetMetaData metaData = rs.getMetaData();
        final int columnCount = metaData.getColumnCount();
        for (int i = 1; i <= columnCount; i++)
            r.append(metaData.getColumnName(i)).append(i == columnCount ? NEW_LINE : "\t");
        while (rs.next())
            for (int i = 1; i <= columnCount; i++)
                r.append(rs.getObject(i)).append(i == columnCount ? NEW_LINE : "\t");
        return r.toString();
    }
}

Using JayDeBeApi - Python JDBC Adapter for AMI

Prerequisites: A jre (Java runtime environment, for JDBC) needs to be installed.

1. Install the JayDeBeApi module.

JayDeBeApi is an adapter of JDBC for python. You can install it using pip:

pip install JayDeBeApi

Alternative ways to install JayDeBeApi: https://pypi.org/project/JayDeBeApi/

2. Start AMI One

3. Connect to amisql from python:

a. You’ll need the path to the out.jar file. This can be found in the ami/amione/lib folder.

b. Find the server hostname and ami.db.jdbc.port (default is 3280).

c. Copy this script, replacing the <placeholders> with appropriate values:

import jaydebeapi

conn =

jaydebeapi.connect( "com.f1.ami.amidb.jdbc.AmiDbJdbcDriver",

"jdbc:amisql:<hostname>:<port>", {"user": "<username>",

"password": "<password>"}, "<path/to/out.jar>")

4. To run queries, create a cursor:

curs = conn.cursor()

5. Queries can then be executed using the execute method:

curs.execute ("show tables")

6. Results are fetched using the fetchall method, which returns a list:

print(curs.fetchall())

7. Close the cursor once finished:

curs.close()

You can also execute queries within a with block for the cursor so you don’t have to worry about closing it:

with conn.cursor() as curs:

curs.execute("show tables")

result = curs.fetchall()

AMI Git Adapter User Guidance

1. Setup
(a). Create an account at https://dev.azure.com/ and initialize a git repository.
(b). Download and unzip the git adapter, then copy and paste its contents into amione/lib.
(c). Inside local.properties , add the following property:

 ami.scm.plugins=com.f1.ami.plugins.git.AmiGitScmPlugin 

(e). To create a connection, go to AMI. Select Account > My Source Control Settings .

2. HTTPS Connection
(a). In AMI, open the Source Control Settings
(b). Select Account > My Source Control Settings > Type > Git , then enter all properties EXCEPT those listed under Advanced .
(c). To obtain the URL, username, and password , go to Azure. Select Repos > Files > Clone > HTTPS > Generate Git Credentials.
(d). Ensure your repo is initialized. The option to initialize is at the end of the page in Repos . Once your repo is initialized, you can obtain the HTTPS.
(e). To specify a branch, go to Advanced > Branch and enter the branch name. The default is the master branch.
(f). Press submit to clone and connect to the repository.
(g). For more information, see the Source Control Properties

3. SSH Connection
(a). Generate a SSH key pair and known_host file.
  (i). To create a key pair, execute ssh-keygen -t rsa in Windows Command Prompt. The default key name id_rsa is the ONLY accepted name for the git adapter.
  (ii). To create a known_host file, execute ssh -v -T git@ssh.dev.azure.com in Windows Command Prompt.

(b). Upload the public key data to Azure
  (i). In Azure, select Repos > Files > Clone > SSH > Manage SSH Keys > New Key
  (ii). Enter id_rsa under Name* and copy-paste the content of id_rsa.pub into Public Key Data*.

(c). In AMI, open the Source Control Settings
  (i). In AMI, select Account > My Source Control Settings > Type > Git.
  (ii). Then, fill in the following : URL, Client, Project Path, SSHKey, and SSHKey Pass .
  (iii) To obtain the URL , go to Azure. Select Repos > Files > Clone > SSH.

(d). Press submit to clone and connect to the repository.
(e). For more information, see the Advanced Control Properties.

4. Adding & Committing Layouts

Status	Tracked	Modified	Changed
	All changes to the layout have been tracked in the repository	Changes to the layout have been tracked locally, but not in the repository	The layout has been added to the commit stage and is ready to be committed to the repository

(a). To commit a layout, go to AMI. Select Dashboard > Included Layouts.
(b). Right click on the layout and select Source Control > Mark For Add.
To revert this, right click and select Source Control > Revert.
(c). Right click and select Source Control > Commit.
Enter a commit message into Comment and press Commit . Doing so will commit and push changes to the connected repository.

Property	Description
URL	HTTPS / SSH URL to the git repository.
Client	Client name, e.g. John Smith
Username	Username generated by Repos > Files > Clone > Generate Git Credentials.
Password	Password generated by Repos > Files > Clone > Generate Git Credentials.
Save Password	Method used to store the password
Project Path	Directory to store and modify the git repository

5. Advanced Control Properties

Property	Description
Branch	Name of the branch to connect to. Default is master
Remote	URL to remote git repository.
SSHKey	Absolute path to the directory where the key pair is stored
SSHKey Pass	Passphrase for the private key
Additional Options