Introduction

How many CAST Application Analytics Dashboards do I need?

CAST highly recommends that you install one CAST Application Analytics Dashboard to display snapshot data from all your Applications whether they are stored in one or multiple Dashboard Services. When configuring the CAST Application Analytics Dashboard, you should therefore:

• Configure a connection to one single Measurement Service (one of the CAST schemas)
• Consolidate data from all your Dashboard Services in this single Measurement Service

Standalone or combined WAR file?

CAST provides the CAST Application Analytics Dashboard in a WAR file that must be deployed to a compatible Application Server (see Supported Platforms for information about Application Server support). However, CAST provides two WAR files that contain the CAST Application Analytics Dashboard, as follows:

You are free to use whichever WAR file you prefer to deploy the CAST Application Analytics Dashboard (the requirements and prerequisites are identical for both WAR files), however if you are using both the CAST Application Analytics and CAST Application Engineering Dashboard, to fulfil (for example) a "risk and quality" use case, then it would make sense to take advantage of the combined CAST-AAD-AED.war file and deploy both dashboards from the same WAR file. If you do so, please note the following about using the "combined" WAR file:

• There is no need to specifically configure a URL for your CAST Application Engineering Dashboard drilldown (via the "microscope" icon)  - see 2.2.3. Snapshot generation and validation for more information: when using the combined "WAR" file, access to the CAST Application Engineering Dashboard from the CAST Application Analytics Dashboard is pre-configured.
• Security access and authentication is common to both Dashboards. Therefore, if you setup Active Directory authentication, then this must be used to access both Dashboards - you cannot use "Static List" for one Dashboard and "Active Directory" for the other.
• Role configuration is common to both Dashboards. Therefore "UserA" that has been granted the "admin" role, will have the "admin" role in both Dashboards.
• Data authorization is common to both Dashboards. Therefore if you authorize "UserA" to view Application "B" only via the authorizations.xml file, then this is true for both Dashboards. Note that authorizations based only on Tags and Categories created for the CAST Application Analytics Dashboard (Tags and Categories are a feature that is not available in the CAST Application Engineering Dashboard) WILL be applied in the CAST Application Engineering Dashboard when using the combined war file.
• Group configuration is common to both Dashboards, regardless of the authentication mode in use. Therefore if you authorize "GroupD"  to view Application "E" only, then this is true for both Dashboards.
• On login, the user will be presented with a choice of Dashboard as shown below (Image 1) in a "Welcome" page. Clicking Access will take the user to the custom login screen for the chosen Dashboard where a "Return to welcome page" URL is available if the user wishes to login to the other Dashboard (Image 2):

Image 1 - Welcome page

Image 2 - Return to welcome page URL

Requirements

Installing the CAST Application Analytics Dashboard (CAST AAD) requires the following:

	Java JRE	Must be installed on the machine that will host the Application Server. Please see Supported Platforms about JRE support.
	Application Server	Must be installed on a compatible machine. Please see Supported Platforms about Application Server support.
	Web browser	Required for accessing the CAST Application Analytics Dashboard. Please see Supported Platforms about Web Browser compatibility.
	Measurement Service	A dedicated schema (the CAST Measurement Service) on a CAST Storage Service 2. To ensure compatibility you must only use a Measurement Service installed with a version of CAST AIP that exactly matches the major, minor or Service Pack release number of the CAST AAD WAR that you are installing. No other RDBMS is supported for the Measurement Service. You may need to install a standalone Measurement Service on a CAST Storage Service 2 (see Install CAST schemas) for example: you have installed only a "triplet" of CAST schemas (i.e. Management/Analysis/Dashboard Services) you have migrated from a previous version of CAST AIP where CAST Measurement Services were not in use (typically CAST AIP 7.0.x) your Management/Analysis/Dashboard Services are installed on Microsoft SQL Server / Oracle Server (which do NOT support the installation of a Measurement Service) you want to install multiple CAST Application Analytics Dashboards Measurement Services can be Active for multiple Management Services (and thus data from multiple Dashboard Services can be aggregated in one Measurement Service).
	Dashboard Service(s)	You can consolidate data into the Measurement Service from any number of Dashboard Service schemas (subject to the limit of 200 applications). The following Dashboard Services are supported: CAST Dashboard Services AIP release Supported 8.2.x 8.1.x 8.0.x 7.3.x 7.2.x 7.1.x 7.0.x Host CSS/RDBMS All supported CSS/RDBMS platforms
	WAR file	The CAST Application Analytics Dashboard is provided as a .WAR file (CAST-AAD.war) - it can be retrieved from the WARS folder located in the CAST installation folder:

Pre-installation check list

Before beginning the installation process, please ensure that you have carried out all of the following tasks and that the following requirements have been met:

Installation procedure

The installation process is divided into various steps:

Step 1: Deploy and configure the CAST-AAD.war file on your application server

Deploy the WAR file

Locate the CAST-AAD.war file and move it to the web application installation location. By default on Apache Tomcat this is set to:

%CATALINA_HOME%\webapps

• If the Apache Tomcat server is running, the .WAR file will then be unpacked and deployed in a folder called "CAST-AAD".
• Once deployed you now need to configure the context.xml file to tell the web application where the Measurement Service is stored. This file is located here:

%CATALINA_HOME%\webapps\CAST-AAD\META-INF\context.xml

Instructions for Tomcat 7

If you are using Tomcat 7 to host the CAST Application Analytics Dashboard, please follow these instructions:

• Open the context.xml file (as detailed above) with a Text editor.
• By default, the file will contain an uncommented template as follows - this is tailored for connections to CAST schemas located on CAST Storage Service 2 using Tomcat 7:

<Resource name="jdbc/domains/AAD" url="jdbc:postgresql://localhost:2280/postgres"
    initConnectionSqls="SET search_path TO [Measure Schema];"
    username="operator" password="CastAIP" 

    auth="Container" type="javax.sql.DataSource" driverClassName="org.postgresql.Driver"
    validationQuery="select 1"
    initialSize="5" maxActive="20" maxIdle="10" maxWait="-1"/>

• Set the URL parameter to the server on which the Measurement Service is located (usually you just need to alter the "localhost" to the name of the server on which the host CSS is located).
• Change [Measure Schema] to the name of the Measurement Service (see Install CAST schemas).
• Ensure the username and password parameters are correct (note that if you need to encrypt the username and password to avoid entering names in clear text, please see: CAST-AAD-AED - Encrypt login and password for datasource and Active Directory)
• You should end up with a section like this:

<Resource name="jdbc/domains/AAD" url="jdbc:postgresql://NEFYN:2280/postgres"
    initConnectionSqls="SET search_path TO V80_MEASURE_CSS2;"
    username="operator" password="CastAIP"

    auth="Container" type="javax.sql.DataSource" driverClassName="org.postgresql.Driver"
    validationQuery="select 1"
    initialSize="5" maxActive="20" maxIdle="10" maxWait="-1"/>

• Following any changes you make, save the context.xml file and then restart your application server so that the changes are taken into account.

Instructions for Tomcat 8 and 8.5

If you are using Tomcat 8 or 8.5 to host the CAST Application Analytics Dashboard, please follow these instructions:

• Open the context.xml file (as detailed above) with a Text editor.
• By default, the file will contain an uncommented template as follows - this is tailored for connections to CAST schemas located on CAST Storage Service 2 using Tomcat 7:

<Resource name="jdbc/domains/AAD" url="jdbc:postgresql://localhost:2280/postgres"
    initConnectionSqls="SET search_path TO [Measure Schema];"
    username="operator" password="CastAIP" 

    auth="Container" type="javax.sql.DataSource" driverClassName="org.postgresql.Driver"
    validationQuery="select 1"
    initialSize="5" maxActive="20" maxIdle="10" maxWait="-1"/>

• You need to comment this template by adding <!-- and --> around the section:

<!--
<Resource name="jdbc/domains/AAD" url="jdbc:postgresql://localhost:2280/postgres"
    initConnectionSqls="SET search_path TO [Measure Schema];"
    username="operator" password="CastAIP" 

    auth="Container" type="javax.sql.DataSource" driverClassName="org.postgresql.Driver"
    validationQuery="select 1"
    initialSize="5" maxActive="20" maxIdle="10" maxWait="-1"/>
-->

• Now locate the Tomcat 8 template for CAST Storage Service 2 - this is located at the top of the following section:

<!--  For Tomcat 8 : http://tomcat.apache.org/tomcat-8.0-doc/jndi-datasource-examples-howto.html & http://commons.apache.org/proper/commons-dbcp/configuration.html

template for resources on CSS :
<Resource name="jdbc/domains/${domainName}" 
        url="jdbc:postgresql://${host}:${port}/postgres"
        connectionInitSqls="SET search_path TO ${schema};"
        username="${user}" password="${password}" 

        auth="Container" type="javax.sql.DataSource" driverClassName="org.postgresql.Driver"
        validationQuery="select 1" initialSize="5" maxTotal="20" maxIdle="10" maxWaitMillis="-1"/>

template for resources on Oracle :            
<Resource name="jdbc/domains/{domainName}"
        url="jdbc:oracle:thin:@{server}:{port}:{instance}"
        connectionInitSqls="ALTER SESSION SET CURRENT_SCHEMA={schema}"
        username="{user}"   password="{password}"

        auth="Container" type="javax.sql.DataSource" driverClassName="oracle.jdbc.OracleDriver"
        validationQuery="select 1 from DUAL" initialSize="5" maxTotal="20" maxIdle="10" maxWaitMillis="-1" />

template for resources on MS SQL Server :
<Resource name="jdbc/domains/{domainName}"
        url="jdbc:jtds:sqlserver://{host};instance={instance}"
        connectionInitSqls="use {database}"
        username="{user}" password="{password}"

        auth="Container" type="javax.sql.DataSource" driverClassName="net.sourceforge.jtds.jdbc.Driver"
        validationQuery="select 1" initialSize="5" maxTotal="20" maxIdle="10" maxWaitMillis="-1"/>
-->

• Copy the CSS2 template into uncommented white space:

<Resource name="jdbc/domains/${domainName}" 
        url="jdbc:postgresql://${host}:${port}/postgres"
        connectionInitSqls="SET search_path TO ${schema};"
        username="${user}" password="${password}" 

        auth="Container" type="javax.sql.DataSource" driverClassName="org.postgresql.Driver"
        validationQuery="select 1" initialSize="5" maxTotal="20" maxIdle="10" maxWaitMillis="-1"/>

• Set the ${domainName} value to AAD
• Set the URL parameter to the server on which the Measurement Service is located (usually you just need to alter the ${host} and ${port} values to the name/port of the server on which the host CSS is located).
• Change ${schema} to the name of the Measurement Service (see Install CAST schemas).
• Ensure the ${user} and ${password} parameters are correct - use the operator and CastAIP username/password combination (note that if you need to encrypt the username and password to avoid entering names in clear text, please see: CAST-AAD-AED - Encrypt login and password for datasource and Active Directory)
• You should end up with a section like this:

<Resource name="jdbc/domains/AAD" 
        url="jdbc:postgresql://NEFYN:2280/postgres"
        connectionInitSqls="SET search_path TO V80_MEASURE_CSS2;"
        username="operator" password="CastAIP" 

        auth="Container" type="javax.sql.DataSource" driverClassName="org.postgresql.Driver"
        validationQuery="select 1" initialSize="5" maxTotal="20" maxIdle="10" maxWaitMillis="-1"/>

• Following any changes you make, save the context.xml file and then restart your application server so that the changes are taken into account.

Test access to the CAST Application Analytics Dashboard

• You can now test that the CAST Application Analytics Dashboard has been deployed using the URL:

http://<server_name>:[<port_number>]/CAST-AAD

• You should see the login page as follows:

Step 2: Configure user authentication

Step 2 involves configuring how your users will authenticate with the CAST Application Analytics Dashboard. Most organizations opt for LDAP/Active Directory integration so that users can use their corporate username/password to access the resources they need. The CAST Application Analytics Dashboard also has a built in username/password authentication mechanism which is enabled "out of the box".

Please see Configuring user authentication for more information.

Step 3: upload snapshot data for display in AAD

Before your users can view any data in the CAST Application Analytics Dashboard, you need to upload your snapshot data once it has been generated (see Application Analysis and Measurement with CAST AIP for more information). The snapshot upload is achieved using the CAST Management Studio.

A - Activate the Measurement Service

Before you can upload snapshot data, you must ensure that the Measurement Service is Active for your current Management Service (i.e. the Management Service you are connected to in the CAST Management Studio). Measurement Services can be Active for multiple Management Services (and thus data from multiple Dashboard Services can be uploaded).

Installation of CAST AIP with Combined Install option

If:

• you have installed this version of CAST AIP from scratch using the Combined Install option "Application Analytics platform installation" in CAST Server Manager
• OR you have upgraded from a previous version of CAST AIP where you were actively using the CAST Application Analytics Dashboard (any release of CAST AIP above and including 7.3.x)

...then a Measurement Service will have been installed alongside the Management, Analysis and Dashboard Services and will be visible in the Services view in the CAST Management Studio. In this case, the Measurement Service will already be Active and you do not need to do anything else:

Standalone Measurement Service

If:

• you have upgraded from a previous version of CAST AIP where the CAST Application Analytics Dashboard was not available (any release of CAST AIP prior to, but not including, 7.3.x)
• OR your Management/Analysis and Dashboard Services are installed on Microsoft SQL Server / Oracle Server (which do NOT support the installation of a Measurement Service)

you will have therefore installed a standalone Measurement Service on CSS2 in order to use the CAST Application Analytics Dashboard. In this scenario, you will need to activate this service before you do anything else:

• Open the CAST Management Studio and move to Services view.
  
  • In the case of a migration from a previous version of CAST - if your Measurement Service is installed on the same server (i.e. CSS2) as the Management/Analysis/Dashboard Service, select the server hosting the CAST Management Service (_MNGT) and choose Services > Discover to locate the standalone Measurement Service:

• • If your Management/Analysis/Dashboard Services are installed on Microsoft SQL Server/Oracle Server and the Measurement Service on CSS2, then you will need to add the CAST Storage Service entry:
    • by clicking the appropriate icon:

• • • and then defining the connection parameters in its editor:

• Select the newly defined server and choose Services > Discover.

• In both cases, the standalone Measurement Service will then be displayed:

• Next double click the Measurement Service in the Services view to edit it.

• The Active for the current Management Service field will display "No" as shown above.
• Click Activate.
• If you already have an Application or Applications in the CAST Management Studio, you will be prompted to choose whether you want to upload the data for all the snapshots that have been generated for the given Application(s). If you do not want to upload data for a specific Application, ensure that you untick the relevant Application(s):

• Click Finish to proceed - the upload process will then begin:

B - Uploading snapshot data when the Measurement Service is active

When the Measurement Service is Active, there are two ways to upload snapshot data to the Measurement Service:

• automatic (at the same time as you generate a snapshot)
• manual (if you choose not to upload the snapshot data when the snapshot is generated).

You can find out more information about these options in 2.2.3. Snapshot generation and validation.

Step 4: Configure data authorization

Step 4 involves configuring data Authorization. An authorization defines permission to a user or group of users to access and "consume the data" in a specific Application in the CAST Application Analytics Dashboard. If permission is not granted then any information related to this Application will be not accessible: application properties such as name, technologies or grades and measures, etc.Therefore, an Authorization must be defined before a user/group of users can access a specific application.

Please see Configuring data authorization for more information.

Additional information

You can find additional information about advanced configuration changes in CAST Application Analytics Dashboard such as:

You can find additional information about advanced security configuration changes for the CAST Application Analytics Dashboard, such as:

There is also additional information about implementing an enhanced security configuration for your application server in Common security configuration options for web application deployment: