Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 15 Current »

Work Items can be customized from the Administration page to better fit your business needs. Navigate to the main work item screen and find the Administration section in the table header. Work item types, statuses, and fields will be configurable there.

Work Item Types

Work item type is a container for the work item. You can use types to group your work items together in a way that makes sense for your team or company. By default, FlexDeploy will come with “Feature”, “Bug”, “Debt”, and “Risk” types out of the box. You can choose to use to keep using those types or scrap them and create your own.

For example:

  • A single small unit of work from the users perspective is typically called a “Story” work item - This is not a default Type and therefore would need to be created by the FlexDeploy user if desired.

  • A defect in a code base is typically called a “Bug” work item

  • A collection of “Stories” is typically called a “Feature” work item

  • A collection of “Features” which requires a larger group effort is typically called a “Epic” work item - This is not a default Type and therefore would need to be created by the FlexDeploy user if desired.

Work Item Status

The work item status indicates its current place in the project’s development cycle. Users can click and select an option from the dropdown to change the status of the work item. You can also configure FlexDeploy to change the status automatically on a build or deployment execution.

A work item status is essentially a label with name and description.

Work Item Fields

Work Item custom fields are used for additional information on work item. Field definitions are organized in groups. Work item page will display these custom fields in individual group tab, where user can enter values for fields. Field values can also setup using various scripting mechanisms on pipeline and webhook functions. The “Details” work item field group is created by default. To create a custom field:

  1. Select a Work Item Field Group first.

    1. You can create new work item field group by using Create new Work Item Field Group option from drop down.

    2. Field group tab will display after the “Commits” section when viewing a work item.

  2. Click Create to add a new field.

  3. Customize the field with various parameters and/or groovy script code. This is the definition of the field, while the value is set on the work item.

  4. Select one or more Work Item Types. Field will only be associated with work item of specific type based on this selection.

  5. Once you enter field definition details, click Save (or use CTRL + S shortcut).

Edit Field Definition

Work item fields containing the following properties:

Property Name

Required

Description

Code

Yes

Work item field code. Uniquely identifies the field.

Display Name

No

Work item display name.

Description

No

Work item description.

Work Item Types

Yes

The work item types this field will apply to. In other words, if a field is assigned the “Feature” Work Item Type, then all Work Items of type “Feature” will display that field. One or more Work Item Types can be set.

Field Group

Yes

Work item field group. The group which contains the current field. The field group name will appear as a section on the work item.

Field Data Type

Yes

Work item field data type sets the visual format of the field on UI along with simple validation. For more complex validation see “Validation Script”.

The following data types are supported: Script data type is provided in parentheses.

  • Text Field (String)

  • Text Area (String)

  • Number (Long) - UI validation will only allow integers / whole numbers

  • Decimal (Double) - UI validation will allow both integers and floating point numbers

  • Checkbox (Boolean) - True / False boolean field

  • Duration (Long) - Duration is the measure of time. Ui validation will only allow unit of measure formats. I.E. +2d or -3w

  • Date (Date) - UI validation expects mm/dd/yyyy format

  • DateTime (TimeStamp) - UI validation expects mm/dd/yyyy hh:mm am/pm. The date time is selectable from a calendar for ease of use.

  • URL (String) - UI validation expects a valid URL

  • JBDCURL (String) - UI validation expects a valid JDBC URL. See packageDeploy (JDBC) for examples of valid JBDC url.

  • Directory (String)

  • User Select (Username or User Id) (String or Long) - UI provides a selection from FlexDeploy users. Value passed to the work item can be username or user id.

  • Group Select (Group name or Group ID) (String or Long) - UI provides a selection from FlexDeploy groups. Value passed to the work item can be name or id.

Example of how each input would display on the work item

Definition Script

No

Definition script is a groovy script that is used to initialize or update value for the field. Additionally, you can set or override basic validations like required, disabled, hidden, maxValue, minValue, maxLength etc. For example, if field is required only based on certain value of other field then you can achieve that by using definition script. You can also make field disabled based on current user’s roles using definition script.

Note that there is no return data from this script, but you will set field.value or field.state.

When you change field value, definition script is executed for all other fields, which allows you to reset value for other fields if necessary. Keep in mind that field.value setting will adjust value of the field on new work item as well as when work item is being updated. If you do not want to adjust the value once it is set then it must be accounted for in definition script, see empty check in example below.

Example definition script to set default value for the property based on work item type:

// empty check - in this example we will not set field value once it has been initialized
if (field.value == '' || field.value == null) 
{
   if (form.type.equalsIgnoreCase("Emergency")) 
   {
      field.value = "Priority 1"
   }
   else  if (form.type.equalsIgnoreCase("Expedite")) 
   {
      field.value = "Priority 2"
   }
   else  if (form.type.equalsIgnoreCase("Normal")) 
   {
      field.value = "Priority 3"
   } 
   else 
   {
      field.value = "Priority 4"
   }
}

Definition script evaluates for all fields when value is changed for any field. You can set field.value in Definition script to adjust the value.

Example definition script to hide field based on another field. Note that field.state in only available in Definition script.

// Hide Field based on other field value
if (form.OTHER_FIELD_CODE.equals("SOME_VALUE")) 
{
  field.state.hidden = true
}

List Data Script

No

Work item list data script. This is a groovy script which defines a set of options the user can choose from for this field value. List Data Script will only apply to String based fields i.e. TextField and not DateTime.

You can return list data in 3 different ways (see below):

// An array of values
return ["PROD", "NON-PROD"]

// A comma separated string
return "Break Fix,Enhancement,Problem,Project,request,Risk remediation"

// An array of ListValueDataObject
// Use the constructor or setters on the ListValueDataObject objects to set appropriate values
return [new ListValueDataObject("value1"),  new ListValueDataObject("label2", "value2"), new ListValueDataObject("label3", "value3", "Description")]


////////////////////////////////////////////////////////////////////////////////////
// ListValueDataObject has the following variables
  public ListValueDataObject(String pLabel, String pValue, String pDescription)
  public ListValueDataObject(String pLabel, String pValue)
  public ListValueDataObject(String pValue)

Validation Script

No

Work item validation script. This groovy script allows for more complex validations beyond simple UI validations like required or min/max value etc.

Return false to indicate validation failure. In addition set ValidationMessage variable with custom error message which will be displayed for user.

Example Date based Validation script:

// Validation script must return or true or false
// ValidationMessage is a variable specific to this script which will be display on the UI if this script returns false
if (form.PLANNEDSTART != null && form.PLANNEDEND != null) 
{   
  if (form.PLANNEDEND.before(form.PLANNEDSTART)) 
  {
    ValidationMessage = "Planned end date is not before start date."
    return false
  }
}
return true

When field value is changed,

  • this script is executed for the field being updated, and if it returns false then value change is not allowed.

  • validation script is executed for all other fields as well, field value change will still be allowed if any validation failure occurs for other fields, and screen will show updated error messages.

When work item status is changed,

  • This script is executed is execution for all fields and if any script returns false then status update will not be allowed.

Field Script Objects and Variables

Definition, List Data, and Validation Script have access to the following variables and methods which can used to retrieve values of other fields, set the value of the current field, and other functions to achieve your business requirement.

Variables

Description

form

Allows access to form details displayed on work item page. For example, field values and work item details like title, description, status, type, assignee and tags.

see details below in form section

field

Represents current field value and allows for override of required, hidden, disabled, maxValue, minValue and maxLength.

see details below in field section

currentUser

Returns CurrentUser object with methods - getUserId(), getUserName(), getFirstName(), getLastName(), getEmail() and getRoles()

FLEXDEPLOY

Provides various methods to retrieve data from FlexDeploy.

EMAIL

Functions for formatting and sending emails.

REST

Object exposing REST functions. For more info see Using the REST object. You can use this to invoke external systems for gathering details and/or validations.

TOPOLOGY

Allows access to Integration Accounts (such as Source Control, Change Management, Cloud, or other tools) properties. You can use this in conjunction with REST function to invoke external systems APIs.

Variables for the form object (note that form data can not be changed from scripts)

Variables

Type

Description

form.title

java.lang.String

Returns the value of the Title for the work item.

form.description

java.lang.String

Returns the value of the Description for the work item.

form.changeField

java.lang.String

Code for changed field, available when one field value is changed.

form.status

java.lang.String

Returns the value of the Status name for the work item.

form.type

java.lang.String

Returns the value of the Type code for the work item.

form.tags

java.util.List

Returns the value of the Tags for the work item.

form.<keycode>

depends on field data type

String, Long, Double, Boolean, Date, Timestamp

<keycode> represent code of specific field. All field values of work item can be referenced this way.

form.assignee

java.lang.String

Returns the username for Assignee for the work item.

Updating of state and value of field is allowed from Definition script.

Variables

Type

Description

field.name

java.lang.String

Returns the current field name.

field.datatype

java.lang.String

Returns the current field data type.

field.value

depends on field data type

String, Long, Double, Boolean, Date, Timestamp

Update the current field value by assigning new value as necessary. Obviously field.value represent current value of the field as well. 

if (field.value == '' || field.value == null) 
{
   if (form.type.equalsIgnoreCase("Emergency")) 
   {
      field.value = "Priority 1"
   }
   else 
   {
     field.value = "Priority 2"
   }
 }

field.state.required

java.lang.Boolean

Overrides the current field required property. True or False.

if (form.DOWN_TIME_REQUIRED!= null &&  form.DOWN_TIME_REQUIRED== true) 
{
    field.state.required= true;
}

field.state.disabled

java.lang.Boolean

Overrides the current field disabled property. True or False.

if (field.value != '' && field.value != null) 
{
    field.state.disabled= true;
}

field.state.hidden

java.lang.Boolean

Overrides the current field hidden property. True or False.

// Hide field based on other field value.
if (form.VENDOR_NOT_FOUND != null &&  form.VENDOR_NOT_FOUND == false) 
{
      field.state.hidden = true      
}

field.state.maxValue

java.lang.Long

Overrides the current field maxValue property.

  field.state.maxValue = 10000

field.state.minValue

java.lang.Long

Overrides the current field minValue property.

  field.state.minValue= 100

field.state.maxLength

java.lang.Long

Overrides the current field maxLength property. 

  field.state.maxLength= 255

  • No labels