Project orchestration

Overview

Tasks are discreet functions that can be run on a target. Tasks are linked together in flows, or orchestrations, that are an target neutral series of activities. Each RapidDeploy project defines a single orchestration, which can be run on many targets, by injecting target specific properties and settings.

Orchestration Execution Options

The orchestration engine can be started via three different mechanisms:

  • Via a SSH connection from the framework server to the target server.
  • Via a RapidDeploy secure remote agent, which is a process running on the target server, from the framework server.
  • Directly on the target server as a standalone java process, invoked from the command line.

If the framework server (using the Web UI or a Web Service) is used to start the orchestration via SSH then the following happens:

  1. All the JAR files from the framework server lib directory are checksummed and compared against what is in the buildstore on the target directory, if there is a difference then the file from the framework server is copied over to the target server.
  2. The project log properties file and the orchestration XML file are copied to the target server.
  3. The project package is copied to the target server.
  4. A java process is executed on the target server to start the project orchestration. The framework defined environment variables are set on the server process before the java process is started.

If the framework server (using the Web UI or a Web Service) is used to start the orchestration via a secure remote agent then the following happens:

  1. The JAR files in the remote agent lib directory on the are used to run the orchestrations.
  2. If the agent is set to auto update and auto restart and the framework server has a different checksum of a plugin JAR file then the file it is copied over to the remote agent and the remote agent is restarted. See Remote Agent documentation for configuration options.
  3. The project log properties file and the orchestration XML file are copied to the target server.
  4. The project package is copied to the target server.
  5. The remote agent then queues the project orchestration and continually polls the queue. The project orchestration starts when there are no executing or queued jobs left in the queue.

Orchestration Process

Whichever mechanism is used to start the orchestration engine, once it is started the execution process that follows is always the same.

  1. Each task is executed in order starting from the initialisation task to the finalisation task. Depending on target specific and conditional branches, different tasks may be executed for different targets or depending on the conditional tests performed.
  2. The initialisation task uncompresses the project package is into the platform-dependant temporary directory. The package name plus a unique GUID is used to create the temporary directory where the package is uncompressed to.
  3. The initialisation task then does a search / replace of all the data dictionary values with all the files in the temporary package directory.
  4. Each user defined task is executed in order. Depending on target specific and conditional branches, different tasks may be executed for different targets or depending on the conditional tests performed.
  5. The finalisation task clears up the platform-dependant temporary directory by deleting the temporary directory created in the initialisation task.
  6. The orchestration task logs are streamed to the framework server while the orchestration is executing.

Accessing tasks

General tasks are accessed via the orchestration plugin. Technology specific tasks are bundled with the technology plugin that they relate to.

The orchestration plugin is shipped with RapidDeploy or can be installed via the Plugin Manager (System menu -> Plugin Manager). Plugin jar files may be downloaded and installed automatically from the MidVision download site, or uploaded from the users desktop or via the plugin manager. Plugins are installed into various locations under the Midvision install directory ($MV_HOME).

Individual task documentation

Tasks fall into a number of categories, as detailed below. Each link will take you to a page detailing all of the tasks for that technology type. There is a core tasks link that details all tasks shipped in the orchestration plugin.

Core Tasks

This section contains details of core tasks. These tasks are included directly in the orchestration jar and are not shipped as part of a plugin. Core tasks typically includes various file maintenance, i/o and server architecture tasks.

Orchestration Settings

To configure the orchestration file paths and email setting please go to project deatils page -> Orchestration Tab -> Settings Sub Tab.

On Settings tab you can find to main sections explained below:

Orchestration File Paths

  • Log4J Path: Default value ./log4j.properties. This is the path (relative or absulute) of the Log4J configuration file used by the logging operation during the orchestration execution
  • Log Level: Default value is INFO. This the the logging level for the orchestration execution. Available options are: TRACE, DEBUG, INFO, WARN, ERROR, SEVERE.

Email

  • Enable: default value is disable, please enable it for use the email features.
  • Notification Email Address: One or more recipients email addresses separated by semi-colon or spaces. (mandatory)
  • Email Host (SMTP): Hostname of the SMTP server (mandatory)
  • Email Port (SMTP):Port of the SMTP server (optional)
  • Email Sender Address (SMTP Auth): Email sender address.
  • Email Credentials (SMTP Auth): Password to authenticate sending emails on the SMTP server (optional). The sender email address is the username to authenticate sending emails on the SMTP server

Orchestration built-in variables.

There are several 'built-in' variables that may be set in orchestration task resources, that will be resolved, at runtime, to the actual values in use for that run job.

Orchestration diagram edition through keyboard:

The orchestration diagram can be edited also using the keyboard. The user can enable this feature just clicking on any diagram element and then use the keyboard, once the user moves the mouse pointer, the keyboard edition is disabled.

Keyboard reference:

  • Arrow Up -> Navigation through diagram * ALT + Arrow Up -> Moves selected task up * CMD + Arrow Up -> Moves selected task up (Only Mac) * Arrow Down -> Navigation through diagram * ALT + Arrow Down -> Moves selected task down * CMD + Arrow Down -> Moves selected task down (Only Mac) * Arrow Left -> Navigation through diagram * Arrow Right -> Navigation through diagram * Delete -> Delete selected Task * CTRL + C -> Copy selected task * CMD + C -> Copy selected task (Only Mac) * CTRL + V -> Paste task * CMD + V -> Paste task (Only Mac)