Workflow activities for invoking a Runbook from Team Build

  • Article

On a project there is a need to invoke a runbook for the following scenario:

  1. Product source code is stored in TFS source repository.
  2. Daily and gated build definitions are created in the team project.
  3. When the team build is triggered, a Windows Workflow (defined in Build Process Template) will be started on the build agent.
  4. After the workflow initializes workspace, gets source code, runs MSBuild successfully, the test will be started.
  5. The workflow starts an Orchestrator runbook to perform the test asynchronously.
  6. For gated build, the workflow will wait for the runbook to be completed in order to decide whether to commit the code changes or not.  For daily build, the runbook takes cares of test case results importing and the rest.

In order to integrate with Team Build process smoothly, two workflow activities were written and shared at https://orchestrator.codeplex.com.  Please go to the source code area to download the project:

image

Two activities are:

  • StartRunbook: invoke a runbook via web service.
  • RunbookJobStatus: check the runbook job status and return values when it’s completed.

A simple workflow as a part of build process template (modified from DefaultTemplates.xaml) looks like:

image

The input parameters for StartRunbook are:

  • OrchestratorUrl: URL of the Orchestrator web service.
  • RunbookPath: full path of the runbook to be invoked.
  • BinariesDirectory: a network share where the product binaries being built can be accessed by the runbook.
  • BuildConfiguration: e.g. Debug/Release/Checked/Retail, etc.
  • CustomParameter: extra parameter passed to the runbook.

The output is the job ID.  The input parameters for RunbookJobStatus are:

  • OrchestratorUrl: URL of the Orchestrator web service.
  • JobId

The output parameters are:

  • TestOutcome: e.g. Passed/Failed/Inconclusive, etc.
  • RunbookReturnData: other runbook return data as a dictionary. 

The runbook to be invoked is expected to have the following parameters:

  • DropLocation: where the binaries are.
  • BuildNumber: build number
  • TeamProject: name of the team project
  • BuildDefinition: name of the build definition
  • ShelveSetName: name of the shelveset for gated build, or empty string.
  • BuildReason: see MSDN documentation
  • BuildUri: the URI of the build detail object.
  • RequestedFor: user name who requested the build, e.g. the user who runs “tf submit” for gated build.
  • BuildConfiguration: e.g. Debug/Release/Checked/Retail, etc.
  • CustomParameter: extra parameter passed to the runbook.

The runbook is expected to return at least “TestOutcome” as a string.  If any of those parameter is not defined, the StartRunbook activity will not invoke the runbook.  If the runbook needs any other details it can use “Get Build Details” activity in TFS IP to query.

If there is any issue, please let me know.  Have fun!