Plug-in Documentation

IBM UrbanCode PHP CLI Tool

Overview

UrbanCode PHP CLI is a tool that combines udclient CLI tool and uDeploy REST APIs to run batch operation such as, but not limited to, backup and restore of components and applications.

The tool has been designed to run a list of basic functions that run out of the box, but also provides a low level implementation that helps developers to create custom scripts.

To work correctly, UrbanCode PHP CLI requires:

  • Linux environment and shell
  • PHP 5+
  • IBM java 1.6.0
  • curl

Note: UrbanCode PHP CLI should run by a user with read, write and execute permission on UrbanCode PHP CLI folder and with execute permission from command line on the programs listed above.

Usage

Run an application process

To simply request an application process, just use the run entry point followed by the path of the file including the information of the application process you want to run.
Heres an example of how a JSON file for application process request should look like:

{
application: ,
applicationProcess: ,
description: ,
environment: ,
onlyChanged: ,
post-deploy-message: ,
snapshot:
}

Once you have your JSON file ready, you can request the application process by running

php uCommand.php run application_process.json

This entry point will print in the console the ID and link of the process request:

php uCommand.php run application_process.json

##################################
# UrbanCode PHP CLI #
# Urban Code Deploy PHP CLI Tool #
# by SalesConnect Dublin #
##################################

[INFO] Default output to: /home/csitadmin/Documents/uCommand/backups

[ID] 6916dd6f-d061-4c07-9071-2db64bcaaa29
[LINK] https://myUrbanCodeServer:8443/#applicationProcess/6916dd6f-d061-4c07-9071-2db64bcaaa29

Promote a snapshot

The promotion of a snapshot is the process of copying a snapshot from an origin UrbanCode Deploy server to a destination UrbanCode Deploy server, including all component versions and artifacts, specified in the snapshot to be promoted.

Prerequisites
In order to successfully promote a snapshot, on the destination UrbanCode Deploy server all the followings are needed:

  • All components listed in the snapshot
  • The target application for the snapshot should have the same name of the origins one
  • All components listed in the snapshot are associated to the application
  • A snapshot with the same name of the one we want to promote has not already been created

If any of the cases listed above fails, the promotion of the snapshot wont be able to continue.

Setup configuration for promotion
A valid ucd configuration is needed. Please check Required configuration for setting up UrbanCode PHP CLI basic configuration.

Edit your servers.config.php file

vi $uCommand/config/servers.config.php

and fill in the information for the origin and destination server

$config = array();

// Orign server login information
$config[origin_weburl] = ;
$config[origin_username] = ;
$config[origin_password] = ; // DEPRECATED
$config[origin_authtoken] = ;

// Destination server login information
$config[destination_weburl] = ;
$config[destination_username] = ;
$config[destination_password] = ; // DEPRECATED
$config[destination_authtoken] = ;

// Application name
$config[application] = SalesConnect;

// Certificate setup
$config[insecure] = true; // Set true for connection without certificate
$config[origin_certificate] = ; // Path to certificate for origin server (only if insecure is set to false)
$config[destination_certificate] = ; // Path to certificate for destination server (only if insecure is set to false)

For origin and destination server login information, please check Required configuration and the information related to login with tokens (recommended) and login with password.

Run the promotion

cd $uCommand

php uCommand.php promoteSnapshot [snapshot name]

Walkthrough of the promotion process
Promotion starts retrieving the snapshot from origin server

UrbanCode PHP CLI will then verify that all prerequisites are in place (list of prerequisites)]

Artifacts are exported from origin server

A new snapshot configuration is set up

Component versions are created. If correctly created, component version will be marked with tag [SUCCESS]; if the component version already exists on destination server, it will be marked with the tag [SKIPPING]. In case of failure, component version will be marked with tag [FAILURE].

If a component version has artifacts, they are uploaded on the destination UrbanCode Deploy server during this process.

User will then be notified of the success or failure. In case of success, a link to the just created snapshot will be displayed in the console.

Promote UrbanCode Deploy configuration

The promotion of UrbanCode Deploy configuration is the process of upgrading UrbanCode Deploy configuration in a destination server using the configuration taken from another UrbanCode Deploy server. This includes upgrade of processes, components and applications.

Promote from UrbanCode Deploy server
When promoting the configuration directly from an origin server, UrbanCode PHP CLI is automatically downloading the configuration from the origin server, so to pick up the latest changes. Then it will proceeed to the upgrade process against the destination server.

Edit your servers.config.php file

vi $uCommand/config/servers.config.php

and fill in the information for the origin and destination server. Then run the promotion command:

php uCommand.php promoteConfig

Promote from a source configuration directory
When promoting the configuration from a source directoy, UrbanCode PHP CLI is using the configuration saved in the directory to perform an upgrade against the destination server.

Edit your servers.config.php file

vi $uCommand/config/servers.config.php

and fill in the information for the origin and destination server.
Then run the promotion command:

php uCommand.php promoteConfig [full_path_for_source_directory]

Promote without importing environments
Since the upgrade of application is importing the environments from the orgin server, promoteConfig accepts the argument clean that automatically removes all the new environments imported by the upgrade.

Server to server promotion

php uCommand.php promoteConfig clean

Directory to server promotion

php uCommand.php promoteConfig [full_path_for_source_directory] clean

Perform a restore

php uCommand.php restore path_for_backup_folder

Restore without importing environments

Since the restore of application is importing the environments from the orgin server, restore accepts the argument clean that automatically removes all the new imported environments.

php uCommand.php restore path_for_backup_folder clean

Quick tip:Double check that the configuration file has the correct information of the destination server.

Warning:Please mind that the restore process is returning a false-positive when checking the success of the restore process. Please ignore this message and check for errors in the process output to determine if the restore was successful.

Perform a backup

After setting up the required configuration as described in required configuration, you can either define a directory where to export all the backup files or leave it blank and fall back to the default output directory.

{uCommand_path}/config/ucd.config.php

$config[output] = ;

Then run the backup:

php uCommand.php backup

Steps

Run UrbanCode PHP CLI .php

cd $UrbanCode PHP CLI
php UrbanCode PHP CLI .php action argument

Action Argument Description
addTeamToComponent [required] Team name or ID[optional] Component name or ID Add a component to a team. If the component is not passed as argument, all the components available in UrbanCode Deploywill be added to the team.
addTeamToResource [required] Team name or ID[optional] Resource name or ID Add a resource to a team. If the resource is not passed as argument, all the resources available in UrbanCode Deploywill be added to the team.
backup Run a complete back up of UrbanCode Deploy.
createSnapshot [required] Snapshot JSON file Create a snapshot based on a JSON file that includes information about snapshot name, application, list of component versions.
createVersion [required] Component name or component ID[required] Version Name

[optional] Description

Create a new component version
createVersionAndSnapshot [required] Snapshot configuration (PHP or JSON) Get a PHP or JSON file which includes the snapshot configuration. Gets the component versions listed and creates them. After that, it creates the snapshot.
exportEnvironmentProperties [required] Environment id Export the environment properties in a JSON file
importEnvironmentProperties [required] Environment id[required] Path of the json file exported with the exportEnvironmentProperties Import the environment properties of a given a JSON file into a uDeploy environment
promoteConfig [optional] If a directory is provided, restore configuration from there[optional] If argument clean is passed, remove new environments imported from application Upgrade an existing UrbanCode Deployconfiguration from a directory or from another UrbanCode Deployserver based on origin and destination servers set in servers.config.php
promoteSnapshot [required] Snapshot name[optional] configuration file

[optional] artifacts directory

Promotes a snapshot from one UrbanCode Deployserver to a second one, based on the details set in the configuration file. If artifacts are needed, thy will be taken from the artifacts directory set as 3rd argument.
requestStatus [required] ID of process request Returns the current status of a requested process.
restore [required] Source path for restore[optional] If argument clean is passed, remove new environments imported from application Run a complete restore of UrbanCode Deployfrom a structured folder.
restoreApplication [required] Path to Application JSON file or path to Application folder Restore an application from JSON file or application and its components from a folder.
restoreComponent [required] Path to component JSON file Restore a component from a JSON file, creating it.
restoreComponentTemplate [required] Path to component template JSON file Restore a component template from a JSON file, creating it.
run [required] Path to JSON file Requests an application process according to the details set in the JSON file passed as argument
runAndWait [required] Path to JSON file Requests an application process according to the details set in the JSON file passed as argument. Polls the request until its completed. Returns completion status.
upgradeApplication [required] Path to Application JSON file or path to Application folder Upgrade an existing application from JSON file or application and its components from a folder. Creates the application (and relative components) if missing in target uDeploy server.
upgradeComponent [required] Path to component JSON file[optional] upgradeTemplate

[optional] upgradeProcess

Upgrade an existing component form a JSON file. Creates the component if missing in target UrbanCode Deployserver. If the arguments upgradeTemplate and/or upgradeProcess are set after file path, template and processes are upgraded too.
upgradeComponentTemplate [required] Path to component template JSON file Upgrade a component template from a JSON file. Creates the component template if missing in target UrbanCode Deployserver.
ver Prints information about UrbanCode PHP CLI version and supported UrbanCode Deployversions
waitRequestCompletion [required] ID of process request Polls the request until its completed. Returns completion status.

Setup

To run any of the commands provided by UrbanCode PHP CLI , a few steps are needed in order to make the scripts work properly

Setup configuration

In order to make the script work, a valid configuration is needed. This will be used for connecting to the UrbanCode Deploy server and to setup some default values that will be used when executing CLI commands.

You can either use the Setup Wizard, or manual setup, steps listed below.

Setup wizard

The easiest and fastest way to configure UrbanCode PHP CLI is to run the setup script, which will automatically set the values in the configuration file. If you want to manually edit the configuration file, please check section Manual Setup.

Run the setup script and follow the instruction in the console:

cd $uCommand

./setup

Setup script will prompt the user for:

  • Server weburl (without htttps and port)
  • Port (Default: 8443)
  • Username (User email)
  • Password
  • JAVA_HOME (Default: $JAVA_HOME for the current environment)
  • Authtoken (If missing, a new one will be generated)

Script will also check that

Java is installed

  • PHP for CLI is installed
  • There is a valid connection to the UrbanCode Deploy server

Manual setup

You can manually edit your configuration with your UrbanCode Deployserver information:

vi $uCommand/config/ucd.config.php

Required configuration

The configuration needs to be updated based on the need of the user and on the action that needs to be executed.

Weburl is the url of the UrbanCode Deployserver the tool will work on. It includes the port and http(s).

$config[weburl] = https://example.com:8443; // URL for uDeploy server (with port)

Java_home is the path of the Java binaries used to run the tool

$config[java_home] = ; // specify the path for java binaries

Then you set the username of the user that is running the various actions on the server. Provide here a user with sufficient permissions to run all the required tasks. This is your own user name, e.g. johnsmith@ie.ibm.com.

$config[username] = ; // Your username for uDeploy

Login with tokens

Its possible to login using an authtoken generated by an administrator from the web UI under [UrbanCode Deployserver url]/#security/tokens

Generate a token

To generate an authtoken for your UrbanCode Deploy you need to login to the web UI as an administrator user.

If your account doesnt have administrator permissions, please contact the administrator of your UrbanCode Deploy server to get the followin steps done.

Navigate to [UrbanCode Deployserver url]/#security/tokens and click on Create New Token

In the dialog box, fill the form selecting

  • user the token is generated for
  • and expiration date and time in the future
  • a description
  • (OPTIONAL) the IP address allowed to login with that particular authtoken. If Allowed IPs field is left blank, all IPs will be allowed to use the token

Set token in the configuration

Once the token is generated, get it from the list available in [UrbanCode Deploy server url]/#security/tokens, and set it in ucd.config.php

$config[authtoken] = ; // AuthToken for udclient

Please bear mind to use a token correspondingto the user set in the configuration and that is not expired.

Login with password (DEPRECATED)

If you have already set up tokens as the login method, you can skip to Optional configuration. Otherwise, its possible to login with username and password. This is not a secure way to do login, since the password will be hardcoded unencrypted in the configuration file.

$config[password] = {Your_Password}; // Your password

You can either encode username and password using Base64 encoding. This is still not a secure way to login, since Base64 is easily reversible and your password will be exposed.

Login with Base64 encoding requires you to encode username and password in the following format:

$config[password] = ; // This should be empty

$config[b64_login] = base64_encode( {YOUR_USERNAME}:{YOUR_PASSWORD} );

Login with cookies (DEPRECATED)

If you have already set up tokens or password as the login method, you can skip to Optional configuration. Otherwise you can also login using cookies, but this will require some additional steps.

Login to your UrbanCode Deployserver and save the cookies

curl -k -u [username] [UrbanCode Deploy server url:port] -c $WORKSPACE/ucdcookie.txt

Then edit the config so to have blank password and the correct cookie file

$config[password] = ; // This should be empty

$config[cookie_file] = $WORKSPACE/ucdcookie.txt;

Optional configuration

This configuration is not required for UrbanCode PHP CLI to run correctly, but it allows you to customise it for your needs.

$config[application] = ; // Application youre working on

$config[environment] = ; // Your Environment

$config[output] = ; // For backup function where to save exported files

$config[udcpath] = ; // Path where udclient java tool is saved. If blank, will take default

$config[silent] = false; // If true, no message is printed in the console

$config[json_check] = false; // If true, run a scan of exported files and verify that are valid JSON

$config[apply_impersonation] = ; // If true, apply impersonation