Example 1: Creating and running procedures

Procedures are the basic automation objects in CloudBees CD/RO. They are used to implement tool integrations and can be used for almost any automation task, such as running scripts and command line actions.

Procedures are made up of steps. A command step invokes a block of shell or script commands on a CloudBees CD/RO agent.

In this example, you create a simple procedure that:

Produces standard I/O output from a CloudBees CD/RO agent machine.
Accepts input from parameters (both static and dynamic).
Runs steps conditionally.

You also customize the runtime job name and step summaries.

Because procedures run inside of projects, you must create a project first.

Create a project

Before you create a procedure, you need to create a container for the procedure, which is called a project. Projects are root-level objects that can contain procedures, pipelines, releases, applications, and other modeling objects. For more information about objects, see Understanding CloudBees CD/RO objects.

To create a project:

Select the CloudBees CD/RO main menu.
Navigate to DevOps Essentials Projects.

The project list appears.
Select New+ in the upper right. The New Project dialog appears.
Select Create New.
Enter the project name Trial Guide (or similar name) and then select OK.

You will not be using credentials (secrets), so when asked if you want to create or edit credentials, select No.

After the project is created, you can search for it by name. When it is displayed, select the menu under Actions to access the project’s attributes.

Create a procedure

Now that you have a project to contain objects, do the following to create a procedure.

From the CloudBees CD/RO main menu, navigate to DevOps Essentials Procedures. The list of procedure objects displays.
Select New+ in the upper right to add a procedure. The New Procedure dialog displays.
Select Create New.
Enter a procedure name such as Trial Procedure. Select the target project that you created above (for example, Trial Guide) and then select OK.

You are now in a procedure. The Hierarchy Menu on the left appears, as well as a Procedure menu on the right.

Add a step

When a procedure is first created, it has no steps to execute, so you must add steps.

Select There are no Steps. Add one + to begin adding a step. The New Procedure Step dialog appears.

Select Create New.
Provide a name, Hello World, and a description for the step — A step to echo out a simple message.
Select Definition in the upper right of the dialog to define the functionality of the step.
In the Command field, enter this command to be run: echo "Hello world".
Select OK.

Your Hello World step is displayed in the list of steps.

Run the procedure for the first time

Select the Run Procedure icon (green arrow) on the right, and then select New Run. The Run Procedure dialog box appears. Select OK. Note the job’s progress.

The abort button can be used to halt a procedure job.
View the job details by selecting Procedure Runs at the top of the page, then selecting the job number. Select the job once again to be able to view the log.
Select the icon under Log to view the job output.

You should now see the Hello world message.
Close the job dialog.

Add a parameter

From the breadcrumb at the top of the window, return to the procedure by selecting Trial Procedure.
Open the Procedure menu on the right and then select Parameters.
Add a parameter by selecting There are no Parameters. Add one +. The New Input Parameter dialog appears.
Provide the the following values:
Name - greetName
Description - Name to use for the "Hello" greeting
Label - Greet Name
Select Custom Validation to enter a validation script.

In the Provide DSL box, enter the following DSL code. This code prevents entries that include the space character.

if(args.parameters['greetName']?.contains(" "))
    return "No spaces allowed!"
else
    return null▼

Select OK.

When the validation script is saved, CloudBees CD/RO runs the DSL script to validate it. The args.parameters['greetName'] returns null in this context because the parameter hasn’t been set yet. The question mark tells DSL to ignore what follows when this is null.

Select OK to complete the parameter definition.
To exit the Parameters dialog, select X in the upper left or the Esc key.

Use the parameter in a step

Duplicate the Hello World step by selecting the Step icon in the upper right, or the plus (+) next to Steps in the Hierarchy Menu on the left.

Select Copy Existing.
Select the Hello World step to copy.
Enter the new step name Hello <greetName> and update the description with the text A step to echo out a greeting to someone. Select OK. (The new step name appears after the step is saved.)
To edit the new step, select the step name or select Step Definition under the Actions menu.
Modify the command block so that it includes only the command echo "Hello $[greetName]"
Select OK.

Run the modified procedure

Select the Run Procedure button (green arrow) to select a run option.
Select either New Run or Last Run. The latter will remember any user-supplied parameter settings. (In this case, there were none, so both options behave the same way.)
Try supplying this name, which includes spaces: A DevOps Guru. (Because of the validation code you supplied, this parameter field does not accept such an entry.)
Now enter the name DevOpsGuru (without spaces) and select OK.
Navigate to the Job Details using the Action menu and examine the step’s log file. You should see Hello DevOpsGuru.
Exit this job’s dialog.

The Rerun button (green arrow in a circle) can be used to run the procedure again with this job’s parameter values already filled in, based on the previous run.

Create a multi-option parameter

Create a new input parameter that enables you to select from a list of options before running the procedure.

Navigate to the procedure using the breadcrumbs.
Using the Procedure menu on the right, select Parameters. The Parameters dialog appears.
Create a new input parameter by selecting Input+ in the upper right. Supply the following information:
Name - cdUser
Description - A list of users from CloudBees CD
Label - CD User
In Parameter Type, select Dropdown Menu, and then select Load options using DSL.
Supply the following DSL code:
```
import com.electriccloud.domain.FormalParameterOptionsResult

def options = new FormalParameterOptionsResult()
getUsers().users.each { aUser -> options.add(aUser.userName, aUser.fullUserName)}
return options▼
```
When the script is saved, CloudBees CD/RO runs the DSL script to validate it. You can use the DSL IDE to create and debug them. If there are dependencies on other parameters, you’ll need to include their definitions in the test script. For example:
```
def args = [parameters: [aParameter: "Parm value"] ]▼
```
Select OK to save the new parameter and then close the Parameters dialog. You are returned to the step object list.

Use the multi-option parameter in a step

Duplicate the second step and modify it to use the new parameter.

From the list of step objects, create a new step using one of the methods discussed earlier.
In the New Procedure Step dialog, select Copy Existing, and then select the Hello <greetName> step.
Change the name of the step to Hello CD User.
Select Definition.
Modify the Command block to include the parameter substitution $[cdUser] so that the new command block is echo "Hello $[cdUser]".
Select OK.

Rerun the procedure

Select the Run button (green arrow) and then select Last Run.
Fill in the parameter values. The pull-down options are populated with a list of users that have been defined in your CloudBees CD/RO instance.
To view the step log for the Hello CD User step, select Job Details from the Actions menu, then select the View Log icon in the upper right. You should see your "Hello" text displayed.

Customize the job name and job step summary

Now, modify the procedure to create a job name based on the name of the procedure and a count.

Navigate to the Trial Procedure editor using the breadcrumb, and then select Details from the Procedure menu on the right.
In the Job Name Template field, add the following syntax to override the blank default value:

$[/myProcedure]-$[/increment /myProcedure/count]

This code creates a job name based on the name of the procedure (from /myProcedure) and a property (count) stored on the procedure property sheet (/myProcedure). The increment function creates the property if it doesn’t exist, and increments it by one.
Select OK.
Edit the last step definition using the Action menu. In the Command field, below the echo command, add the following:

ectool setProperty /myJobStep/summary "Hello $[cdUser]"

Run the procedure with the new job name

Select the Run button and select Last Run. Note the new job name format.
Navigate to the job details and note the new job step summary value.

Create and use an output parameter

Navigate to the Trial procedure to create an output parameter.

From the Trial procedure, select the Procedure menu on the right, and then select Parameters. The Parameters dialog appears.
Select the Output Parameters tab and add an output parameter called whoRanMe.

Select OK. Close the Parameters dialog.
Add a new procedure step and name it Set output parameter.

Select the + beside Steps in the Hierarchy Menu to add a step.
Navigate to the Definition tab.
Add the following shell command in the Command field:

ectool setOutputParameter whoRanMe "$[/myJob/launchedByUser]"

Select OK.
Run the procedure using the Last Run option to reuse the parameter values previously entered.
Navigate to the job details and select Parameters. Note that the Output Parameter value whoRanMe is set as expected.

Create a step condition

Navigate to the procedure editor using the breadcrumb.
Open the first step, Hello World, and select the Condition tab on the upper right.
Add the following Run Condition (not Precondition) expression so that the step runs only after the procedure has been run five times:

$[/javascript myProcedure.count > 5]

Select OK.
Run the procedure. Use the Last Run option.
Select Rerun a few more times.

Note that the Hello World step runs after the count property exceeds five. Here is an example of the results after eight runs.