In this page

Working with smart values

Smart values are variables that you can use in automation action configuration parameters. They are using the curly-brace syntax like {{someSmartValue}}. They are variables in the sense that their actual values will be calculated while the automation rule is being executed:

DevOps Automation for Jira commands to be used in commit message

You can use two types of smart values:

  1. The Automation for Jira app comes with a large selection of built-in smart values.
  2. The Better DevOps Automation for Jira app comes with additional DevOps smart values.

It is important to understand that you can freely combine these: you can use any type in any action, even mixing the two types in the same action.

Smart value reference

Issues

Most automation rules work with one or more issues as "subject". Those are stored in the smart value called issues. In this sense, this is probably the most important smart value.

DevOps triggers also populate this smart value with the issues linked to the changeset, commit, branch or tag. Issues can be linked to these by:

  • Including the issue key in the commit message (e.g. "FOO-1 Bug fixed.").
  • Including the issue key in the branch name (e.g. "feature/FOO-2-our-killer-feature").
  • Including the issue key in the tag name (e.g. "FOO-3-release").

The order of the issues is the chronological order as they were included in the commit messages, branch and tag names. If they are included multiple times, the earliest occurrence matters.

Expressions:

Smart value Description
{{issues}} List of the linked issues.
{{issues.size}} Number of the linked issues.
{{#issues}}{{key}}{{/}} Key of the linked issue.
{{#issues}}{{summary}}{{/}} Summary of the linked issue.
{{#issues}}{{url}}{{/}} URL of the linked issue.

DevOps smart value reference

This table is the reference of the smart values provided by the DevOps triggers in addition to the built-in smart values.

Note that not every trigger supports every smart value. For the list of supported smart values per trigger, see the trigger's documentation.

Expressions:

Smart value Description
{{devops.actor}} The user manually configured to be the rule actor. An ApplicationUser instance.

Note that the actor may not be the best option to automate activities for which the precise identity of the committer is important.

Alternatives:
{{devops.actor.key}} User key (unique identifier in Jira).
{{devops.actor.name}} User name.
{{devops.actor.displayName}} Display name.
{{devops.actor.emailAddress}} Email address.
{{devops.initiator}} The user whose activity (push, merge, etc.) initiated the automation rule execution. An ApplicationUser instance.

Its value depends on the VCS:
  • Git and Mercurial: the user who pushed the changeset. (More precisely, the user configured for the hook script in the jcp_config.py file.)
  • Bitbucket:
    • Hook: the user who pushed the changeset.
    • Merge Check: the user who merged the pull request.
  • Subversion: the user who installed the hook script to the central repository. (More precisely, the user configured for the hook script in the jcp_config.py file).

The initiator is associated with a complete changeset. For a single commit, see these alternatives:
{{devops.initiator.key}} User key (unique identifier in Jira).
{{devops.initiator.name}} User name.
{{devops.initiator.displayName}} Display name.
{{devops.initiator.emailAddress}} Email address.
{{devops.changeset}} Details of the changeset.
{{devops.changeset.repositoryId}} Identifier of the repository. How to find out?
{{devops.changeset.vcs}} Code of the Version Control System:
  • "git": Git (incl. Bitbucket)
  • "svn": Subversion
  • "hg": Mercurial
{{devops.changeset.branches}} List of the changed branches (in undefined order). Contains the newly created and deleted branches.
{{#devops.changeset.branches}}{{name}}{{/}} Name of the branch.
{{#devops.changeset.branches}}{{action.code}}{{/}} Action code of the branch operation:
  • "a": added
  • "d": deleted
{{#devops.changeset.branches}}{{action.color}}{{/}} Color code of the branch operation:
  • "#36B37E": added
  • "#FF5630": deleted
{{#devops.changeset.branches}}{{action.label}}{{/}} Short name of the branch operation:
  • "ADD": added
  • "DEL": deleted
{{devops.changeset.tags}} List of the changed tags (in undefined order). Contains the newly created and deleted tags.
{{#devops.changeset.tags}}{{name}}{{/}} Name of the tag.
{{#devops.changeset.tags}}{{action.code}}{{/}} Action code of the tag operation:
  • "a": added
  • "d": deleted
{{#devops.changeset.tags}}{{action.color}}{{/}} Color code of the tag operation:
  • "#36B37E": added
  • "#FF5630": deleted
{{#devops.changeset.tags}}{{action.label}}{{/}} Short name of the tag operation:
  • "ADD": added
  • "DEL": deleted
{{devops.changeset.commits}} List of the commits (in historical order, i.e. oldest first).
{{devops.changeset.commits.size}} Number of the commits.
{{devops.changeset.commits.id}} Comma-separated list of the commit IDs (implicit iteration). Note that similarly to id, you can access all commit properties through this collection.
{{#devops.changeset.commits}}{{id}}{{/}} List of the commit IDs (explicit iteration). Note that similarly to id, you can access all commit properties through this collection.
{{devops.branch}} Name of the new branch (provided by the Branch Created trigger).
{{devops.tag}} Name of the new tag (provided by the Tag Created trigger).
{{devops.command}} The command to execute (e.g. "comment" without the leading "@").
{{devops.commit}} Commit details.
{{devops.commit.id}} Unique identifier of the commit.
{{devops.commit.branch}} The name of the branch that the commit was added to.
{{devops.commit.repositoryId}} Identifier of the enclosing repository.
{{devops.commit.vcs}} Code of the Version Control System.
{{devops.commit.isMerge}} Whether the commit is a merge commit.
{{devops.commit.isExisting}} Whether the commit already exists (e.g. on another branch) in the repository that receives this commit.

For the Commit Created and Genius Commit Created triggers, this is false for every commit.
{{devops.commit.author}} Commit author in the username plus email address format (e.g. "alice <alice.white@acme.com>").

You can use the extracted fields of this smart value using {{devops.commit.username}} and {{devops.commit.emailAddress}}.

Alternatives:
{{devops.commit.username}} Username of the committer extracted from {{devops.commit.author}}.
{{devops.commit.emailAddress}} Email address of the committer extracted from {{devops.commit.author}}.
{{devops.commit.committerByUsername}} The user who created the commit. An ApplicationUser instance.

More precisely, it is the Jira user identified by the commit author's username (or null in case of a failed identification). Use this when the Jira user accounts' usernames match the VCS usernames!

Short-hand:
Alternative:
{{devops.commit.committerByUsername.key}} User key (unique identifier in Jira).
{{devops.commit.committerByUsername.name}} User name.
{{devops.commit.committerByUsername.displayName}} Display name.
{{devops.commit.committerByUsername.emailAddress}} Email address.
{{devops.commit.committerByEmailAddress}} The user who created the commit. An ApplicationUser instance.

More precisely, it is the Jira user identified by the commit author's email address (or null in case of a failed identification). Use this when the Jira user accounts' email addresses match the VCS email addresses!

Short-hand:
Alternative:
{{devops.commit.committerByEmailAddress.key}} User key (unique identifier in Jira).
{{devops.commit.committerByEmailAddress.name}} User name.
{{devops.commit.committerByEmailAddress.displayName}} Display name.
{{devops.commit.committerByEmailAddress.emailAddress}} Email address.
{{devops.commit.message}} Commit message.
{{devops.commit.files}} List of the files that were added/modified/deleted (in undefined order).
{{devops.commit.files.size}} Number of the files.
{{#devops.commit.files}}{{path}}{{/}} Full path (including the file name) of the file.
{{#devops.commit.files}}{{action.code}}{{/}} Action code of the file operation:
  • "a": added
  • "d": deleted
  • "m": modified
{{#devops.changeset.files}}{{action.color}}{{/}} Color code of the file operation:
  • "#36B37E": added
  • "#FFAB00": modified
  • "#FF5630": deleted
{{#devops.changeset.files}}{{action.label}}{{/}} Short name of the file operation:
  • "ADD": added
  • "MOD": modified
  • "DEL": deleted
{{devops.committerByUsername}} A shorthand for the slightly longer {{devops.commit.committerByUsername}}.
{{devops.committerByUsername.key}} User key (unique identifier in Jira).
{{devops.committerByUsername.name}} User name.
{{devops.committerByUsername.displayName}} Display name.
{{devops.committerByUsername.emailAddress}} Email address.
{{devops.committerByEmailAddress}} A shorthand for the slightly longer {{devops.commit.committerByEmailAddress}}.
{{devops.committerByEmailAddress.key}} User key (unique identifier in Jira).
{{devops.committerByEmailAddress.name}} User name.
{{devops.committerByEmailAddress.displayName}} Display name.
{{devops.committerByEmailAddress.emailAddress}} Email address.
{{devops.rejectionMessage}} Rejection message with the reason(s) why the changeset has been rejected by the commit policy.

Helpers

ChangesetHelper

It helps accessing changeset details in smart value expressions.

Expression
{{changesetHelper.matchRepository(devops.changeset, ".*foo.git")}} or {{changesetHelper.matchRepository(devops.commit, ".*foo.git")}}
Returns the repository ID which matches the passed regular expression. Although it is written in multi-value form to be consistent with other helpers, it can return only that single repository ID in which the changeset or commit was created.
(E.g. it returns the repository ID if that ends with "foo.git".)
{{changesetHelper.matchBranches(devops.changeset, "feature\/.*")}}
Returns the branch names which match the passed regular expression and commits were created on.
(E.g. it returns the branch names which start with "feature/".)
{{changesetHelper.matchCommitters(devops.changeset, "ext-.*")}}
Returns the committer names which match the passed regular expression.
(E.g. it returns the committer names which start with "ext-".)
{{changesetHelper.matchPaths(devops.changeset, "src\/.*")}}
Returns the file paths which match the passed regular expression.
(E.g. it returns the file paths which start with "src/".)
{{changesetHelper.matchPaths(devops.changeset, "src\/.*", "a")}}
Returns the file paths which match the passed regular expression and match the passed operation code.
(E.g. it returns the file paths which start with "src/" and were added in this changeset.)
{{changesetHelper.matchChangedBranches(devops.changeset, "feature\/.*")}}
Returns the branch names which match the passed regular expression and were added or removed in this changeset.
(E.g. it returns the branch names which start with "feature/".)
{{changesetHelper.matchChangedBranches(devops.changeset, "feature\/.*", "a")}}
Returns the branch names which match passed regular expression and match the passed operation code.
(E.g. it returns the branch names which start with "feature/" and were added in this changeset.)
{{changesetHelper.matchChangedTags(devops.changeset, "version-.*")}}
Returns the tag names which match the passed regular expression and were added or removed in this changeset.
(E.g. it returns the tag names which start with "version-".)
{{changesetHelper.matchChangedTags(devops.changeset, "version-.*", "a")}}
Returns the tag names which which match the passed regular expression match the passed operation code.
(E.g. it returns the tag names which start with "version-" and were added in this changeset.)
{{changesetHelper.getCommitsByIssue(devops.changeset.commits, issue.key)}}
Returns the commits which are linked to the passed issue.
{{changesetHelper.getCommitsWithoutIssues(devops.changeset.commits, issues)}}
Returns the commits which are not linked to the passed issues.
(E.g. it returns the commits which are not linked to any issue mentioned in the changeset.)

JiraHelper

It helps working users, statuses and other Jira entities in smart value expressions.

Expression
{{jiraHelper.getIssueTypeByName("Bug")}}
Returns the IssueType instance for the passed issue type name (case-insensitive).
{{jiraHelper.getPriorityByName("High")}}
Returns the Priority instance for the passed priority name (case-insensitive).
{{jiraHelper.getResolutionByName("Fixed")}}
Returns the Resolution instance for the passed resolution name (case-insensitive).
{{jiraHelper.getStatusByName("Done")}}
Returns the Status instance for the passed status name (case-insensitive).
{{jiraHelper.getTransitionByName(issue.key, "Start progress")}}
Returns the TransitionEntry instance for the passed issue and transition name (case-insensitive).
(The issue determines the workflow in which the transition is looked for.)
{{jiraHelper.getTransitionByTargetStatus(issue.key, "Done")}}
Returns the TransitionEntry instance for the passed issue and target status name (case-insensitive).
(The issue determines the workflow in which the transition is looked for.)
{{jiraHelper.getUserByName("alice")}}
Returns the ApplicationUser instance for the passed username (case-insensitive).
{{jiraHelper.getVersionByName(issue.projectId, "1.2-beta")}}
Returns the Version instance for the passed project id and version name (case-insensitive).
(The project id determines the available versions in which the passed version name is looked for.)

StringHelper

It helps working with scripts in smart value expressions.

Expression
{{stringHelper.getOrDefault(devops.comment, "(No comment entered.)")}}
Returns the first parameter if it's not an empty string, otherwise the second parameter.
{{stringHelper.trimToNull(devops.resolution)}}
Returns the trimmed string or null if empty.

ClassHelper

It helps working with classes when debugging smart value expressions. Note that provides more functionality for loading classes in Groovy scripts.

Expression
{{classHelper.getClassName(issues.first)}}
Returns the class name of the passed object.
(E.g. it returns "com.codebarrel.automation.rulecomponent.jira.common.smartbeans.SmartIssueBean" for issues.first.)

Questions?

Ask us any time.