Getting Started & Setup
How to setup Bamboo and the Bamboo Rollout Manager plugin
- Setup Version Control
- Setup Jira
- Setup Bamboo
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:
- SVN (opens new window)
- Git (opens new window)
- BitBucket (opens new window) (Cloud and Server) - Git based
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)
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.
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.
- install SVN on one of the DEV servers. Easiest is to use one of the binary packages available here (opens new window).
- If you are working on a Windows system, install Tortoise SVN (opens new window) on the DEV servers and on your local PC to make all changes visible in windows explorer and to avoid having to use the command line interface.
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 (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
create a .gitignore file, with these contents:
git addto add all of the files.
git commit -m "initial commit".
Using TortoiseGit in Windows Explorer:
- right click on the LES directory and select 'Create Git Repository here'.
- 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.
- right click again on the LES directory and select 'Git commit → "master" '.
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
- sign in or register with Bitbucket (opens new window)
- create a new (empty) repository (opens new window)
- push the content of the local git directory to the new repository in Bitbucket. It is explained in 'Import an existing Git project into Bitbucket Server (opens new window)'.
Setup Bitbucket Server
Bitbucket is not just a cloud-based product, it can also be installed on your local server.
After that, it is the same as described above in the BitBucket Cloud setup.
We assume you are already using Jira Software or have Jira Software setup. If not, refer to these online help pages to get started:
- Installing Jira server (opens new window) for installing Jira on your own servers
- Setup Jira cloud (opens new window)
There are not many requirements for Jira related to the Bamboo Rollout Manager plugin, except the following two:
- Jira issues should be linked to a Version using the Fix Version field.
- 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)
Link Jira to Bamboo
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:
- Install Bamboo (opens new window)
- the user that runs the windows service in bamboo should have permission to install rollouts. This typically means the permission to run the 'mload' utility.
- also, the windows user should have permission to stop and start the moca service.
- Install remote agents on all Blue Yonder WMS servers
- Link Bamboo to Jira
- Link repositories to Bamboo (opens new window). Link all repositories you want to build Blue Yonder WMS rollouts for. You can mix repositories from both SVN, Git and BitBucket.
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:
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.
In the Capabilities tab, click on 'Add Capability'
Add a custom capability with key
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.
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
Provide the name for this artifact, e.g. 'WM Rollout' or 'REFS Rollout'
Unique subdirectory name, e.g. 'wm_rollout' or 'refs_rollout'
Always copy everything:
Always check this box.
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
Build Rollout and
Install Rollout for Build. See screenshot below.
Add the Build Rollout task next
Description for this task.
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
If this field is left empty, as well as the 'Exclude' field, it will evaluate all files in the repository.
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
If this field is left empty, as well as the 'Include' field, it will evaluate all files in the repository.
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
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:
- The Blue Yonder WMS environment is located on the same server where the Bamboo server is located.
- include the
Install Rollout for Buildtask in the same Job as the
- include the
- 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
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
Description of this task.
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.
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.
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'.
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.
Edit Build Plan
To name the rollout releases the same as the Jira Release version, use the following variable:
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.
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
To link the right Remote Agent to the right environment, we need to assign an Agent to this Bamboo Environment
If we want the deployment in another environment to trigger the deployment in this environment, we can add a trigger here.