Creating a plugin

To create a plugin, you set up the plugin configuration and then add procedures and properties.

Setting Up the plugin configuration

From the main menu, select menu:DevOps Essentials[Platform Home page>Administration>Plugins. The Plugin Manager appears.
Select Create Plugin. The New Plugin page appears.

Complete the page as follows:

Field name Description

Field name	Description
Name	Plugin name. Enter a unique name.
Version	Plugin version. The default is `1.0.0.0`.
Description	(Optional) Plain text description of the plugin. CloudBees CD/RO does not interpret this text.
Category	(Optional) Category for the plugin. Categories let you group plugins by functionality or purpose and provide a convenient way to look up a specific plugin if you know its functionality or purpose. For example, when you are configuring a process step and want to deploy an application on WebSphere, you first choose the Application Server category and then the WebSphere plugin. You can select an existing plugin category by using the autofill functionality or enter a new category. The default category is `Utility`.
Author	(Optional) Plugin author’s name. For example, a user or organization name. The default is the current user name, such as `System Administrator`.
Author Url	(Optional) Plugin author’s URL. For example, `https://example.com/integrations/docker`.
Enable plugin configuration support	(Optional) Determines whether to allow the addition of plugin procedures to support the creation of plugin configurations. Disabling this option displays a confirmation dialog box if the plugin already exists: `Any existing plugin configurations for this plugin will be deleted if the 'Enable plugin configuration support' is unchecked`. If you enable this feature, the Configuration Setup tab is added to the Project Details page for the plugin, and the CreateConfiguration and DeleteConfiguration procedures are added to the plugin. This tab lets you modify information required to support plugin configurations such as the parameters required by the CreateConfiguration procedure. This option is enabled by default.

Name

Plugin name. Enter a unique name.

Version

Plugin version. The default is 1.0.0.0.

Description

(Optional) Plain text description of the plugin. CloudBees CD/RO does not interpret this text.

Category

(Optional) Category for the plugin. Categories let you group plugins by functionality or purpose and provide a convenient way to look up a specific plugin if you know its functionality or purpose. For example, when you are configuring a process step and want to deploy an application on WebSphere, you first choose the Application Server category and then the WebSphere plugin.

You can select an existing plugin category by using the autofill functionality or enter a new category. The default category is Utility.

Author

(Optional) Plugin author’s name. For example, a user or organization name. The default is the current user name, such as System Administrator.

Author Url

(Optional) Plugin author’s URL. For example, https://example.com/integrations/docker.

Enable plugin configuration support

(Optional) Determines whether to allow the addition of plugin procedures to support the creation of plugin configurations. Disabling this option displays a confirmation dialog box if the plugin already exists: Any existing plugin configurations for this plugin will be deleted if the 'Enable plugin configuration support' is unchecked.

If you enable this feature, the Configuration Setup tab is added to the Project Details page for the plugin, and the CreateConfiguration and DeleteConfiguration procedures are added to the plugin. This tab lets you modify information required to support plugin configurations such as the parameters required by the CreateConfiguration procedure.

This option is enabled by default.

Select OK.

If you selected Enable plugin configuration support in the New Plugin page above, the Configuration Setup tab in the Project Details page appears. (A plugin is a type of project.)

In the Configuration Setup tab, the plugin configuration parameters appear under the Configuration Parameters section. The CreateConfiguration procedure uses these parameters when creating the plugin configuration. By default, the following configurations parameters are added to a new plugin:
- config: used to provide a unique name for the configuration
- desc: description of the plugin configuration
- credential: user name and password used to communicate with the third-party system with which the plugin is integrated
In the Configuration Setup tab, select Create Parameter to add configuration parameters that your plugin requires. The New Parameter page appears.

Complete the page as follows:

Field name	Description
Name	Name of the parameter for which values are requested when the CreateConfiguration procedure is invoked. Enter a unique name.
Description	(Optional) Plain text description of the parameter. CloudBees CD/RO does not interpret this text.
Type	The type of the parameter selected from the dropdown list.
Default Value	Default value of the parameter if no value is provided when the procedure is invoked.
Required?	Determines whether a value for the parameter is required. If this is enabled, the CreateConfiguration procedure ignores the default value and does not run unless a value is provided. After the procedure begins execution, the parameter value is available in the job property sheet with the same name as the parameter. The check box is unchecked by default.
Defer Expansion?	When the step executes (the check box is checked). The check box is unchecked by default (meaning that expansion is not deferred).

Field name

Description

Name

Name of the parameter for which values are requested when the CreateConfiguration procedure is invoked. Enter a unique name.

Description

(Optional) Plain text description of the parameter. CloudBees CD/RO does not interpret this text.

Type

The type of the parameter selected from the dropdown list.

Default Value

Default value of the parameter if no value is provided when the procedure is invoked.

Required?

Determines whether a value for the parameter is required. If this is enabled, the CreateConfiguration procedure ignores the default value and does not run unless a value is provided. After the procedure begins execution, the parameter value is available in the job property sheet with the same name as the parameter.

The check box is unchecked by default.

Defer Expansion?

When the step executes (the check box is checked). The check box is unchecked by default (meaning that expansion is not deferred).

The configuration parameters that you specified are added as parameters to the Create Configuration procedure in the Procedures tab for the plugin.

From the Type pull-down menu, choose a form element type and complete the page for that type as follows:

Type Description

Type	Description
Text entry	Creates a field for users to enter a small amount of text.
Text area	Creates a field that expands for users to enter a large amount of text (such as a script).
Dropdown menu	Creates a drop-down menu for users to select a value when the parameter is presented. Choose one of the following: Enter options —Select + Add Option to add one or more new rows. Then enter the text and value for each option. The text is what will appear in the menu, and the value is the parameter value if that option is selected. Load options from list —Enter a pipe-separated list of options (for example, `foo\|bar\|baz` ). The text and value for the options will be the same. Load options from property sheet —Enter the path to the property sheet that contains options for the parameter. The property sheet must be created in a specific format: An `optionCount` property must exist whose value is the number of options. For each option, create a nested property sheet named `option` N , where N is the option number, starting with `1`. For example, if `optionCount` is set to `3`, you must create three nested sheets: `option1`, `option2`, and `option3`. In each nested sheet, create two properties: `text` and `value`. The value of the `text` property will appear in the menu. The value of the `value` property is the parameter value if that option is selected.
Radio selector	Creates radio buttons for users to select a value when the parameter is presented. Enter options —Select + Add Option to add one or more new rows. Then enter the text and value for each option. The text is what will appear in the menu, and the value is the parameter value if that option is selected. Load options from list —Enter a pipe-separated list of options (for example, `foo\|bar\|baz` ). The text and value for the options will be the same. Load options from property sheet —Enter the path to the property sheet that contains options for the parameter. The property sheet must be created in a specific format: An `optionCount` property must exist whose value is the number of options. For each option, create a nested property sheet named `option` N , where N is the option number, starting with `1`. For example, if `optionCount` is set to `3`, you must create three nested sheets: `option1`, `option2`, and `option3`. In each nested sheet, create two properties: `text` and `value`. The value of the `text` property will appear in the menu. The value of the `value` property is the parameter value if that option is selected.
Checkbox	Creates a check box for users to select or deselect a value when the parameter is presented. Value when unchecked —Value of the parameter when the check box is unchecked ( `false` by default) Value when checked —Value of the check box when the check box is checked ( `true` by default) Initially checked? - Whether the check box should be checked initially. If `true`, set Default value to match Value when checked. If `false` (the default) set Default value to match Value when unchecked.
Credential	Creates a text box and an input field for users to provide a user name and password respectively to use this parameter at runtime.

Text entry

Creates a field for users to enter a small amount of text.

Text area

Creates a field that expands for users to enter a large amount of text (such as a script).

Dropdown menu

Creates a drop-down menu for users to select a value when the parameter is presented. Choose one of the following:

Enter options —Select + Add Option to add one or more new rows. Then enter the text and value for each option. The text is what will appear in the menu, and the value is the parameter value if that option is selected.
Load options from list —Enter a pipe-separated list of options (for example, foo|bar|baz ). The text and value for the options will be the same.
Load options from property sheet —Enter the path to the property sheet that contains options for the parameter. The property sheet must be created in a specific format:
An optionCount property must exist whose value is the number of options.
For each option, create a nested property sheet named option N , where N is the option number, starting with 1. For example, if optionCount is set to 3, you must create three nested sheets: option1, option2, and option3.
In each nested sheet, create two properties: text and value. The value of the text property will appear in the menu. The value of the value property is the parameter value if that option is selected.

Radio selector

Creates radio buttons for users to select a value when the parameter is presented.

Enter options —Select + Add Option to add one or more new rows. Then enter the text and value for each option. The text is what will appear in the menu, and the value is the parameter value if that option is selected.
Load options from list —Enter a pipe-separated list of options (for example, foo|bar|baz ). The text and value for the options will be the same.
Load options from property sheet —Enter the path to the property sheet that contains options for the parameter. The property sheet must be created in a specific format:
An optionCount property must exist whose value is the number of options.
For each option, create a nested property sheet named option N , where N is the option number, starting with 1. For example, if optionCount is set to 3, you must create three nested sheets: option1, option2, and option3.
In each nested sheet, create two properties: text and value. The value of the text property will appear in the menu. The value of the value property is the parameter value if that option is selected.

Checkbox

Creates a check box for users to select or deselect a value when the parameter is presented.

Value when unchecked —Value of the parameter when the check box is unchecked ( false by default)
Value when checked —Value of the check box when the check box is checked ( true by default)
Initially checked? - Whether the check box should be checked initially. If true, set Default value to match Value when checked. If false (the default) set Default value to match Value when unchecked.

Credential

Creates a text box and an input field for users to provide a user name and password respectively to use this parameter at runtime.

Select OK.

The new parameter appears in the Project Details page under the Configuration Parameters list.
Repeat the previous three steps to create more parameters as needed.

The new plugin appears on the Plugin Manager page under the Currently Installed tab along with the other installed plugins.

Adding Procedures

A procedure defines a process to automate one or more steps. A procedure is run to carry out a process.

In the Plugin Manager page, select the plugin name. The Project Details page for the plugin appears.
Select the Procedures tab and then select Create Procedure. The New Procedure page appears.
Complete the page as follows:

Field name Description

Name

Procedure name. This name must be unique within the project.

Description

(Optional) Plain text description of the procedure. CloudBees CD/RO does not interpret this text.

Job Name Template

Template used to determine the default name of a job launched from the procedure. For example:

$[projectName]_$[/increment /myproject/jobCounter]_$[/timestamp]▼

produces a name such as:

projectFoo_1234_20140102130321▼

Enter any combination of elements to create meaningful procedure names. For example, you could include the build number.

You should not use the CloudBees CD/RO-generated jobId, because it is not a human-readable integer. This means that it does not provide identifiable information and cannot be used as a counter.

Default Resource

Resource name. Enter a name or click Browse and choose a resource. This name must be unique among resource names.

Default Workspace

Name of the default workspace. Enter a name or click Browse and choose a workspace.

Time Limit

Maximum amount of time during which the step can execute. The step is aborted if it exceeds this time. If no time limit was specified on the calling step, time limits are copied to the calling step from the procedure. If the procedure is called from runProcedure (or a schedule), the time limit acts as a global job timeout.

The timer for the procedure starts when the calling step or job becomes runnable (when all preconditions are satisfied). Specify a number and then use the pull-down menu to select the units (seconds, minutes, or hours).

Impersonation Credential

Credential Project

Name of the project that contains this credential. Use the current project or click the other radio button and enter a project name (or click Browse and choose another project). The current project is used by default.

Credential Name

Name of the credential for the project. Enter a name or click Browse and choose another credential.

Select OK.
Repeat the above steps to add more procedures if needed.

Adding Properties

In the Project Details page for the plugin, select the Properties tab. The list of properties for the plugin appears.
Select Create Property. The New Property popup appears.
Complete the popup as follows:

Column Name Description / Actions

Column Name	Description / Actions
Name	Property name.
Value	Value to assign to the property.
Description	(Optional) Plain text description of this object. CloudBees CD/RO does not interpret this text.
Expandable	Determines whether the property is marked for expansion. Enabled (checked) means that a property value such as `$[MYPROPERTY]` will be expanded or resolved to be the actual value of `$[MYPROPERTY]`. Disabled (unchecked) means that the value of the property is interpreted literally as `$[MYPROPERTY]`.

Name

Property name.

Value

Value to assign to the property.

Description

(Optional) Plain text description of this object. CloudBees CD/RO does not interpret this text.

Expandable

Determines whether the property is marked for expansion. Enabled (checked) means that a property value such as $[MYPROPERTY] will be expanded or resolved to be the actual value of $[MYPROPERTY]. Disabled (unchecked) means that the value of the property is interpreted literally as $[MYPROPERTY].

Select OK.
Repeat the above steps to add more properties if needed.