Workflow Properties
- Karl Henselin
- Blake Westmoreland
Workflow Properties provide the ability to add custom properties for a workflow
The Workflow Properties section provides the ability to add custom properties for a workflow. Plugins generally provide most of the properties, but it is useful to have custom properties specifically when using plugins like Shell, Groovy, Jython, etc. These properties will then be available for setting values on either the referencing project or target (depending on the selected scope). For example, if you need to define a reusable workflow that deploys files to a specific folder depending on what project is being deployed, in that case, you can add a property to define DEPLOY_FOLDER at the Project scope.
Creating Custom Properties
Navigate to the Properties tab of the Workflow. By default, you will see an empty screen unless properties have been added previously. To create a new property click the Create button.
This will insert a new row where you can specify the fields for the property. Additionally, you can right-click (or use the actions menu at the end of the row) and select Edit to show a popup with more available fields.
Workflow Property Fields
A detailed listing of all available fields is described below:
Field | Description | Required |
|---|---|---|
Code | The code field must be globally unique across all properties in FlexDeploy. Only uppercase letters, numbers, and underscores are allowed. Best Practice All native FlexDeploy properties are prefixed with FD_. It is best practice not to prefix your custom properties with FD_. All custom properties are available in the workflow via this code field. | Yes |
Display Name | The Display Name is a more user-friendly name for the property that is shown in the UI. It has looser restrictions compared to the Code field. | No |
Description | The description will show as an input hint next to the property in the UI. | No |
Field Data Type | The Field Data Type decides how your custom property should be displayed in the UI and how the data should be made available to your Workflow. A few examples:
| Yes |
Scope | The Scope field defines where the property value is specified, options are:
| Yes |
Required | Should a value for your custom property be required? | No |
Encrypted | Checking the Encrypted checkbox will convert your property to a credential selection. Note that a credential cannot be specified for the Default Value field, however. Encrypted property values will not display on the screen or be readable in any of the logs. | No |
Default Value | Specify a default value for this Property | No |
List Data CSV | Specify a list of options that should be made available to pick from. Depending upon the Field Type chosen, list data may not be allowed. Full examples and variants of list data can be found in the Using List Data section below. | No |
Display Rows | The number of rows that will be displayed by default in the input field. Cannot exceed 50. | No |
Max Length | The maximum length allowed for the property value is only applicable to text data types. | No |
Multi-Select | If List Data is specified, should multiple selected values be allowed? Only applicable when list data is specified or the Field Type is from the Selects category. | No |
Min Value | The minimum value (number) allowed for the input. Only applicable for number types. | No |
Max Value | The maximum value (number) allowed for the input. Only applicable for number types. | No |
Validation Script | A custom validation script will be run before saving the value. The script should return The script has two variables available:
| No |
Hide When | Conditionally hide this field should. See Using Hide When and Disable When below | No |
Disable When | Conditionally disable this field should. See Using Hide When and Disable When below | No |
Selecting Existing Properties
In addition to creating new custom properties, you can also use existing properties. Existing properties can be either native in FlexDeploy or custom properties created on another Workflow.
To add an existing property, click the Add Existing button.
Next, simply select the property you would like to add . A few caveats about adding existing properties:
If adding a native FlexDeploy property, it will be added as read-only and cannot be modified.
If adding a property that was created on another Workflow, that property will be editable but changes made will also update the other references to that property.
Using List Data
There are multiple ways to fill out the List Data CSV field when specifying a custom property. There are a few terms to iron out before we dive in:
label - The label is what text will be shown on the select option.
value - The value is what value will be saved when selecting an option. This is not visible on the screen when selecting a value.
description - The description is simply a hint that will be shown below the option label.
Take for example the Field Data Type selection above:
In this case “Text Field” is our label, “Generic text field” is our description and our value (again hidden) would be some id that correlates to the Text Field type.
With that out of the way let's talk about the various ways we can define the list data.
Plain Text
Plain text is the default for list data. It is simpler than Groovy but does not support as many use cases. Below are the variations which can be used for Plain Text
Variation | Notes |
|---|---|
john, jack, jill | When specifying a CSV in this fashion, each entry will be used for BOTH label and value. This means the selection option will show “john” and when selected we will save a value of “john”. The description is omitted in this variation. |
John##john, Jack##jack, Jill##jill | You can optionally separate entries with |
John##john##QA Analyst, Jack##jack##Software Engineer | Lastly, you can add a third segment, also separated with Note that you can mix and match entries in the CSV. For example, if Jack did not have a role within the company you can omit the description: John##john##QA Analyst, Jack##jack |
Groovy
Using Groovy to define your list data has the added benefit of being able to make HTTP calls or any other means to dynamically set the list data. As such there are infinite examples of usages but a few are shown below.
Variation | Notes |
|---|---|
return 'john, jack, jill' | The simplest example is for all intents and purposes identical to the first example in the Plain Text examples. Any variation you can do in Plain Text can be done in Groovy by just returning it as a string. |
return ['john', 'Jack##jack', 'jill'] | Perhaps more conventional in terms of Groovy scripting, you can return a list of strings to represent the options as well. |
import flexagon.fd.model2.pojo.common.ListValueDataObject;
return [
new ListValueDataObject("value1"),
new ListValueDataObject("label2","value2"),
new ListValueDataObject("label3","value3","Description")
] | You can also use the |
import flexagon.ff.common.core.rest.FlexRESTClient;
import groovy.json.JsonSlurper;
def client = new FlexRESTClient("https://swapi.dev/api/people");
client.addHeader("accept", "application/json");
def response = client.get();
def jsonObject = new JsonSlurper().parseText(
response.getResponseString()
);
// json keys can be accessed via dot notation
// for example jsonObject.items or jsonObject.result.data
// the following returns a list of text names
return jsonObject.results.collect({item -> item.name}) | This final example is making a public API call to the Star Wars API and returning a list of Star Wars character names as list options. At the end of the day, this is boiled down to something like: return ['Luke Skywalker', 'Han Solo', 'Darth Vader'] |
Using Hide When and Disable When
Hide When and Disable When are two powerful ways to help control the simplicity when specifying values for your custom properties. Each option can be broken down into 4 pieces:
Field | Description |
|---|---|
Target Field Code | This is the Code field of the target field you want to use to determine the hidden/disabled state of this property. |
Type | The type of comparison that should be used when evaluating the Target field value to determine if this input should be hidden/disabled. |
Negate | Negate the Type/Value field combination, for example, if Type was |
Values | Finally, the values of the Target Field should be used to determine if the field should be hidden/disabled. |
A full example
Let's say our Workflow has these two custom properties defined, both Project scoped:
If we open the edit popup of DOCS_MESSAGE let's set a Hide When rule to hide the field when DOCS_SHOW_MESSAGE is not checked.
Now if we navigate to the Project Properties of a Project using our Hello World Workflow we can see only our DOCS_SHOW_MESSAGE field since it is unchecked. All we need to do is check it and viola!
Related content
- style