Getting Started & Setup

How to setup Bamboo and the Bamboo Rollout Manager plugin

Prerequisites

What you need before following this setup guide:

  • Installation of Atlassian Jira. This can be a local Jira server version or the Jira Cloud version. See local or cloud based for different configuration options.
  • At least one Blue Yonder WMS environment setup (e.g. a DEV environment)
  • Blue Yonder WMS running in a Windows environment (UNIX is not yet supported)
  • An environment with Java 8 to install Bamboo and the Bamboo Rollout Manager plugin

Setup Version Control

Bamboo relies on a version control system to build the rollouts. Currently, the following version control systems are supported with the Bamboo Rollout Manager plugin:

To build the rollouts correctly, the 'LES' directory has to be version controlled, with the exception of a few subdirectories. One repository (or one branch) should contain only one LES directory. Which sub-directories should be under version control depends on the JDA product (e.g. WMS, HUB, Parcel), but generally all subdirectories besides the directories bin, build, files, include, install, lib, log, rollouts and temp.

For example, a version controlled LES directory could look like this: (note: this is a windows explorer view on a server with TortoiseGit (opens new window) installed)

LES Directory

Multiple environments and branches.

In a given company, there can be many different Blue Yonder WMS environments. At a minimum, there is the Development, Test, production and Archive environment. Then there might be other products like EMS and Parcel which might also require a Development and/or Test environment. And that is just for one warehouse. Often times, there are multiple warehouses, each with their own production environment. These other production environments might share the same code base. Or they might each have different customizations and different versions. How can we setup version control to support this completely?

The bottom line is: create one branch per unique code base.  In Blue Yonder WMS situations, a 'code base' usually translates to one production environment, or if multiple production environments share the same code, then it would apply to all these production environments.

Also, with the use of Bamboo, only the DEV environments have to be version controlled. The code in the other environments is only changed via rollouts created by Bamboo and don't need to be version controlled.

Multiple environments

Setup SVN

SubVersion (SVN) (opens new window) has some user friendly features and especially when working with Blue Yonder WMS components, compared to Git, it is more user friendly when you have to correct or revert mistakes. Downside is that you can't link it to an Atlassian web viewer like BitBucket. You have to install another web viewer/ web client. This wikipedia page (opens new window) has an overview of the different SVN clients.

Another downside is that you can use SVN only with a Jira Server installation and not with Jira Cloud. If really needed, there are some work-arounds, but it's not straightforward.

Setup Git

Git seems to be the main version control system for Atlassian products like Jira and Bamboo. It assumes that GIT is installed on the server where you have your version controlled directories.

Install Git

  • install Git (opens new window) on one of the DEV servers. If you want to clone the version controlled files to local PCs of the developers, each PC also has to install GIT.
  • Install a GUI client (opens new window) on the DEV servers and/or local PCs of the developers. This will make the daily git tasks - which is mainly committing code - a lot easier for developers.

Put the LES directory under version control.

  • Using git command line:

    • go to the LES directory

    • Type git init.

    • create a .gitignore file, with these contents:

      **.gitignore** 
      
    • Type git add to add all of the files.

    • Type git commit -m "initial commit".

  • Using TortoiseGit in Windows Explorer:

    • right click on the LES directory and select 'Create Git Repository here'. Create Git Repo
    • select all sub-directories that should not be version controlled and right click TortoiseGit → 'Delete and add to ignore list → Delete and add to ignore list x items by name. This will not actually delete the directories (you will be prompted to 'keep local' - say Yes) but add these folders to the .gitignore file. Alternatively, you could manually create the .gitignore file in the LES directory as stated earlier. Git Ignore
    • right click again on the LES directory and select 'Git commit → "master" '.  Git Ignore

Setup Bitbucket

After installing Git on one or more DEV servers, you can link the (local) Git repositories to BitBucket and use Bitbucket as the 'remote repository'. Bitbucket is also the place where you can view the code and diffs as well as the system that Bamboo can connect to.

Depending on the Bitbucket version (cloud or server), the setup is a bit different.

Setup Bitbucket Cloud

Setup Bitbucket Server

Bitbucket is not just a cloud-based product, it can also be installed on your local server.

See installation instructions here (opens new window)

After that, it is the same as described above in the BitBucket Cloud setup.

Setup Jira

We assume you are already using Jira Software or have Jira Software setup. If not, refer to these online help pages to get started:

There are not many requirements for Jira related to the Bamboo Rollout Manager plugin, except the following two:

  1. Jira issues should be linked to a Version using the Fix Version field.
  2. Jira should be linked to Bamboo via an 'application link'

See paragraphs below for more details.

Enable Jira Versions

The 'Fix Version' field in Jira is not always visible in Jira Issues until you create at least one Version in Jira. Create at least one version to make this field visible.

Another reason you might not see the 'Fix Version' field is when this field is not setup for the Issue Type you are using. See this article about Project screens, schemes and fields (opens new window)

Atlassian uses 'application links' to connect one application to another. For the plugin to work, Jira needs to have an application link to Bamboo.

See the following links for how to set this up:

Setup Bamboo

Install Bamboo

Install the plugin

From the Bamboo Admin page, go Manage Apps -> Find New Apps.

In the search box, type 'Rollout'.

Or, start with the plugin itself on the Atlassian Marketplace:

Get the plugin
Get the plugin here

Setup Remote Agents

Per a previous step above, all Blue Yonder WMS servers should have a Bamboo Remote Agent installed. See See installation instructions here (opens new window)

Add Custom Capability for Perl

Once the Remote Agents are istalled and visible in Bamboo Administration -> Agents -> Remote Agents, we need to add a 'Capability' to each Remote Agent, to specify where the Perl executable is.

Click on the Remove Agent you want to configure. This shows the 'Agents summary' screen.

Agents Summary

In the Capabilities tab, click on 'Add Capability'

Agent Custom Capability

Add a custom capability with key perl.path. The value should be the absolute path to the Perl executable on the server where the Remote Agent is running. The path should include the executable name itself (e.g. perl.exe)

Setup a Build Plan

The build plan is where we the rollout is build and optionally where we install it in the test environments. See the diagram below to see how build plans relate to different environments. Typically, we need one build plan per DEV environment.

Build Plans

To setup a build plan in Bamboo, refer to this documentation (opens new window).

In the Plan → triggers tab: remove all triggers that might be created by default.

Define one job per Rollout definition

We want to create one Job per rollout we want to create. E.g. if we want to create a rollout for WMS and another one for REFS, we create two Jobs. We can use the same Stage for multiple Jobs.

Add Artifact Definition

For each Job that builds a rollout, go to the 'Artifacts' tab and click Define Artifact.

Bamboo Artifact Definition

Field Name Provide the name for this artifact, e.g. 'WM Rollout' or 'REFS Rollout'

Field Location Unique subdirectory name, e.g. 'wm_rollout' or 'refs_rollout'

Field Copy Pattern Always copy everything: **

Field Shared Always check this box.

Field Required Uncheck this box. (We don't want to fail the build if we don't have REFS files in this rollout.)

Add Task Build Rollout

When you click on 'Add Task' you will find two Bamboo Rollout Manager plugin specific tasks under Builder: Build Rollout and Install Rollout for Build. See screenshot below.

Bamboo Task Types

Add the Build Rollout task next

Bamboo Task Configuration: Build Rollout

Field description. Description for this task.

Field Include Files. Use this if we want to create a rollout for a subset of the repository. For example, if we want to create a REFS rollout, and the REFS code is in LES/refs_deploy, then this field should contain **/refs_deploy/** If this field is left empty, as well as the 'Exclude' field, it will evaluate all files in the repository.

Field Exclude Files. Use this if we want to create a rollout for a subset of the repository. For example, if we want to create a WMS rollout, while we want to exclude REFS changes is in LES/refs_deploy, then this field should contain **/refs_deploy/** If this field is left empty, as well as the 'Include' field, it will evaluate all files in the repository.

Field Path and file name for rollout.pl file to use. Specify a custom rollout.pl file to be used in the rollout. This allows for potentially different rollout.pl scripts in each rollout. The file name can be different than 'rollout.pl', but it will rename it to 'rollout.pl' in the resulting rollout package. If blank, it will use **/scripts/rollout.pl from the repository.

Add Task Install Rollout for Build

To test the actual installation of the rollout, we might want to install the rollout in DEV (even though the code itself should already be present there). And/or we might want to install the rollout in a TES environment right away.

There are a few possible scenarios, each requiring a slightly different setup:

  1. The Blue Yonder WMS environment is located on the same server where the Bamboo server is located.
    • include the Install Rollout for Build task in the same Job as the Build Rollout task
  2. The Blue Yonder WMS environment is on a different server than the Bamboo server:
    • in the same Build Plan, create a new Stage. (not just a new job; jobs within a stage are executed in random sequence)
    • in the new Stage, create a new Job (e.g. Install Rollout in TEST)
    • in the new Job, go to the tab Artifacts and click Artifact Dependency. Specify the rollout we want to install.
    • link the Job to to the Agent that runs on the Blue Yonder WMS environment where we want to install this (e.g. TEST). This is done in completely different place: Bamboo Administration -> Agents -> Remote Agents -> (select remote agent) -> Dedicate Agents -> Type: Build Job: select Job you are defining

Bamboo Task Configuration: Install Rollout for Build

Field description. Description of this task.

Field File location of env.bat. Absolute path of the env.bat file for the Blue Yonder WMS environment where we want to install the rollout.

Field Custom options for rollout.pl. If a custom rollout.pl file is used that supports arguments like --noDataLoad or --noCompile, we can add these arguments here.

Other settings

For each job, we need to cleanup the working directory so it doesn't get confused with files from the next build. In tab Job → Miscellaneous, check box for  'Clean working directory after each build'.

Bamboo Job Configuration: Other tab

Setup a Deployment project

See this documentation (opens new window) to setup a deployment project.

Below is a summary of the setup steps.

Once a Deployment Project is created Edit or Add 'Build Plan', 'Release Versioning' and 'Environments'. See buttons in screenshot below. Bamboo Deployment Configuration: Deployment Project

Edit Build Plan

Bamboo Deployment Configuration: Link Build Plan

Release Versioning

Bamboo Deployment Configuration: Release Versioning

To name the rollout releases the same as the Jira Release version, use the following variable:

${bamboo.JIRA_RELEASE}

Add Environments

At a minimum, we need to add Tasks and assign Agents. We can add triggers if we don't want to initiate the deployment to each environment manually. Bamboo Deployment Configuration: Edit Environments

Add Tasks

Typically for a remote environment, we add the following tasks:

  • Clean working directory task. Required so different artifacts (rollouts) don't interfere with each other.
  • Download Rollout. This is to copy the rollout from the Bamboo server to the remote agent on the Blue Yonder WMS server
  • Control Windows Service. To stop the Blue Yonder WMS windows service while the rollout is installed
  • Install Rollout for Deployment. The actual rollout installation
  • Control Windows Service. To start the Blue Yonder WMS windows service back up

Below are screenshots for these tasks as examples

Bamboo Deployment Configuration: Task Download Rollout

Bamboo Deployment Configuration: Task Control Windows Service

Bamboo Deployment Configuration: Task Install Rollout

Agent Assignment

To link the right Remote Agent to the right environment, we need to assign an Agent to this Bamboo Environment

Bamboo Deployment Configuration: Assign Agent

Triggers

If we want the deployment in another environment to trigger the deployment in this environment, we can add a trigger here.

Bamboo Deployment Configuration: Triggers

Last Updated: 5/6/2022, 6:33:27 PM