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:

First steps

To use the CAST AIC Portal CLI:

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

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

Step 2 - Copy the Application to the new Delivery folder

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.

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.

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.

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

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==