Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Configuring Domains

Info

Note that:

  • domains are used to group Applications together and associate them to a group of users that will manage their delivery (Delivery Manager role).
  • Note that only a user with the Platform Administrator role can configure Domains.
  • Connect to the CAST AIC Portal using the defined URL, for example: http://server:8080/CAST-AICP
  • Login with a user that is a member of a group that has been assigned the Platform Administrator role, for example the "cast" user if you are using "in memory authentication", or another user that is a member of an LDAP group that has been configured with the Platform Administrator role
  • When successfully connected, a list of Domains will be displayed. If this is the first time you have connected to the CAST AIC Portal, the "Default domain" will be the only available domain and will show 0 Apps (Applications) associated to it:

  • You can either add your Applications to this default domain, or you can create a custom domain and add Applications to this new custom domain.

Creating a new domain

  • To create a new domain, click the Register button (if you do not see the Register button, you do not have the Platform Administrator role) and select Register new domain from the drop down list:

  • Enter a name for your new domain (in this example we are creating a domain called "Back Office" to group all our back office Applications together) and click the Register button:

Info
Note that you can configure your Delivery Managers when creating the domain, however, this process is explained separately in 1.2. Delivery Managers and other key participants.
  • Your new domain will be displayed alongside the Default domain and can now be used to register Applications:

Rename or delete an existing domain

  • To rename or delete an existing domain, click the three dots next to a domain name:

  • This will give you the choice of either editing the domain to rename it or deleting the domain entirely:

Info

Note that if you attempt to delete a domain that contains Applications, the following confirmation message will be displayed:

Clicking OK will remove the domain and all its attached Applications. Any instances of the CAST Delivery Manager Tool that refer to an Application that has been deleted will no longer function.

Registering a new domain using the command line

If you want to employ an automated solution to create the domain and assign users and groups to this domain as Delivery Managers, you can do so using a command line tool provided with CAST AIP.

Info
The following instructions are for a Windows environment, but CAST also provides scripts for use on Linux.

JRE requirements

The command line tool requires that a Java JRE has been installed on the machine (at least version 1.6). This should already be the case if you intend to use the CAST Delivery Manager Tool in GUI mode from the CAST AIC Portal.

The tool then 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.

Locate and unzip the tool

  • The tool is provided as a zip archive in the WARS folder at the root of your CAST AIP installation: CAST-AICP-admintools.zip
  • Unzip this archive file and navigate to WARS\CAST-AICP-admintools\CAST-AICP-admintools

Create and configure your batch file

  • 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 registerDomain.bat in your own batch file.
Usage
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:

No Format
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.
-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.

Info
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 1.2. Delivery Managers and other key participants particularly if you are using In Memory Authentication.

-authorizeUsers
-verbosity

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

No Format
[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

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

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

No Format
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

No Format
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

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

Anchor
-authkey option
-authkey option
-authkey option

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

No Format
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:

No Format
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:

No Format
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:

No Format
WARS\CAST-AICP-admintools\CAST-AICP-admintools

Then enter the following:

No Format
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:

Info
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 for the key generatation 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:

No Format
-password cast

with:

No Format
-username cast -authkey u0tjM5qkCZO8IpzrD0CYUw==

Configuring Applications

Info
Note that only a user with the Platform Administrator role can configure Applications.
  • Connect to the CAST AIC Portal using the defined URL, for example: http://server:8080/CAST-AIC
  • Login with a user that is a member of a group that has been assigned the Platform Administrator role, for example the "cast" user if you are using "in memory authentication", or another user that is a member of an LDAP group that has been configured with the Platform Administrator role
  • When successfully connected, a list of Domains will be displayed. If this is the first time you have connected to the CAST AIC Portal, the "Default domain" will be the only available domain and will show 0 Apps (Applications) associated to it.
  • You can either add your Applications to this default domain, or you can create a custom domain and add Applications to this new custom domain (see section above about creating new domains).

Adding Applications to a domain

  • Click the Register button and select Register new Application from the drop down list:

  • A new interface will be displayed allowing you to choose the Domain you want the new Application to be associated to and the name of the new Application:

  • Choose the Domain you want to associate the Application to (in this example we are associating the new Application with the Back Office domain we created earlier):

  • Now enter a name for the new Application and click the Register button when ready:
Info

Note that the Application Name field cannot contain any of the following characters: \ / : * ? " < > |

  • Your new Application will be displayed as follows:

Rename or delete an existing Application

  • To rename or delete an existing Application, click the three dots next to the Application's name (you may need to click the Domain name to "expand" the section in order to view the Applications):

  • This will give you the choice of either editing the Application to rename it or deleting the Application entirely:

Warning

Please note:

  • Deleting the Application will remove all trace of it, i.e. any Versions or Packages that have already been created/delivered will also be removed - this also applies to the CAST Management Studio - i.e. the Application will no longer be available to work on. Any existing instances of the CAST Delivery Manager Tool that refer to an Application that has been deleted will no longer function.
  • After renaming an Application, the Application name will also be updated in all associated tools - the CAST Management Studio and the CAST Delivery Manager Tool. However, to ensure the update is propagated correctly, you must do the following in the CAST Management Studio:
    • Use the File > Save All option (or save your modifications when exiting the CAST Management Studio) to ensure that the new Application name is saved in the Management Service schema
    • Run the Synchronize action manually in the CAST Management Studio (right click the CAST Dashboard Service and select Synchronize) or automatically as part of a another action (such as a snapshot generation) to ensure that the new Application name is saved in the Dashboard Service schema and is therefore displayed correctly in the CAST Application Engineering Dashboard (or the legacy CAST Engineering Dashboard):

    • Click the Upload Snapshots to Measurement Service option in the Application editor > Execute tab) to ensure that the new Application name is saved in the Measurement Service schema and is therefore displayed correctly in the CAST Application Analytics Dashboard:

Moving the Application to a different domain

Info
When moving the Application to another domain, all users belonging to groups assigned to the other domain will gain Delivery Manager rights on the Application you move.
  • To move an existing Application to another domain, click the three dots next to the Application's name:

  • Select the Edit option:

  • Choose the new Domain in the drop down list and clicking Update to make the changes:

Note about invalid Applications

Note that if an Application is deemed "invalid", it is displayed in the CAST AIC Portal in red:

The only option available is to delete the Application.

Info
An Application is generally considered to be invalid if it has been registered in the CAST AIC Portal but does not exist in the Delivery folder.

Registering a new Application using the command line

If you want to employ an automated solution to create the Application, you can do so using a command line tool provided with CAST AIP.

Info
The following instructions are for a Windows environment, but CAST also provides scripts for use on Linux.

JRE requirements

The command line tool requires that a Java JRE has been installed on the machine (at least version 1.6). This should already be the case if you intend to use the CAST Delivery Manager Tool in GUI mode from the CAST AIC Portal.

The tool then 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.

Locate and unzip the tool

  • The tool is provided as a zip archive in the WARS folder at the root of your CAST AIP installation: CAST-AICP-admintools.zip
  • Unzip this archive file and navigate to WARS\CAST-AICP-admintools\CAST-AICP-admintools

Create and configure your batch file

  • 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 registerApplication.bat in your own batch file.
Usage

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:

No Format
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.
-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.

Info
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:

No Format
[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

No Format
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

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