Page tree
Skip to end of metadata
Go to start of metadata

This documentation is no longer maintained and may contain obsolete information. You should instead refer to https://github.com/CAST-Extend/com.castsoftware.aip.console.tools for more information about automating source code delivery/analysis with AIP Console.

In this section:

Target audience:

  • CAST administrators
Summary: This section of documentation provides an explanation of how to register domains and applications in the CAST AIC Portal in an automated and repeatable way.

Introduction

The registration of domains and applications is achieved using the web based CAST AIC Portal as explained in Register the Application in the CAST AIC Portal.

If you need to automate these tasks, then you can do so by using the CLI (Command Line Interface) provided with the CAST AIC Portal. This document explains how.

Prerequisites

Before you can starting using the CAST AIC Portal CLI, you must ensure that you meet the following requirements:

(tick)An installation of the CAST AIC Portal is required - please see Installing and configuring the CAST AIC Portal.
(tick)A CAST Server Manager connection profile specifying the target RDBMS/CSS must already exist.
(tick)The command line tool requires that a Java JRE has been installed on the machine (at least version 1.6) from which you will run the CLI.
(tick)

The command line tool requires that:

  • either a %JAVA_HOME% system environment variable exists on the machine pointing to the installation folder of your JRE (for example: C:\Program Files (x86)\Java\jre7)
  • or that the JRE's bin folder is referenced in the PATH system environment variable (for example: C:\Program Files (x86)\Java\jre7\bin)

If neither of the above are true, a message will be displayed explaining this when you attempt to run the tool.

(tick)Please ensure that you have the CLI tool on he machine from which you will run the CLI. The CLI tool is provided as a zip archive in the WARS folder at the root of your CAST AIP installation: CAST-AICP-admintools.zip
(tick)The command line tool requires that you use a CAST AIC Portal login that has the Platform Administrator role. Please see CAST AIC Portal - Configuring user authentication for more information.
(tick)The following instructions are for a Windows environment only.
(tick)If your Apache Tomcat web application server is configured for secure https access, ensure that a trusted CA (Certificate Authority) SSL certificate is installed, rather than a self-signed certificate.

What can the CLI do?

The CAST AIC Portal can do the following:

  • Register a new Domain in the CAST AIC Portal and optionally grant the Delivery Manager role to groups and/or usernames for the new Domain (and therefore all its Applications)
  • Register a new Application in a specific Domain in the CAST AIC Portal
  • Register an existing Application - this is a special option: in some circumstances (for example you want to move an Application from a staging to a production environment), you may need to move an Application that has already been on-boarded in Delivery folder "A" used by CAST AIC Portal "A" and move it (and any delivered source code) to Delivery folder "B" used by CAST AIC Portal "B".

First steps

To use the CAST AIC Portal CLI:

  • Unzip the CAST-AICP-admintools.zip archive file and navigate to WARS\CAST-AICP-admintools\CAST-AICP-admintools
  • Create a new .bat batch file in the WARS\CAST-AICP-admintools\CAST-AICP-admintools - the batch file can be called anything
  • Create your command line in the .bat batch file using the parameters listed below. You must call the preprepared .BAT files (registerDomain.bat / registerApplication.bat / registerExistingApplication.bat) in your own batch file.

RegisterDomain.bat

Register a new Domain in the CAST AIC Portal and optionally grant the Delivery Manager role to groups and/or usernames for the new Domain (and therefore all its Applications):

registerDomain.bat -serverUrl %SERVER_URL% -username %USER_NAME% -password %USER_PWD% -verbosity %LOG_VERBOSITY% -authorizeGroups "%GROUPS%" -authorizeUsers "%USERS%" "%DOMAIN_NAME%"
OptionsDescription
-serverUrl

Required: enter the URL you use to access the CAST AIC Portal in which you want to create the new domain, for example:

http://server:8080/CAST-AICP

Note that you must omit the trailing forward slash ( / ) at the end of the URL.

-usernameRequired: enter the username to access the CAST AIC Portal. The user name must have the Platform Administrator role in order to be able to create a new Domain. Please see CAST AIC Portal - Configuring user authentication for more information.
-passwordRequired unless the -authkey option is present: enter the password that corresponds to the username you entered. This password is passed in clear text - if you need to enter an encrypted password, please use the -authkey parameter instead.
-authkey

Required unless the -password option is present: enter the authentication key that you have generated for the clear text password that corresponds to the username you entered. You can use the -password option instead if you do not need to use an encrypted password.

See the -authkey section for more information about how to use this.
-authorizeGroups

Optional: these two options enable you to grant the Delivery Manager role to groups and/or usernames for the new Domain (and therefore all its Applications). If you want to add multiple groups and multiple users, they must be separated with a semi-colon ( ; ):

  • corp.delivery.company;corp.admins.company
  • JHU;FRA;LWI

You are not obliged to use these options when you create the Domain, however, if you do, you must follow the instructions located in Configure the Delivery Manager role particularly if you are using Default Authentication.

-authorizeUsers
-verbosity

Optional: use this option to change the verbosity of the output. The default setting is error:

[debug|info|warn|error|off ]

Error status codes

JRE_NOT_FOUNDJava runtime not found. Please define the JAVA_HOME environment variable or put java.exe into your execution path
DYSFUNCTIONThe software had an unexpected dysfunction
INVALID_COMMANDThe command's syntax is not correct
SERVER_NOT_AVAILABLEThe CAST AIC Portal specified by the provided URL does not respond
INVALID_URLThe provided URL is invalid
INVALID_CREDENTIALSCould not authenticate with the provided credentials
NOT_PERMITTEDThe account with the provided credentials is not permitted to perform the operation
INVALID_NAMEThe provided name is invalid: it is empty or it is too long or it contains forbidden characters
DUPLICATEThe operations violates a uniqueness constraint
INVALID_GUIDThe provided GUID is invalid
DOMAIN_NOT_FOUNDThe referenced domain cannot be found
INVALID_AUTH_KEYInvalid authentication key
INVALID_DELIVERY_MANAGERSThe provided list of delivery managers is invalid: at least one name is empty or it is too long or it contains forbidden characters

Examples

The following are example command lines:

Register a new domain called "Test Domain" using clear text password

registerDomain -serverUrl http://server:8080/CAST-AICP -username cast -password cast "Test Domain"

Register a new domain called "Test Domain" using authentication key password

registerDomain -serverUrl http://server:8080/CAST-AICP -username cast -authkey u0tjM5qkCZO8IpzrD0CYUw== "Test Domain"

Register a new domain called "Test Domain" using clear text password and assigning groups as Delivery Managers

registerDomain -serverUrl http://server:8080/CAST-AICP -username cast -password cast "Test Domain" -authorizeGroups corp.delivery.company;corp.admin.company

Register a new domain called "Test Domain" using clear text password and assigning groups and users as Delivery Managers

registerDomain -serverUrl http://server:8080/CAST-AICP -username cast -password cast "Test Domain" -authorizeGroups corp.delivery.company;corp.admin.company -authorizeUsers JHU;FRA;LWI

RegisterApplication.bat

Register a new Application in a specific Domain in the CAST AIC Portal:

registerApplication.bat -serverUrl %SERVER_URL% -username %USER_NAME% -password %USER_PWD% -verbosity %LOG_VERBOSITY% -domain "%DOMAIN_NAME%" "%APPLICATION_NAME%"
OptionsDescription
-serverUrl

Required: enter the URL you use to access the CAST AIC Portal in which you want to create the new Application, for example:

http://server:8080/CAST-AICP

Note that you must omit the trailing forward slash ( / ) at the end of the URL.

-usernameRequired: enter the username to access the CAST AIC Portal. The user name must have the Platform Administrator role in order to be able to create a new Application. Please see CAST AIC Portal - Configuring user authentication for more information.
-passwordRequired unless the -authkey option is present: enter the password that corresponds to the username you entered. This password is passed in clear text - if you need to enter an encrypted password, please use the -authkey parameter instead.
-authkey

Required unless the -password option is present: enter the authentication key that you have generated for the clear text password that corresponds to the username you entered. You can use the -password option instead if you do not need to use an encrypted password.

See the -authkey section for more information about how to use this.
-domainRequired: specify the name of the domain to which you want to associate the new Application. This domain must already exist.
-verbosity

Optional: use this option to change the verbosity of the output. The default setting is error:

[debug|info|warn|error|off ]

Error status codes

JRE_NOT_FOUNDJava runtime not found. Please define the JAVA_HOME environment variable or put java.exe into your execution path
DYSFUNCTIONThe software had an unexpected dysfunction
INVALID_COMMANDThe command's syntax is not correct
SERVER_NOT_AVAILABLEThe AIC Portal specified by the provided URL does not respond
INVALID_URLThe provided URL is invalid
INVALID_CREDENTIALSCould not authenticate with the provided credentials
NOT_PERMITTEDThe account with the provided credentials is not permitted to perform the operation
INVALID_NAMEThe provided name is invalid: it is empty or it is too long or it contains forbidden characters
DUPLICATEThe operations violates a uniqueness constraint
INVALID_GUIDThe provided GUID is invalid
DOMAIN_NOT_FOUNDThe referenced domain cannot be found
INVALID_AUTH_KEYInvalid authentication key
INVALID_DELIVERY_MANAGERSThe provided list of delivery managers is invalid: at least one name is empty or it is too long or it contains forbidden characters

Examples

The following are example command lines:

Register a new Application called "Test Application" associated to the domain "Back Office" using clear text password

registerApplication -serverUrl http://server:8080/CAST-AICP -username cast -password cast -domain "Back Office" "Test Application"

Register a new Application called "Test Application" associated to the domain "Back Office" using authentication key password

registerApplication -serverUrl http://server:8080/CAST-AICP -username cast -authkey u0tjM5qkCZO8IpzrD0CYUw== -domain "Back Office" "Test Application"

RegisterExistingApplication.bat

In some circumstances (for example you want to move an Application from a staging to a production environment), you may need to move an Application that has already been on-boarded in Delivery folder "A" used by CAST AIC Portal "A" and move it (and any delivered source code) to Delivery folder "B" used by CAST AIC Portal "B". The process of doing so is described in this page.

Things you need to know

  • You cannot move an Application to a CAST AIC Portal/Delivery folder that is installed with a different major/minor release of CAST AIP (i.e. from CAST AIP 8.0.0 to CAST AIP 8.1.0) nor to a CAST AIC Portal/Delivery folder that is installed with a different Service Pack release (CAST AIP 8.0.1 to CAST AIP 8.0.2). You must only move an Application between installations of identical CAST AIP releases.
  • The process will move the Application and any delivered source code, but it will not move deployed source code, nor will it move snapshot data/analysis results/analysis configuration.
  • If the Application you wish to copy uses any CAST AIP Extensions, you must ensure that these are installed BEFORE your Delivery Managers start to deliver source code for the Application after the copy process has completed.

Note that this process assumes that:

  • the Application has already been registered in a CAST AIC Portal, and that at least one Version and associated Packages have been delivered.
  • the source and target CAST AIC Portals/Delivery folders are associated with different Management Service schemas.

Step 1 - Identify the Application

  • First you need to identify the Application you want to move: find its name either in the CAST Management Studio or in the CAST AIC Portal.
  • Now navigate to the data folder in the Delivery folder in which the Application is currently stored:

  • Open the index.xml file located at the root of this data folder with a text editor and search for the name of the Application you want to move - for this example the Application is called "MEUDON" highlighted in blue:

  • You then need to identify the Application's GUID - this is highlighted in the above image in a red box. This GUID will enable you to copy the correct Application data.

Step 2 - Copy the Application to the new Delivery folder

  • Now that you have identified the Application's GUID (f9c4b55d-255f-4c3c-b83c-ac02bebc51b4 in this example), you can copy the relevant folder and files over to the new Delivery folder.
  • In the data folder in the Delivery folder in which the Application is currently stored, copy the following items:
ItemDescription
Folder named <GUID>Contains the configuration files and folder for all Versions and Packages that belong to the Application, as well as any Delivered source code.
File named <GUID>.entity.xmlContains configuration information for the Application.
  • In our example, there are two Applications in the Delivery\data folder. We will copy the highlighted items that are relevant only to the Application named "MEUDON":

  • Now copy the items to the new Delivery folder, placing them in the data subfolder - in this example, the new Delivery folder is empty (i.e. no Applications have been created in it yet):

  • If you now open the CAST AIC Portal that uses the target Delivery folder and login, you will see that there are no Applications registered yet, even though you have copied across the relevant files:

  • You now need to handle the index.xml file located at the root of the data subfolder.

Step 3 - Handle the index.xml file

You now need to handle the index.xml file located at the root of the data subfolder so that the CAST AIC Portal is aware that the Application exists.

If the Delivery\data folder already contains an index.xml file

If the new Delivery\data subfolder already contains an index.xml file (this file will be present if the new Delivery\data folder already contains other existing Applications), you need to edit this index.xml file and add in the information relevant to the Application you have copied.

  • Edit the Delivery\data\index.xml file (for the new Delivery folder). In the example below, we can see that one other Application is already referenced (SEVRES):

  • Now open the Delivery\data\index.xml file (for the OLD Delivery folder where the Application was located originally) and copy all lines that mention the Application's GUID, as highlighted below:

  • Now paste the copied lines into the Delivery\data\index.xml file (for the new Delivery folder), below any references to existing applications as shown below:

  • Save the index.xml file.
  • You now need to register the Application in a Domain so that it is displayed correctly in the CAST AIC Portal (see Step 4).

If the Delivery\data folder does not contain an index.xml file

If the new Delivery\data subfolder does not contain an index.xml file (this file will only be present if the new Delivery\data folder already contains other existing Applications), you need to create a new index.xml file that references the Application you have copied. The simplest way to do this is to re-use the Delivery\data\index.xml file (for the OLD Delivery folder where the Application was located originally) and remove any references to other Applications.

  • Copy the Delivery\data\index.xml file (for the OLD Delivery folder where the Application was located originally) to Delivery\data (for the new Delivery folder)
  • Edit the Delivery\data\index.xml file (for the new Delivery folder) and remove references to any other Applications leaving just the lines relevant to the Application you have copied. In this example, there is one other Application called SEVRES that we will remove (highlighted in blue) leaving just the lines for the MEUDON Application we have copied:

  • This will leave you with an index.xml file like this:

  • Save the index.xml file.
  • You now need to register the Application in a Domain so that it is displayed correctly in the CAST AIC Portal (see Step 4).

Step 4 - Register the Application using the command line tool registerExistingApplication.bat

You now need to register the Application in a Domain so that it is displayed correctly in the CAST AIC Portal.

registerExistingApplication.bat -serverUrl %SERVER_URL% -username %USER_NAME% -password %USER_PWD% -verbosity %LOG_VERBOSITY% -domain "%DOMAIN_NAME%" "%APPLICATION_GUID%"
OptionsDescription
-serverUrl

Required: enter the URL you use to access the CAST AIC Portal in which you want to register the existing Application, for example:

http://server:8080/CAST-AICP

Note that you must omit the trailing forward slash ( / ) at the end of the URL.

-usernameRequired: enter the username to access the CAST AIC Portal. The user name must have the Platform Administrator role in order to be able to register and existing Application. Please see CAST AIC Portal - Configuring user authentication for more information.
-passwordRequired unless the -authkey option is present: enter the password that corresponds to the username you entered. This password is passed in clear text - if you need to enter an encrypted password, please use the -authkey parameter instead.
-authkey

Required unless the -password option is present: enter the authentication key that you have generated for the clear text password that corresponds to the username you entered. You can use the -password option instead if you do not need to use an encrypted password.

See the -authkey section for more information about how to use this.
-domainRequired: specify the name of the domain to which you want to associate the existing Application. This domain must already exist.
-verbosity

Optional: use this option to change the verbosity of the output. The default setting is error:

[debug|info|warn|error|off ]

Error status codes

JRE_NOT_FOUNDJava runtime not found. Please define the JAVA_HOME environment variable or put java.exe into your execution path
DYSFUNCTIONThe software had an unexpected dysfunction
INVALID_COMMANDThe command's syntax is not correct
SERVER_NOT_AVAILABLEThe AIC Portal specified by the provided URL does not respond
INVALID_URLThe provided URL is invalid
INVALID_CREDENTIALSCould not authenticate with the provided credentials
NOT_PERMITTEDThe account with the provided credentials is not permitted to perform the operation
INVALID_NAMEThe provided name is invalid: it is empty or it is too long or it contains forbidden characters
DUPLICATEThe operations violates a uniqueness constraint
INVALID_GUIDThe provided GUID is invalid
DOMAIN_NOT_FOUNDThe referenced domain cannot be found
INVALID_AUTH_KEYInvalid authentication key
INVALID_DELIVERY_MANAGERSThe provided list of delivery managers is invalid: at least one name is empty or it is too long or it contains forbidden characters
"%APPLICATION_GUID%"Enter (between double quote marks) the GUID of the Application you have copied and now want to register.

Examples

The following are example command lines:

Register a copied existing Application with a GUID "f9c4b55d-255f-4c3c-b83c-ac02bebc51b4" and associate it to the the domain "TEST" using clear text password

registerExistingApplication.bat -serverUrl http://server:8080/CAST-AICP -username cast -password cast -verbosity debug -domain "TEST" "f9c4b55d-255f-4c3c-b83c-ac02bebc51b4"

Register a copied existing Application with a GUID "f9c4b55d-255f-4c3c-b83c-ac02bebc51b4" and associate it to the the domain "TEST" using authentication key password

registerApplication -serverUrl http://server:8080/CAST-AICP -username cast -authkey u0tjM5qkCZO8IpzrD0CYUw== -domain "TEST" "f9c4b55d-255f-4c3c-b83c-ac02bebc51b4"

Check the process has completed

  • If you now open the CAST AIC Portal that uses the target Delivery folder and log in, you will see that the Application should now be visible and associated to the required Domain:

Note that in order for Delivery Managers to be able to deliver source code for this Application, you may need to configure Users/Groups on the domain to which you have associated the copied Application. Please see Configure the Delivery Manager role for more information.

-authkey option

When using the command line, you can pass the password in clear text as follows:

registerDomain -serverUrl http://server:8080/CAST-AICP -username cast -password cast "Test Domain"

However, in a secure environment, clear text passwords may not be acceptable. For improved security, CAST recommends using an encrypted password and has therefore provided a method to encrypt the password and then enter the encrypted password into the command line using the -authkey parameter in place of the -password parameter as follows:

registerDomain -serverUrl http://server:8080/CAST-AICP -username cast -authkey u0tjM5qkCZO8IpzrD0CYUw== "Test Domain"

The -authkey parameter requires a string of characters derived from the user's password by cryptographic means, in order to prevent the password from being exposed in clear-text. An authkey generation tool, named authkeygen.bat (this is in fact a batch file that is run via a CMD window), is provided with the CAST Delivery Manager Tool, located in the same folder as the register batch files:

WARS\CAST-AICP-admintools\CAST-AICP-admintools

Note that an authkeygen.sh tool also exists for Linux environments.

Generating an encryption key

To generate an encryption key, please open a command prompt and navigate to the following location:

WARS\CAST-AICP-admintools\CAST-AICP-admintools

Then enter the following:

authkeygen

The tool will then prompt you for the password to encrypt:

Enter the password you want to encrypt, then tap ENTER. The resulting encryption key value is displayed preceded by authkey:

Note that the encryption key generation process is host and user login dependent: i.e. an encryption key is only valid on the same host and with the same machine user login as have been used for the key generation process. In other words, you must run the registerDomain and registerApplication commands on the same machine and with the same user login as was used to generate the encryption key.

Using the encryption key

When the encryption key has been generated, simply replace the following lines in your batch file:

-password cast

with:

-username cast -authkey u0tjM5qkCZO8IpzrD0CYUw==
  • No labels