XL Release - Reference Manual 3.0.4

Introduction

Welcome to XL Release!

XL Release is an enterprise release coordination software solution that allows you to:

• Plan, track and execute release plans from code drop to end user
• Pro-actively avoid release delays and failures by tracking pending tasks, risks and dependencies
• Accelerate your delivery process by replacing manual with automated tasks and standardizing release plans.

By providing a single source of truth and increasing the level of automation and standardizing the release process, XL Release helps you deliver higher quality software faster.

XL Release is for everyone who needs to work on, manage or report on a release.

This is the reference manual of XL Release, describing the core concepts of the application and all functionality available from the UI.

Core concepts

This section briefly explains the concepts used in XL Release.

Releases are at the heart of XL Release. A release represents a number of activities in a certain time period with people working on it. XL Release allows you to plan track and execute releases automatically and acts as a single source of truth for all people involved to make the release a success.

A release is divided into phases -- logical stages in the process. For example, a release can be divided into a Dev, QA and Deployment phase. In XL Release, a phase is a grouping of tasks, the activities that have to be done to fulfil the release.

Tasks are activities in a release. In XL Release, everything that has to be done is defined as a task. There are manual tasks, where a human has to do something, and automated tasks that will be performed unattended by the XL Release flow engine.

When a release is started, XL Release will execute the release flow. This is the workflow of the release. XL Release will determine what is the current task that needs to be picked up and will either execute it (if it is an automated task) or send a message to the person responsible for it (if it is a manual task).

Each release has a release owner, the person that is responsible for correct performance of the release. If something goes wrong, the release owner will be notified. For example if an automated task produces an error, or one of the people working on a task indicates that he is in trouble.

A Template is a blueprint for a release. It can be used to start various releases that have the same flow. It is very similar to a release, but some functionality is different because a template will never be executed directly. For example, there are no start or end dates on a template; most tasks will be assigned to teams rather than actual people; and variables will be used as placeholders for information that differs from release to release, like the version number of an application.

Each release (or release template) defines a set of teams. A Team is a logical grouping of people that perform a certain role. For example, on a release you could define a Dev team, QA team, OPS team and Release Management team.

Task overview

When logging in, you will be presented with the Tasks overview. It will show the active tasks that are assigned to you or a team you are in.

Tasks are grouped by release. You can hide the tasks of a certain release by clicking on the triangle on the left side of the screen.

Per task, the following information is shown, from left to right:

Status icon. An orange icon indicates that a task is currently active. A clock icon indicates that a task is waiting to start at a predefined time in the future (task state is 'pending').

Task type and Status label. Each task type has its own icon. For example a person icon identifies the task as a 'manual task'. The status label below it indicates the current execution state of the task.

Task title and assignee. Next, we find the task title, and below it, the name of the person or team that is responsible for it.

Task actions. Actions on the task. Only the actions are shown that are currently relevant and that the currently logged in user has permission to perform.

• Complete. Complete this task and advance to the next task in the release. A dialog will be shown asking you to comment on the completion of the task. The comment is optional.
• Skip. Skip this task and advance to the next task in the release. This is similar to 'complete', but will indicate that no actual work has been done. A dialog will be shown asking you to enter a comment. This comment is required.
• Fail. Put this task in 'Failed' state and notify the release owner. This will halt the release process and can be used as a mechanism to signal that something is wrong, that you as a the owner of the task don't know how to resolve. A dialog will be shown asking you to enter a comment. This comment is required.
• Assign to me. Assigns the task to you, the currently logged in user.
• View in Release. Opens the release flow for this task.

Number of comments. The number of comments that have been added on the task.

Phase. The phase the task is in.

Started, Planned or Scheduled. If the task has already started, its start date is displayed here. Otherwise, if the task is scheduled to start at a specific date in the future, this date is displayed; the label will be "Planned" if the task is waiting for a previous task to complete, or "Scheduled" if it is waiting for its start date. See the task lifecycle.

Due. If a due date is set on a task, it is displayed here.

Flag. A task may be flagged to indicate that progress doesn't go as smooth as intended and the timely completion maybe at risk. There are two colors for the flag: orange indicates "attention needed"; red indicates "at risk". When setting a flag, you can also set a status text. In the task overview, the status text is displayed underneath the task details, on a background corresponding to the flag color.

By clicking anywhere on the task details, a dialog window will pop up showing the task details. See the Task types section for more details for each task type.

Filtering tasks

By using the filtering and search options, you can query the current tasks in the system.

The Filter options button brings up a selection window with several options. By toggling them on and off, you can select which tasks you want to see. These are the options:

• Active Tasks. If selected, only tasks that are currently active are shown. When deselected, you can also see the tasks that are coming up (task state 'planned').
• Assigned to me. Toggles whether to show tasks that are assigned directly to the currently logged in user.
• Assigned to my teams. Toggles whether to show tasks that are assigned to teams the current user is in.
• Assigned to others. Toggles whether to show tasks that are assigned to people that are not the current user, or to teams the current user is not in.
• Not assigned. Toggles whether to show tasks that are not assigned to anybody. When selected only in combination with Active Tasks, this is a useful way to show all tasks that are active but that nobody is looking at.

Apart from task properties, you can also filter on task title using the Filter by title search box. Simply enter (part of) a title of a task title, release title, task owner or teams, and only the corresponding tasks are shown.

Release overview

When navigating to Releases > Overview you will see the list of currently active releases.

Each release that is visible to you (you may not have view permissions on all releases) and that is currently active is displayed. This includes releases that are planned, in progress and failed.

Each release is displayed in a block. The first column contains the Release title and the current phase (if the release is active).

The Actions column contains shortcuts to some of the actions that can be performed on a release:

• View. Opens the release details screen on the release flow editor page.
• Start. Starts the release. Only available if the release is in 'planned' state.
• Abort. Aborts the current release.

The Status column shows where the release is in its lifecycle.

The Start date column displays the planned start date if the release is scheduled in the future, or the actual start date if it has already started. The End date column displays the planned end date if the release has not yet completed, or the actual end date otherwise.

In both columns, an overdue date is displayed in red.

If a status flag is set on either the release or one of its tasks, it is displayed on the bottom of the release box.

Filtering releases

By clicking Filter options a menu is displayed with filtering options.

• Active releases. Toggles showing releases that are currently busy. (Release states 'in progress', 'failing' or 'failed').
• Planned releases. Toggles showing releases that have been created but that have not been started yet. (Release state 'planned').
• Completed releases Toggles showing releases that are done. (Release states 'completed' and 'aborted').
• My releases. When selected, only shows releases for which you are the release owner.
• Flagged. When selected, only shows releases that have are flagged with a warning message. Use this option to show releases that are currently at risk.

You can also filter on task title using the Filter by title or tag search box. Simply enter (part of) a release title or tag and only the corresponding releases are shown.

Release details

The release details pages show you all information on a release and let you edit the release, provided that you are granted permissions to do so.

The first button on the top bar lets you navigate across the different pages of the release details

The sections below describe each of the pages.

Release Summary

The Release Summary page shows an overview of the current release.

The first section shows a timeline of the release.

The complete timeline of the current release is displayed in orange.

A release may depend on other releases; you can specify this on a Gate. If the release has any dependencies on other releases, then those releases are displayed above it, and listed under the "Depends On" header. All releases that depend on this release are displayed below this release in the timeline (if visible) and are summarized in the "Blocks" header.

Below the timeline, the current phase and currently active tasks are displayed.

Next section is the Task Overview

This widget shows which tasks are coming up, are currently active and still need to be done. The tasks are split out per team or per user, so you can easily see how teams and people are allocated throughout the release.

Finally, the Alerts section shows warning signs on the release

Status Flags are manually set on the release or on a task to indicate the release needs attention or is at risk.

The Dependencies section shows alerts for dependent releases that have not finished yet.

Finally, Delays shows all tasks (active and planned) that have a due date in the past.

Planner

The Planner section shows an interactive Gantt chart and allows you to view and edit the timing of phases and tasks on the level that you desire.

The so-called Gantt diagram is a combined timeline of the release, its phases and the tasks within. You can set set a desired start time and due date on phases and tasks, but it is not required. When no start time is set on a task, it will be displayed on the diagram as having the same start time as the phase it is in (and conversely for due dates).

Keep in mind that in a phase tasks are executed in sequential order. So in the above diagram, Task 2 will not be started until Task 1 has finished. This is indicated by the grey line connecting the right end of Task 1 of with the left side of Task 2.

For detailed time planning, you can move and resize the tasks in the diagram. You can set the due date of a task by dragging the right edge of a task. Conversely, you can set the scheduled start date of a task by dragging the left edge of a task. Note that setting a scheduled start date on a task means that the task will not start before this date is reached, even though the previous task has finished. You can also move the whole task by dragging it -- this will update scheduled start date and due date but keep the duration of the task the same.

Moving a task and chaining the due date will also affect the start dates of subsequent task in the same phase. One exception here is that Gates will not be moved.

To remove a start or due date, double click on the task. The task dialog will appear and you can click on the cross next to 'Scheduled start date' or 'due date' to remove it.

More sophisticated planning can be done inside a Parallel group. By default, all tasks in a parallel are started when the group is started and are executed in parallel. The planner tool allows you to do planning on a detailed level and express dependencies between tasks explicitly.

Here's an example of a ParallelGroup with three tasks. Task 1 already has a due date.

We connect Task 1 to Task 2 by dragging an arrow from the right edge of Task 1 to the left edge of Task 2

As a result, Task 2 will start at the due date of Task 1

Task 3 is not connected and since it is inside a Parallel Group, it will start at the same time as Task 1 (when the Parallel Group starts).

Release flow editor

The release flow editor shows you the phases and tasks in the release and allows you to add, move, edit and delete them.

This editor is used for both running releases and templates, but there are some minor differences between the two usages.

In a running release, the current task is indicated with an orange arrow. Completed tasks are greyed out and can not be moved or edited anymore.

Top bar

Next to the navigation button, there are darker colored action buttons that are different for the various release types.

Template

Planned release

Active release

Here's a description of the actions:

• Add Phase will add a new phase to the release editor, after the last phase. Move it into the right position using drag-and-drop.
• New Release. In a template, pressing this button will create a new release from the template. This is a copy from the template. See Creating and starting a release for the detailed procedure.
• Start. Pressing the Start button will start a release that is in planned state.
• Abort. The Abort button will stop a currently active release and discard it.
• Restart Phase…. In an active release, you may abort the current phase and restart the execution from any phase in the past. See Restarting a phase for more information.
• Export to Excel. Pressing this button will start a download of the current release in Microsoft Excel format (xlsx).
• Export to JSON. Pressing this button will start a download of the current release in JSON format. This format can be imported from the Template Overview screen, so you can share templates across XL Release servers. See Importing a template for more information.

Editor

The editor is used to display the workflow of your release. This section describes on how to use the editor to design a workflow by adding, moving and deleting phases and tasks.

Managing Phases

To add a phase, press the Add Phase button on the top bar. A new phase with title 'New Phase' will appear.

Change the title by clicking on it. You can move the new phase to the desired position in the release flow by way of drag-and-drop. You can also collapse / expand a planned phase by clicking on the arrow.

The phase header contains four icons that appear when hovering over it with the mouse pointer.

• Select phase color is a color picker that allows you to select a color for the top bar on the phase. Use this to color-code your phases.
• Duplicate phase creates a carbon copy of the current phase. This is useful during modeling when you have similar or even identical phases. When duplicating a phase that is active and has running and completed tasks, the new phase will have all tasks in 'planned' state.

• Phase details opens the following popup:

  

  • A description of the phase;
  • Start and due dates. These will be used when displaying the phase in the calendar; if they are not consistent with the release dates (as defined in the Release properties page), a warning will be displayed.

• Delete phase will delete the phase from the release flow. You can not remove completed or active phases of a running release. This is not allowed, because it would corrupt the history reports and audit log of your release.

Managing Tasks

Phases by themselves do not do very much -- they are logical groupings of all activities in a release. The activities are modeled as tasks. To add a task to a phase, simply press the Add task link at the bottom of the phase.

An input field is displayed that allows you to specify the title of the new task and select the type. See Task types for an overview of available task types. Press Add to create the task and add it to the phase. The input field stays open, allowing you to quickly add another task.

The task will be added at the end of the release. Move it to the desired position in the phase using drag-and-drop. You can also drop the task into another phase.

A Parallel group is a special task that is a container for other tasks. All tasks inside the parallel group will be started simultaneously and the parallel group task will finish when all its children have completed. The parallel group has its own Add task link inside to conveniently add nested tasks. You can also move tasks into a parallel group by way of drag-and-drop or collapse / expand it by clicking on the arrow.

A task is displayed as a box in the phase. Here's a legend of all UI elements that can be displayed on a task:

The orange triangle indicates that this task is currently active in the release. This can only be displayed on an active release, not in templates or planned releases. Inside a parallel group, there may be more than one active task.

The title ('Prepare Release notes') is displayed in the top-left corner.

The task assignee ('John') is displayed in the bottom-left corner. The team is displayed here if the task has not been assigned to a user yet. If the task isn't assigned to a team either, this is left blank. If the task is an automated one, the type of script is displayed here. For example: "Webhook: JSON webhook".

The top-right corner displays a list of icons. First is the icon that identifies the type of task. Then a colored label ('In progress') that shows the current state of the task. This label is only displayed on active releases. After that, the alert icon is displayed if attention is needed on the task. Finally there are the clickable icon buttons that allow you to duplicate and remove a task. In an active release, only planned tasks (tasks that are not in progress yet) can be removed. Only tasks that are active or planned can be duplicated.

The due date is displayed on the bottom-right corner, if set.

Clicking anywhere on the task (except on the duplicate and delete icons) will open the task details popup. Every task type has a different dialog, see Task types for more details.

Release properties

Select Properties from the Show menu in the top bar of the release view to navigate to the Release properties screen. This page shows all the meta-data of a release.

Here's a breakdown of all the fields on this page.

The Release name field allows you to change the name of the release. This is also allowed on a running release.

Flag status is an optional warning message that can be set on a release. You can set the alert to amber ("attention needed") and red ("release at risk"). Releases with such a status will be highlighted in overviews so they are easy to spot.

Start date and time and Due date and time set the planned start and end dates of a release. These dates will be used to display the release on the calendar. Note that these times are not the dates that the release actually started or ended.

The Release owner is the person that is responsible for the release and will receive notifications if tasks fail, or are flagged of being in danger. The release owners are automatically added to the Release Admin team when the release is created. This team has all security permissions on a release. Release owners can also make use of the My Releases filter option in the Release overview.

The Description has detailed information about the release. You can edit the text by clicking on it. The text editor supports Markdown syntax, so you can put styled text and hyperlinks here.

Tags can be set on the release, to make it easier to search for it the release overview.

Share calendar enables you to view the release in your calendar application, for example Microsoft Outlook or Apple's iCal. There are two ways that the release dates can be exported. The first way is to publish a link that can be imported in the calendar application. When the dates of the release change, the event will automatically be updated in your external calendar. This link is accessible to everybody that can reach the XL Release server. This may be a security concern, so the link needs to be explicitly enabled by marking the check box in front of it. The other way to export the release information is a private download. This will save an ICS file to your computer that can be opened by your calendaring application.

The Variables section lists all Variables that are defined in the release. Variables can be put in most task fields by putting ${..} around a word or phrase. The variables are placeholders that are filled in when the task is started. The values of the variables are specified on this page. You need to give values for all variables, otherwise the task that contains a variable without a value will fail.

Smart auto-completing is available for deployment packages and environments of a Deployit task. You can start typing and XL Release will retrieve the list of deployment packages or environments that are available in Deployit.

The release properties page has an explicit Save button, meaning that changes are not persisted until you press this button. (This is in contrast to the Task dialog, where changes are sent to the XL Release server immediately). To reset the form with the current state of the release properties as known by the server, simply press Reset.

Teams

The Teams section of a release displays the teams that are defined for this particular release. Teams group people with the same role together. You can assign a task to a team, in order to express that someone from that team has to pick up the task when it becomes active. Security permissions on a release are also expressed on the team level, see Release permissions.

The page consists of a table and a New team button.

The New team button adds a new team to the release. The members of a team are entered one by one and are added by hitting the enter key.

Remove the team by clicking on the black cross in the last column.

There are two predefined teams that can't be removed:

• The Template Owner team contains all people that have owning rights on the template.
• The Release Admin team is the team that contains all people that are responsible for a running release, that is created from this template. These are the people that get extra notifications when a task fails and the release is halted for example.

Release permissions

The Permissions page of the release allows you to specify who can do what on a release. This page is only available to users that have Edit security permission, either on the release or as a global permission.

The page lists all teams and their permissions.

The following permissions apply to a release:

• View Release. Users have view access to this release. It will show up in the Release Overview. In the Release Details, users have read-only access to the release flow, properties and activity log.
• Edit Release. Users may alter the structure of a release: adding and moving tasks and phases. Release properties and teams are editable.
• Edit Security. Edit teams and permissions in a release.
• Start release. A planned release may be started with this permission.
• Abort release. An active or planned release may be aborted with this permission.
• Edit task. Individual tasks may be edited.
• Reassign task. Tasks may be assigned to other people. Team assignment is also enabled.

The Release Admin team is created when the release is created. It contains the Release owner and has all permissions by default.

Changes to the table are not applied immediately -- press the Save button to confirm or the Reset button to discard your edits.

Activity logs

The activity logs show everything that has happened on a release. It shows an audit trail of who did what and when.

Here's an example of an activity log:

The top bar provides various ways to filter the entries:

• click the Filter categories button to select which types of actions are displayed.
• start typing in the text field to target a specific user or action.
• use the from and to fields to select a date range.

You can also toggle the order of the rows by clicking on the Date column header.

Task types

There are several types of tasks in XL Release. They can be divided into three groups. First, there are the human tasks, that imply that somebody performs some kind of action and notifies it has been done. Manual tasks and Gates are examples of this kind of tasks. Then there are the the automated tasks, where the XL Release execution engine will perform some kind of automated script. Examples are the Deployit task, the Script task, Webhooks and the Notification task. Finally, there are the container tasks -- these are tasks that contain subtasks. For example, the parallel group.

Manual task

A manual task indicates that a step in the release process has to be done by a human.

It is the most basic of the available task types and we will use it as a basis to describe the functionality that is common across most tasks.

Here is an example of the task details dialog window. You get this window by clicking on a task in the task overview or in the release flow editor.

Immediate edits. There are no Save or Cancel buttons on the task dialog window. All edits are immediately processed, so you never loose work. Most of the fields are 'inline editors'. They appear as normal UI text elements, but when you click on them they turn into an editable field. After editing you can press enter or click outside the field to save the changes. You can cancel your edit by pressing the escape key. On larger text areas, you use the enter key to go to the next line. You have to click on the checkmark icon to save the changes, or the round cancel icon to discard your changes.

Title and description

The task title is displayed in the top colored bar. You can change the title by clicking on it. Below it the release this task belongs to is displayed ("Consumer Portal 3.2" in the screen shot), followed by the task's phase. Clicking on the release will take you to the release flow editor.

The task description is the main element on the dialog. Use the description to write down the purpose of the task and instructions on how to complete it. Again, the description can be edited by clicking on it.

In order to use styled text (headers, bold & italic, hyperlinks, bullet lists, etc.), XL Release supports the Markdown syntax. In essence, this is a visually friendly way to code styling into text. See the Markdown syntax guide for more information.

Tip: use hyperlinks to refer to documents published elsewhere, for example on a WIKI or SharePoint server.

Task status and transitions

Below the description we find three buttons that you can use to indicate that something happened on the task. These buttons are only shown when the task is assigned to you.

Use the Complete button to tell XL Release that the task has been done. After pressing the button, a comment field will appear to allow you to write down some details upon completion of the tasks. (This is optional). After completion, XL Release will advance to the next task in the phase and send the appropriate notifications.

Skip is very similar to Complete. XL Release will mark that task as done and move on to the next task. Use Skip to indicate that in this case, no work was needed or could be done, but that you have to move on in any case. You can use this option for tasks that were not relevant for this release. Since this is not the expected behavior in the release process, a comment is required when skipping a task.

Fail will signal that either something unforeseen has happened that impedes the completion of the task or that you don't know how to solve it. When hitting fail, the release flow is stopped and the release owner is notified.

Task properties

If failing the task is too drastic, but you do want to signal that timely completion of the task is at risk, or that you simply need some help, use the Status flags (upper right-hand corner) to mark the task as being in trouble. The status flag will show up in all overviews to alert the release manager and other coworkers.

Scheduled start date

Use the Scheduled start date to schedule a task to be performed at an exact time. For example, a deployment with Deployit has to start at midnight, or an email has to be sent to all stakeholders at Monday morning, 9am.

Note that the task will not be started on the scheduled start date if it's not the active yet in the flow. All previous tasks must have completed before a scheduled task is started and the scheduled start date is reached. If the previous tasks complete after the scheduled start date, the task will start the moment it becomes active.

Click on "Add a planned start date" to bring up the date picker and select a date and time. During execution of the release flow, XL Release will wait until this time (if set) with the execution of the task. While waiting the task is marked as "Pending".

Dates in XL Release are displayed using the clients OS's timezone. Dates and times are formatted according to the browser's language settings.

Due date

Set a Due date on a task to mark the time that the task has to be completed.

Assigned to

There are two fields below Assigned to. First, the user. This is a single user, identified by his name. This is the owner of the task and responsible for its completion.

Secondly, the task can also be assigned to a team. Teams are useful grouping mechanism for several people that are involved in the release that have the same role. For example, you could have a DEV team, QA team and an OPS team. During planning it can be useful to assign a task to a team only, because it is not clear in advance who will participate in a certain release. If a task is assigned to a team but not to a user, all team members get an email when the team becomes active.

Assignments to users and teams can be removed by clicking the black cross icon on the right.

Gate

A Gate is a type of task that contains some conditions that need to be fulfilled before the release can continue. There are two types of conditions: simple checkboxes and dependencies on other releases.

In the Gate details window, you will find the checkbox section below the task description. If you have the Edit task permission, you can add a checkbox by clicking on 'Add condition' and remove them by clicking on the black cross on the right-hand side.

Checkbox items need to be manually ticked off by people involved in the release. When a Gate task is active, it can only be completed when all conditions have been met, ie. when all checkboxes have been ticked. The Gate task will not complete automatically when all conditions haven been met, the task assignee still has to mark it as completed.

Under the conditions section, we find the dependencies to other releases. Click on 'Add dependency' to have the Gate task wait on other releases. You can wait on the level of release, phase or task. In the screen shot above, there is a dependency on the "Deploy version to QA" task in the QA phase of the Back office services 3.2 release.

Click on "Add dependency" to create a new one or just click on an existing dependency to edit it. You then go into edit mode:

You see a row of three drop down lists. The first line lets you choose a release this gate will wait on. Only currently active releases are shown. When only a release is selected, the dependency will complete when the entire release is finished. The second line lets you choose a phase in the release, and the third line a task. This way you can wait for certain events in a release, e.g. the completion of a task or phase. Notice that phase and task are optional.

When the gate only contains dependencies and no conditions, it will complete automatically if all dependent releases, phases or tasks are completed.

When a dependent task or release fails, the gate will not fail. It will wait until the release is restarted and that task is completed or skipped. A gate will fail if a release it depends on is aborted.

Notification task

The notification task lets you write emails that are sent automatically when the task becomes active. This is an automated task, so it will complete by itself (or fail if the email could not be sent) and XL Release will advance to the subsequent task.

There are three relevant fields to this task:

• To. Put a list of email addresses here. The message will be sent to these recipients.
• Subject. The subject of the message.
• Body. The message body. This is plain text.

Click on any of the fields to edit them. You may use variables.

Deployit task

The Deployit task provides tight integration with Deployit, the Application Release Automation solution form XebiaLabs.

This is an automated task, that tells Deployit to deploy a certain application to an environment. Both application and environment need to be configured in Deployit. The task gives live updates of the deployment process and completes automatically when the deployment finishes.

There are five fields to configure:

• Server. This is the Deployit Server we connect to. Deployit servers can be configured in the Settings section, under Deployit Servers.
• Deployment package. The version of the application to be deployed. Auto-complete is supported in this field. You can start typing and XL Release will retrieve the list of applications that are present in the currently configured Deployit server.
• Environment. The environment to deploy to. Auto-complete is also supported in this field.
• Username. The username to use to connect to the Deployit Server.
• Password. The password corresponding to the username used to connect to the Deployit Server.

You can also use variables in the Deployment package and Environment fields. This allows you to reuse application version and environment across tasks in XL Release. For example, when using variables you can mention the name of the application and the environment you deploy to in a notification task.

Script task

Script tasks contain a Python script that is executed on the XL Release server. This is an automated task that completes automatically when the script finishes successfully.

The script task has a 'Script' field where you can type or paste a Python script. The supported version is Jython 2.5. Jython is the Java implementation of Python. This means that you have access to standard Python, but additionally to all Java libraries that come with Java 7.

When the task becomes active, the script will be executed in a sandboxed environment on the XL Release server. 'Sandboxed' means that the script has very restricted permissions. By default, access to the file system and network are not allowed.

Restrictions can be relieved by adding a script.policy file to the SERVER_INSTALLATION/conf directory. This is a standard Java Security Policy file, where you can put the permissions that a script may have.

The following example shows how to download a file from a web site and save it locally:

import httplib
url = 'www.xebialabs.com'
file = '/tmp/xebialabs.html'
xl = httplib.HTTPConnection(url)
xl.request('GET', '/')
response = xl.getresponse()
myFile = open(file, 'w')
myFile.write(response.read())
myFile.close()
print "Save %s to %s" % (url, file)

In order for this to work, we need to adapt the conf/script.policy file, otherwise the script will fail. Here's a version that allows accessing the network using Pythons httplib and read/write access to the /tmp directory on the XL Release server:

grant {
    // Network access
    permission  java.lang.RuntimePermission "accessClassInPackage.sun.nio.ch";
    permission  java.net.SocketPermission "*", "connect, resolve";

    // File access
    permission java.io.FilePermission "/tmp/*", "read, write";
    permission java.util.PropertyPermission "line.separator", "read";
};

The XL Release server has to be restarted after changing the conf/script.policy file.

Webhook task

A common use case for automatic tasks is to interact with an external system through a REST interface. You could use a script task to send an HTTP query and parse the response; but to spare you the boilerplate, XL release provides a special task for that: Webhooks.

To configure a webhook, you specify the URL to call and the details of the request (HTTP method, request body, authentication). The task will perform the query, parse the response, and optionally extract a result and store it in a release variable.

Webhooks come in two flavors, depending on the format of the HTTP response: XML and JSON. Each has its own way of extracting a result from the response:

• for XML webhooks, you provide an XPath expression to select the value.
• for JSON webhooks, you use JSON path.

To see Webhooks in action, here is an example based on HttpBin, a free service to test REST clients. We'll use the /ip endpoint, which returns the IP of the caller in a JSON response with the following structure:

{
  "origin": "xxx.xxx.xxx.xxx"
}

Here is the configuration of the task in XL release:

Once the task completes, the origin field will be extracted from the response and stored in the ${xlreleaseIP} release variable, where it can be used by other tasks.

Parallel group

The Parallel group allows you to model tasks that have to be executed in parallel. The default flow in a phase is serial: all tasks are executed in order, one after the other.

The Parallel group is a container for a bunch of tasks that are to be executed simultaneously. There are no specific properties to be set on the parallel group, other than the common properties like description, due date, etc.

In the release editor, simply add a Parallel group using the Add task link. Then you can either drag existing tasks into the parallel group, or click on the inner Add task link to create a new task in the parallel group.

In the above example, the two Deployit tasks and the "Divide test cases" will be started simultaneously and the parallel group "Deploy to ACC" will not complete until all tasks have completed. Only then will XL Release start the task after that, "Notify QA installation".

Templates

Templates are like blueprints for releases. You use them to model the ideal process of a release flow. Templates lack certain properties of actual releases. For example, they don't have start and end dates and typically you will use placeholders like variables and teams for information about a release you don't know in advance.

When starting a release, a template is taken as the basis. The release is a copy of the template and will have the values for the variables filled in, start and end dates assigned and teams populated. Note that changes in a template are not reflected in a running release that is created from it. And vice versa: you can change the contents and structure of a release, but those changes are not automatically propagated to the template that was used to create it.

Template overview

The template overview shows all templates that are available to the user. You may not see all templates, because you need the View template permission to see them in this overview.

For each template in the list the following commands are available (provided that you have the right permissions):

• View opens the release flow editor for the template so you can edit it. See template details.
• New Release from template will create a new release based on this template.
• Copy creates a new template that is a copy of this one.
• Delete deletes this template.

Creating a template

The button New template will create a new empty template when clicked.

Template name is the name by which the template will be identified in the overview.

A description can be set to give more information about the template. You can edit the text by clicking on it. The text editor supports Markdown syntax, so you can put styled text and hyperlinks here.

Tags can be set on the template. The tags will be copied over to the releases that are created from this template, to make it easier to search for them in the release overview.

Template details

Editing a template is very similar to editing an actual release. Please refer to the Release details section for a full explanation.

However, there are some differences.

Teams in templates

In teams, there is a specially created team Template owner, that is created when the template is created. It is populated with the user creating the template. This team has all permissions needed to edit a template and create a release. The Release Admin team is not yet available for templates. It will be created when a release is created from the template.

Template permissions

Templates have two sets of permissions. The first table shows the permissions that are applied to the template itself.

• Create release allows a user to create a release from this template.
• View template allows a user to see a template in the template overview.
• Edit template allows a user to make changes to the template: adding tasks and phases and changing them.
• Edit security allows a user to edit teams and permissions on the template.

The second table contains the permissions that are copied over when creating a release. Their purpose is that you can already define teams and permissions for the release beforehand. See Release Permissions for an overview of these permissions.

Importing a template

Templates can be imported from a JSON file. Templates are exported to JSON using the Export to JSON button in the Release Flow editor for templates.

The Import button opens the following popup when clicked:

You can choose a JSON file that was previously exported by XL Release to import and click on the Import button. Once the file is processed, the popup will display the list of imported templates. If these templates contain references to objects that do not exist on the server (for instance, Deployit servers or Gate dependencies), the references are removed and warning messages are displayed.

Variables

For data that may change or is not known in advance, XL Release provides a placeholder mechanism in the form of variables. This is a great way of managing information that

1. is not known when designing a template. For example, the name of the application.
2. is used in several places in the release. For example, you would use the name of the application in task descriptions and email notifications.
3. may change during the release. For example, the version number of the release that is being pushed towards production.

Variables are just snippets of text in a text field surrounded by ${ }. So you can define a variable called name by simply typing ${name} in a text field.

Variables are supported in

• Titles of phases and tasks
• Task Descriptions
• Task owners
• Deployit fields
• Notification task fields
• Gate conditions
• Scripts

You are obliged to give values for all variables when starting a release. Values are filled in the task when the task is started. You may change the values of variables during an active release, but that will affect only the tasks that are in planned state and still have to be executed.

Variable usage example

Let's look at an example. We'll create a template that deploys an application to a test environment, and assigns testing to QA. When testing succeeds, an email notification is sent. If it fails, we try again with the next version of the application.

First we will create a template:

We use the variable ${package} in the phase title and in the title of various tasks. We will also use this variable to tell Deployit to deploy this package:

Using a variable is easy: just type the variable in ${ } format in the text field. You can combine normal text with one or more variables (See QA testing task above). In the case of Deployit however, we recommend using a a dedicated variable for the entire field, because this will enable auto-completion later on.

We will now create an actual release from the template by clicking on the New release button. XL Release will scan the template for variables and will ask to provide values for all of them.

The Deployit variables are marked with special icons and auto-completion is available for those variables. XL Release will query the Deployit Server for available packages and environments and display them in a drop-down menu.

Once the release has been created, the release flow will be displayed with the values of the variables filled in.

Note that you can still change variables by editing the fields. Changing the values of the variables can be done on the Release properties page.

Now suppose that QA testing for BillingApp 1.0 failed, and we need to repeat the procedure for the next version delivered by the Dev team.

We will restart the QA phase by pressing the Restart Phase button. When the phase is restarted but before the release flow is resumed, we get an opportunity to change the variables:

When the release is resumed, the phase is duplicated with the new variable values in place, but the old phase still has the old values.

Release life cycle

A release can go through various stages. First a blueprint of a release is defined as a template. From the template, a planned release is created. The release is a carbon copy of the template but has not started yet. When started, a release becomes active and the phases and the tasks in a release are executed. When all is done, the release is completed. We will first explain the different stages of a release from a practical perspective. See the life cycle diagram below for a detailed overview of all the states a release can be in.

Templates

A template is a blueprint for similar releases. A template may describe a procedure that is used to deliver different applications. Or it can be specific to the steps involved to release a particular application, but will be reused for the different versions of the same application.

In a template, we don't know all details in advance. Think of application name and version, deployment environment, etc. Therefore we typically make heavy use of placeholders like variables and teams in templates. In a template you may for example define the teams but leave them empty, to be filled in once a release based on the template is started.

Creating and starting a release

When creating a release from a template, it has not started yet and will first be in Planned state. This is an important state, because before the release starts and people are notified by email that tasks are assigned to them, the release owner still has to do some configuration.

The following should be configured before a release is started:

• Variables. When starting a release, the Create Release page will ask to assign values to all variables.
• Teams. In a planned release, populate the teams or revise the members of each team.
• Start dates and due dates. Set scheduled start dates and due dates on crucial tasks. It is not needed to specify due dates on all tasks, but you may take this opportunity to revise all dates.
• Dependencies to other releases in gate tasks can only be set on active releases. It makes therefore little sense to already specify them in a template. So the release owner should revise all dependencies on other releases before starting.

A running Release

In a running release, XL Release will start planned tasks in the right order and either execute them if they are automated, or send an notification to the people responsible for its completion.

Generally speaking, there will be one or more tasks that are currently active. Users that have tasks assigned to them will find these tasks in their task overview and are expected to mark them as completed in the XL Release UI when done.

The release may be paused when the current active tasks are failed. The release owner then needs to decide what to do: assign the task to somebody else to do, or skip it.

Another case when the release may be stalled is after restarting a phase. Tasks are copied in that scenario and may have erroneous start and due dates or be assigned to the wrong users. The release owner is given the chance to configure the tasks correctly before carrying on.

Restarting a phase

In an active release, you may abort the current phase and restart the execution from any phase in the past. This may come in handy if some parts of the release procedure need to be repeated. For example, if QA rejects a certain version of the application to be released and the test phase will have to be repeated with an updated version.

When you restart the release from a previous phase, the current phase is interrupted and all remaining tasks are skipped. The release is paused and a copy is made of all previous phases that need to be repeated. The release owner can change variable values and task details before the release flow is reinitiated.

Here's an example of how restarting a phase works in practice.

Suppose we have a release with three phases: QA, UAT and Production:

The QA phase was started with version 1.0 of the product, but some bugs were found and QA can not sign off. So the Sign off by QA task has failed. The Dev team is notified and produces a fix: version 1.0.1. We can now start the QA phase again for version 1.0.1

We do so by clicking on the Restart Phase… button in the top bar. This produces the following dialog, asking us from which phase the release should be restarted.

We can confirm restart by pressing Continue. We can still back out by clicking Cancel - no changes will have been made.

After clicking Continue, the release is paused and the new phases are created. Before the release flow is resumed again, the user restarting he phase still has the opportunity to make some changes. First of all, a confirmation dialog is displayed that offers two choices, to resume now or later.

All variables that are in use are displayed, so we can conveniently change the package version from 1.0 to 1.0.1 and click Resume now to proceed right away.

If we click Resume later, the release will be in the Paused state (see below) and we still have the opportunity to change task assignees, due dates, etc. We can even decide to delete some tasks that are not relevant anymore.

After the dialog has been dismissed, we see that a phase called QA (2) has been added. We can still modify its contents. Suppose that the task Update test scenarios is not relevant anymore, so we will simply remove it.

When paused, the release can be resumed by clicking on the Resume Release button in the top bar.

Release life cycle states

Here is a detailed breakdown of all the states a release can go through.

All releases are derived from a template (this may also be an empty template), so the first state of a release is Template.

When a release is created from a template, a copy is made from the template and the release is in Planned state.

When a release starts, it enters the In progress state. Phases and tasks will be started and notifications will be sent to task owners to pick up their tasks.

The state of a an active release is reflected by the state of the current task. In the case of multiple tasks running in a parallel group, the state of the topmost parallel group is taken.

• In progress -- the current task is in progress.
• Failed -- the current task has failed. The release is halted until the task is retried.
• Failing -- some tasks in a parallel group have failed, but other tasks are still in progress.

It's possible to restart a phase when the release is any active state (in progress, failed or failing). After restarting a phase, the release is in paused state. This is a state where no tasks are active. It is similar to the planned state, and allows the release owner to tweak due dates and other task variables before the release is resumed.

There are two end states: Completed and Aborted. When the last task in a release finishes, the release enters the Completed state. A release can be manually aborted at any point, it will then end up in the Aborted state.

Task life cycle states

In an active release, tasks will transition through different states. The following diagram shows the lifecycle of a task.

Normal flow

Tasks start in planned state. This means that they are not active yet. All properties can still be edited. When the release flow reaches a task and it becomes active, there is a choice. If a scheduled start date is set and this date has not passed yet, the task goes into Pending. Otherwise the next state will be In progress. At this point, notifications are sent to the task owner and the user may trigger the next transition by pressing the Complete, Skip or Fail buttons in the UI.

Normally, when a task is completed by a user, or an automated task is performed without errors, the task goes into Completed state. This is an end state and it means that the task has completed successfully. The release flow continues with the next task in the flow.

A user may also skip a task that was In progress or Failed. In that case, the task goes into the Skipped state. The Skipped state is functionally equivalent to Completed. The only difference is that it implies that no actual work has been done on the task.

Tasks may also be completed or skipped in advance: before the execution flow has reached this task. In that case, the task shows up as completed (or skipped) in the release flow editor. Before the release flow has reached this task, it still possible to reopen the task, moving it back in the planned stated. When the release flow hits a task that was completed or skipped in advance, the state is made definite and the task can't be reopened again.

Fail and abort

If a user fails a task, or an automated task encountered an error, the task goes into the Failed state. This triggers a notification to the release owner that something is wrong. The task can then be either restarted (it will go to In progress state) or skipped if no more work will be done (it will go into Skipped state).

There is also a Failing state. This state only applies to the Parallel Group task that contains subtasks. This state indicates that one of the subtasks is in Failed state, but that other tasks are still running.

Transitions to and from the Failing state:

1. In progress -> Failing: a subtask fails and other subtasks are still in progress.
2. Failing -> In progress: a failed subtask restarts (and was the only failed) or is skipped, and there are other subtasks still pending or in progress.
3. Failing -> Failing: a failed subtask is skipped, but of the remaining subtasks there are some that are failed and some that are pending or in progress.
4. Failing -> Failed: there are some failed subtasks and the last subtask that was still pending or in progress completes or fails.

Completion of gate tasks

Gate tasks with no conditions and only dependencies will complete immediately if their dependencies are completed. If all dependencies are completed, but at least one of the dependencies is an aborted release, the gate goes into failed state. If any conditions are set, the owner of the task has to complete the gate task by hand.

Notifications

XL Release will send out emails when certain events happen in a release. Here's an overview of all the emails that are sent out. See the SMTP server section on how to configure the email server and sender for these messages.

1. Task assignment. An active task has been assigned to somebody else. The new assignee receives a message telling them they are responsible for completion of this task.
2. Task failed. When a task fails, the release owner is notified so they can take action. Manual tasks fail when their owners indicate that they can't proceed and press the Fail button. Automated tasks may fail when they can't be executed correctly. The release owner then has the responsibility to resolve the issue.
3. Task started. A task was started by XL Release and is now in progress. A notification is sent to the owner of the task to alert them. If the task doesn't have an assignee, but it has been assigned to the team, all team members receive a message. If there is no owner or team assigned, the release owner receives a warning message that a task is in progress but nobody is responsible for it. This works slightly different for automated tasks: messages are sent out to individual owners or team owners, so they can keep track of automated procedures they are responsible for. However, the warning message for release owners for unassigned tasks is not sent.
4. Comment added. When somebody adds a comment to a task, a message is sent to the task owner and all team members of the team assigned to the task.
5. Release flagged. The release owner is notified when somebody adds a flag status message to a task or the release to indicate that attention is needed or the release is at risk.

Pipeline

The Pipeline view shows an overview of all active releases, which phases they are in and which task is the currently active task.

A flag is displayed next to the release title if a status message is set to indicate that the release is at risk. All phases are displayed in a linear fashion. Completed phases have a gray tick mark inside them. An active phase shows the currently active task. Gate tasks are red, all other tasks are light blue. If a phase starts or end with a gate that has not passed yet, it is shown in the pipeline view with the gate icon .

Calendar

The Calendar shows an overview of all releases on a month-by-month basis.

The navigation bar on the right offers a convenient way to browse months. It is hidden by default, but can be opened by clicking on the gray vertical bar with triangle on the left-hand side of the calendar.

To see the current month, press the Today button in the top bar.

Next to it, the Filter options give you control over which releases are shown on the calendar.

• Active releases: show releases that are currently in progress.
• Planned releases: show planned releases that have not started yet.
• Completed releases: show releases that have completed or that were aborted.
• My releases: show releases that the current logged in user is the Release owner for.
• Only flagged: show releases that are flagged with a status message to indicate that they need attention or are at risk.

You can also filter by release title or tag by using the text box. This will work in addition to the filters already selected.

Releases are displayed as light blue bars on the calendar. They may be adorned with warning icons to indicate that some attention is needed. A flag is displayed when a status message is set on the task. A red icon with exclamation mark is displayed when there is a dependency conflict. A dependency conflict occurs when a gate task in a release has a dependency on another release, but this release will end later than the start date of the current release. It helps you identify 'schedule shift' when one ore more releases need the completion of other releases.

You can get more information on a release by clicking on it. A small window with information will appear.

For the release, this window will display the title, followed by the currently active phases and tasks. Further on, a summary is shown of dependencies to other releases. Depends on shows the releases that have to complete before a Gate task in this release can complete. Alert icons are displayed if this dependency is at risk. Depending on this release are the releases that are waiting on this release. Tip: Hovering over the dependent releases will highlight them in the calendar.

Reports

The reports screen aggregates shows graphs and statistics based on the historical release data present in the XL Release repository. It is accessible to users with the View Reports permission.

On the top of the page you can select the time period you are interested in: last 30 days, last 3 months, last 6 months and all time. The choice is reflected on all graphs and tables on this page.

The Number of release per month bar chart shows how many releases were finished in a particular month.

The table Top 10 People most involved shows which users have spent most time and handled most tasks in the selected period.

Top-10 Longest tasks is an overview of which tasks took most time to be completed and who was responsible for that task.

For a higher-level overview of what parts of the release took most time, there is the Top-10 Longest phases table.

Settings

The Settings section contains personal preferences and global configuration options for XL Release.

Profile

The Profile page allows you to set your name, your email address and your password.

The email address is needed to send notifications, for example when a task that is assigned to you starts. When the XL Release server is configured to use your company's LDAP directory, it will attempt to automatically find your name and your email address. You may change the name and address that the server has found.

External users cannot change their passwords from XL Release.

Users

The Users page allows you to view and edit XL Release Users. This page is only displayed to users with either Admin or Edit Security permissions.

Only users that have logged in at least once are listed in this page.

There are two kind of users in XL Release.

• Internal users are managed by XL Release and can be added and removed by an administrator.
• External users are maintained in an external system like a Active Directory. See the section on Configuring LDAP security in the System Administration manual.

You can create an internal user by clicking on the New internal user button. You will see this dialog pop up:

Fill in the required details to create the user. Note that Username is the name that is needed to log in, and Name is the full name of the user that is being displayed in overviews and tasks.

On the overview, administrators can change the password or email address of an internal user by clicking on it. Note that you cannot change the password of an external user from XL Release, that is maintained in LDAP.

Roles

The Roles and Permissions screens let you set global permissions, i.e. security settings that apply across the entire system. These pages are only displayed to users with either Admin or Edit Security permissions.

A role is a group of login names or LDAP groups. 'Principals' is the technical term for an entity that is either a user or a group. You can assign permissions to roles in the Permissions screen. Use the New Role button to add a new role. Roles can be deleted by using the black cross on the right-hand side of the table.

Change the name of a role by clicking on it. The role is defined by which principals it contains: this is a comma-separated list of user ids or groups from the LDAP repository. For example in the above screen shot, we see that 'john' and 'mary' are Administrators, and all users in the 'all-it' group are Users in XL Release.

The naming of the roles is not restricted. You can give a role any name you want, and there are no predefined role names.

Changes or not applied until you press the Save button. Use the Reset button to discard your changes and reload the current settings from the server.

Global permissions

On the Permissions screen under settings, you can assign permissions to roles.

For each role, a list of permissions is displayed that can be enabled or disabled. The following permissions are available:

• Admin. When granted this permission, you can do anything.
• Login. You need this permission in order to be able to log in to XL Release.
• Edit security. Gives access to the Roles and Permissions screens and also allows the user that has this global permission to edit security on a release and templates.
• Create Template. Permission to create a new template
• Create Release. Permission to create a release from any template. See also the Create release permission on a single release.
• View Reports. Permission to view the reports.

Changes are not applied until you press the Save button. Use the Reset button to discard your changes and reload the current settings from the server.

Apart from global permissions, security can also be enforced on the release level. On releases and templates, other permissions apply and they are granted to teams that are defined within the release.

See Release Permissions and Template Permissions for an overview of these permissions.

Deployit servers

The Deployit Servers page is used to configure connections to XebiaLabs Deployit servers. This page is accessible to users with Admin permissions.

The page shows a list of currently known servers and allows you to configure them.

The overview shows the Deployit server name, as used by the Deployit Task, followed by the connection URL and the name of the Deployit user that is used to make the remote connection.

Add a server by clicking on the New server button. You will see this dialog pop up:

Set a symbolic name in the Server Name field. Inside the XL Release application, the Deployit Server is referred to by this name.

The connection URL is the internet address by which the Deployit Server is reachable. It is the same address you use to access the Deployit UI.

The Username is the login ID of the user in Deployit that XL Release will use, followed by the Password.

This user will be used to query Deployit for its available Applications and Environments, in order to support code completion in the Deployit task and variables section.

The Test button will try to log in to the Deployit Server with the configured URL and credentials and will show a message whether the connection was set up correctly or not.

We recommend setting up a user in Deployit that has read-only rights for this. To do deployments, specify a user and password on the Deployit Task directly. This provides fine-grained access control from XL Release to Deployit. If no user is specified on the Deployit Task, the user configured on the Deployit Server will be used to do deployments, provided that it has deployment rights on the Deployit Server of course.

SMTP server

XL Release sends out various notifications to users of the system by email. The SMTP server page allows you to configure which email server is used to send the emails. This page is only accessible to users with Admin rights.

Host is used to specify the internet address of the mail server, followed by the port it is listening on. Check with the system administrator which values to use, and whether to use TLS (see option below) to secure the connection.

Most SMTP servers require authentication. Use the Username and Password fields to set the credentials of the user that will connect. The From address is the address that is used in the emails for the sender. People will get emails on behalf of this user. You must enter a valid email address here, but you can add a name to by using the following syntax: Full name <name@example.com>. Please note that some mail servers will ignore this setting and set the authenticated user as the sender of the emails.

Press Save to apply the changes.