Teamstudio Build Manager is truly a unique product; the world’s only build management tool specifically engineered to work with native HCL Domino apps. It’s a very powerful, and highly configurable tool, but there are times when you might wish that there was an action to perform a certain step of the build, but you find that it doesn’t already exist. If you’ve ever had that thought, then this post is for you.

An underutilized feature of Build Manager is the ability to create a custom promotion step. Similar to the other prebuilt promotion steps, anyone with HCL Domino Designer and an understanding 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 may seem daunting, once you familiarize yourself with how the process works, it’s pretty straightforward, and can be a very powerful feature.

Let’s start with a simple example. Suppose you wanted to force your promotion user to add a set of comments that will be added to the promotion log, but differ from what may be captured already by Build Manager? There are four parts to the process of creating a custom promotion step - we’ll use this example to walk through them one-by-one.

1. Create the Custom Step Action Form

First, we need to create a new form that will 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 four fields (and their labels) 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.

You have just created the form that’s used to configure your custom promotion step action. The form in Domino Designer should look similar to the image below:

2. Create the Script Library

Now that you have created the form for configuring the custom step action, you need to write the 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, we’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 to create the script library:

Open the database BMSL.nsf in Domino Designer, and navigate to the Script Libraries design elements.
Copy the script library titled “customLibTemplate” onto your clipboard.
Open the Build Manager database in Domino Designer and navigate to the Script Library design elements.
Paste the “customLibTemplate” script library into the Build Manager database.
Rename the script library to “customLibComment”.

Now that you have the script library in place, you need to modify the design to work with your newly created form during the promotion process. Open the script library you just copied/pasted in Domino Designer. The script library already contains the structure needed to integrate with the promotion action. Have a look at the function titled “userInput.” This function already has the required parameters being passed into it for you 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.

Now you need to create 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. Then, if the user did add a comment, it will write the comment into the promotion log.

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 this example, you will only be using “docAct” and “util.” Here’s the LotusScript code:

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

3. Making It All Work

You 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. Here is the LotusScript, which can be used for your design changes:

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

And that’s it!

4. The Customizations in Action

You now have a form for configuring the custom step action, a script library that obtains the comment and puts it into the promotion log, and you have registered it to be recognized by Build Manager as a custom step action. Now you can use the new custom step action. Select a promotion or build path that’s safe to run tests with! Then, 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).

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.

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, let’s say 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, you need to indicate that the comment is required and change the step number on the step control tab to be 1, which will force this custom step action to happen first. You should also provide 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.

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

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 Domino 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! Have fun, and if you come up with any neat ideas, let us know!

If you have questions about this or any aspect of HCL Domino application management, click below to start a conversation. We love to chat!

Contact Us