How to Add a Custom Promotion Step with Build Manager in 4 Parts

While using Teamstudio Build Manager, have you ever thought, “I really wish there was an action to do _________?” An underutilized feature that’s contained within Build Manager is the ability for anyone to create a custom promotion step. Similar to the other prebuilt promotion steps, anyone with IBM Domino Designer and knowledge of promotions can create a custom promotion step. This does involve the creation of a new form and a LotusScript Library to contain the custom functions that you want to trigger during a promotion. Although this seems daunting, when you familiarize yourself with how the process happens, it can be a very powerful feature.

So let’s start with a simple example. What if you wanted to force your promotion user to add special comments that’ll be added to the promotion log, but differ from what may be captured already by Build Manager? Let’s walk through the four parts to create this custom promotion step.

Part 1: Creating the Custom Step Action Form

We’ll first need to create a new form that’ll be used when adding the new custom step action to the promotion path. Follow these steps to create the form so that it’ll look similar to an existing promotion action:

  • Open the Build Manager database in Domino Designer
  • Locate the form named “email notification” and make a copy of it in the Build Manager database
  • Change the name of the form to match the following:
    • Name: “Comment Prompt”
    • Alias: “actComment”
  • Open the form for editing
  • On the tabbed table, remove the field and labels for the four fields that currently exist (EmailRecipients, EmailSubject, EmailOptions, and EmailBody)
  • Add a label titled “Require Comment?”
  • Add a corresponding field called “RequiredYN” with the following attributes:
    • Type: Checkbox     (on the field info tab of the properties dialog)
    • Choices: Yes     (on the control tab of the properties dialog)
  • Modify the default value for the following fields to have these formulas:
    • ActionTitle: "Promotion Comment"
    • ActionViewDescription: ActionTitle+" : "+Description
  • Save and close the form

This will now be the form that’s used for configuring this custom promotion step action. The form in Domino Designer should look similar to the image below:

bm-the-form.png

Part 2: Creating the Script Library

Now that we have the form for configuring the custom step action, we need to make some code to use in the promotion. There’s some initial setup of the script library that needs to be done in order to integrate with the Build Manager API. To simplify this process, I’ve created a template script library for this purpose, which is in the database “BMSL.nsf” that you can download by clicking here. Follow these instructions for creating the script library:

  • Open the BMSL.nsf in Domino Designer and navigate to the script libraries design elements
  • Copy the script library titled “customLibTemplate” onto your clipboard (CTRL-C)
  • Open the Build Manager database in Domino Designer and navigate to the script library design elements
  • Paste the script library into the Build Manager database
  • Rename the script library to “customLibComment”

Now that we have the script library in place, we need to modify the design to work with our newly created form and to also work during the promotion process. Open the script library in Domino Designer. The script library will already contain the structure needed to integrate with the promotion action. Where we’ll focus is in the function titled “userInput.” This function already has the required parameters being passed into it for us to obtain all the information about the promotion that’s occurring. The script library is well documented and explains each of the parameters being passed into the function.

What we now need to design is the LotusScript code that’ll look at the custom step action document and determine what the custom step action should do. We’ll make the LotusScript code very simple:

  • It will reference the custom step action document to determine if the promotion should stop or continue if the user doesn’t enter a comment
  • It will write the comment into the promotion log if the user added a comment

One of the parameters passed into the function is “docAct.” This is the custom step action document where you can configure whether the promotion should stop or continue if the user enters a comment or not. Also available from within the function are the following:

  • docPromo: the promotion path document for the promotion being run
  • docConfig: the main CIAO! configuration document (the parent of docPromo)
  • util: a utility that offers some Build Manager specific functions like writing to the log file or setting variables

For our example, we’ll only be using “docAct” and “util.” The LotusScript code will perform the following actions:

  • Determine what should happen if the user doesn’t provide a comment
  • If the user does provide a comment, then add it to the promotion log

Below, you’ll see the LotusScript code that performs these actions:

Dim stopPromo As Boolean
' This will be set based on the setting on the custom step action document.

Dim outputStr As String
' This will be where we temporarily store the comment from the user.

Dim ws As New NotesUIWorkspace
' This is the Notes workspace. This will be used to obtain the user's comment.

' First, let's determine what needs to be done if the user doesn't enter comments.
If docAct.Hasitem("RequiredYN")Then
If docAct.RequiredYN(0)<>"" Then
' If the field has a value, then the user must enter a comment or the promotion will be stopped.
stopPromo=True
End If
End If

' Second, let's prompt the user for the comment. Here, we're using a workspace prompt to obtain the comment.
outputStr=ws.Prompt(PROMPT_OKCANCELEDIT, "Enter Comment", "Please enter a Comment to be added to the Log")

' Third, we now need to validate if we are to allow the promotion to continue if they didn't enter a comment.
If outputStr="" Then
If stopPromo=True Then
' The custom step action document indicates that a comment is required.
' Since it wasn't provided, we can exit the function here and the promotion will be canceled.
Exit Function
End If

Else
' The user provided a comment. Now, let's add the comment to the promotion log.
' This is done by using the ActionExtensionUtility parameter.
util.log outputStr
End If

' Since everything has happened as planned, we can set the "userInput" function parameter to "True."
' This will allow the promotion to continue through the remaining promotion steps.
userInput=True

Part 3: Making It All Work

We now have a form to configure the custom step action and a script library that’ll prompt the user for a comment. This will determine what to do if the user doesn’t provide a comment and will also add the comment to the promotion log if it was provided. The third and final part of this design change is to “register” the new custom step action with the existing Build Manager functionality so it can be used. This is a simple step to perform. It requires you to edit an existing script library. Follow the steps below to “register” the new custom step action:

  • Open the Build Manager database in Domino Designer and navigate to the script library design elements
  • Locate and open for editing the script library titled “Custom Action Extensions”
  • Open the function titled “RegisterCustomActions”
  • Within this function is an example of how to “register” the custom step action. Below, I’ve included the LotusScript, which can be used for our design changes:

Dim ae As New ActionExtensionInfo("customLibComment", "CustomClass", "actComment", "Comment Input")
AEUtil.RegisterAction ae

And that’s it!

Part 4: The Customizations in Action

We now have a form for configuring the custom step action, a script library that performs the needed functionality to obtain the comment and put it into the promotion log, and we have registered it to be recognized by Build Manager as a custom step action. Now let’s use the new custom step action. Select a promotion or build path that’s safe to run tests with. Then, we need to create the custom step action. To do this, first, change to the “Admin” tab in the navigator. Then, expand the “Create -> Actions…” section on the navigator and select “Custom…” (as pictured below).

create-custom-action.png
 

This will present you with a dialog box that lists all custom step actions that have been “registered.” If this is your first custom step action, then you should see the following dialog box.

action-selection.png
 

Select the “Comment Input” option and then click “OK.” This will now create the custom step action document. From here, you can indicate whether the comment is required and also change when in the promotion process the user is prompted for the comment. For this example, we want them prompted for the comment at the beginning of the promotion process and we want to require them to enter a comment. For this, I’ve indicated that the comment is required and I’ve changed the step number on the step control tab to be 1, which will force this custom step action to happen first. I also provided a description for this document, which will be displayed in the view.

Once this document has been saved, it’s time to test the new customization. Start the “Promote Database” process. Depending on how you have configured your promotion path, the prompt to enter in the comment should be presented very close to the start of the promotion. You should see a prompt similar to what’s pictured below.

comment-prompt.png
 

Once a comment is entered, it will print to the promotion log, as pictured below.

comment-in-log.png
 

So that, in a nutshell, is how you can add a custom step to your promotion path! There are many additional ways to customize and extend the functionality of Build Manager beyond just a simple prompt for a comment. One of the most common requests we’ve received is to integrate with another Notes application, primarily to select and retrieve values from a document and then populate the values into the promotion log. Another request we’ve received is to disable any “prohibit design refresh or replace to modify” flags that might be set in the source design prior to a promotion. In reality, the possibilities of extending the functionality of Build Manager are endless, so get your thinking caps on and go for it!

-Brian Arnold, Technical Director, Teamstudio

We released Build Manager 8.1 on Nov. 1!
Read the release notes to see what's new.