×
Atlassian Jira Software
Atlassian Jira Software

Overview

The Atlassian Jira Software plugin supports management of Jira groups, issues, and users. Additionally, a generic node exists to expose all REST API methods.

Functionality

The Security Flow Atlassian Jira Software plugin provides the ability to call any REST API end-point through the NL-Jira-REST-API node. Additionally, the plugin provides direct access to

  • retrieve issues through a Jira Query Language (JQL) search query
  • retrieve issues using an ID or key
  • retrieve metadata to use when creating a new issue
  • retrieve metadata to use when editing an existing issue
  • create a new issue
  • edit an existing issue
  • add attachments to an issue
  • add a comment to an issue
  • add a watcher to an issue
  • find existing Jira users
  • retrieve the groups assigned to a user
  • create a new user
  • update an existing user
  • delete an existing user
  • retrieve groups by searching their names
  • add a user to a group
  • remove a user from a group

Instance Configuration Parameters

Property
Description

Instance Name

Name for the Atlassian Jira Software plugin instance.


Unique ID

A system-wide unique identifier for this plugin instance used to locate the service.


Authentication Mechanism

The authentication mechanism to use for accessing the Jira server.


Jira Connection Protocol

Jira connection protocol either http or https.


Jira Server

Host name of the Jira server. E.g., myinstance.atlassian.net.


Jira Server Port

Jira server port number. Choose between 1-65535.


Base Path

Optional path added before the rest/api/ of the URL.


Intermediate Path

Optional API path replacing the default rest/api/[API version] of the URL.


API Version

Optional API Version of the Jira REST API. Defaults to 2.


Username

Jira username. Required when the Authentication Mechanism is set to Username/Password Authentication.


Password / API Token

Password or API Token for accessing the account of the specified username. Cloud users need to see https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/ to create an API Token.

Required when the Authentication Mechanism is set to Username/Password Authentication.


Authorization (OAuth2)

Application authorization used to access Jira services. Required when the Authentication Mechanism is set to Authorization (OAuth2).

Flow Nodes

This node exposes sections of the Atlassian Jira REST API to manage users.
Property
Description

Name

The display name of the node within the flows.


Unique ID

A system-wide unique identifier for this plugin instance used to locate the service.


Action

Configuration option determining the type of operation to perform:

  • Find Groups: Finds matching groups by name.
  • Add User to Group: Adds a user to a group.
  • Remove User from Group: Removes a user from a group.

Successful results for an action are placed in msg.payload.jira.[uniqueId].response.


Group Query

The search string used to search through group names. Looks for the sub-string within existing group names.


Exclude

When set, the Exclude configuration parameter, excludes specifically named groups from the matching results. This value may be a comma separated group list string or an array of groups.


Size Limit

The maximum number of groups to return when performing the Find Groups action.


Group

The name of the group to add a user to or remove a user from.


Account ID

The account ID for the user to be added to or removed from the designated Group.

This node exposes sections of the Atlassian Jira REST API to manage issues.
Property
Description

Name

The display name of the node within the flows.


Unique ID

A system-wide unique identifier for this plugin instance used to locate the service.


Action

Configuration option determining the type of operation to perform:

  • Find Issues: Retrieve issues through a Jira Query Language (JQL) search query.
  • : Retrieves an issue using an ID or key.
  • : Retrieves metadata to use when creating a new issue.
  • : Retrieves metadata to use when editing an existing issue.
  • : Creates a new issue.
  • : Edits an existing issue.
  • : Adds attachments to an issue.
  • : Adds a comment to an issue.
  • : Adds a watcher to an issue.

Successful results for an action are placed in msg.payload.jira.[uniqueId].response.


JQL Search

Defines the JQL search query. See the Advanced Searching Using JQL page for detailed documentation on the structure of the JQL search string. The search supports using mustache variable substitution from the incoming message. Visit the Template Engine and Formatters page to learn more.


Issue ID / Key

The issue ID or issue key uniquely identifies the Jira issue. If a value of Standard Issue Key Location is selected, the key is obtained from msg.payload.jira.[uniqueId].response.issue.key.


Issue Fields

If specified, the Issue Fields defines the fields to return. If not specified, all fields are returned. If the field name is prefixed with a - (dash), the field is excluded from the results. This value may be a comma separated field name list or an array of fields.


Expand Parameters

If specified, the Expand Parameters defines the additional information to return. Learn more about expansion. Possible values are renderedFields, names,schema, transitions, operations, editmeta, changelog, and versionedRepresentations. This value may be a comma separated parameter list or an array of parameters.


Size Limit

The maximum number of issues to return when performing the Find Issues action.


Validation

Validation determines how to validate the JQL Search criteria and treat the validation results.


Create JSON Payload

The Create JSON Payload configuration parameter defines the initial settings for a new issue. See the Jira API v3 Create Issue page for detailed documentation on the structure of the JSON payload. The sample payload illustrates how to create an issue with a few values defined dynamically using mustache variable substitution from the incoming message. Visit the Template Engine and Formatters page to learn more.


Edit JSON Payload

The Edit JSON Payload configuration parameter defines the update settings to an existing issue. See the Jira API v3 Edit Issue page for detailed documentation on the structure of the JSON payload. The sample payload illustrates how to update an issue with a few values defined dynamically using mustache variable substitution from the incoming message. Visit the Template Engine and Formatters page to learn more.


Notify Users

If Notify Users evaluates to a JavaScript truthy value, a notification is sent to all watchers of the issue by the Jira Software.


Included Attachment(s)

Included Attachment(s), if supplied, is a glob or extended glob pattern. Only file names matching the glob pattern are included as an attachment. For example, *.foo will include only those attachments with an extension of “foo”. *.+(jpg|gif|png) will include the three supplied file extensions of “jpg”, “gif”, and “png”. Globbing is configured to be case insensitive.

The Included Attachment(s) setting takes precedence over the Excluded Attachment(s) setting. It is recommend to define only one setting, but not both.


Excluded Attachment(s)

Excluded Attachment(s), if supplied, is also a glob or extended glob pattern. Any file attachment name matching the glob pattern is skipped from processing. For example, *.foo will exclude any attachment with an extension of “foo”. *.+(jpg|gif|png) will exclude the three supplied file extensions of “jpg”, “gif”, and “png”. Globbing is configured to be case insensitive.


Comment

The Comment field uses variable substitution from the incoming message using a mustache format. Visit the Template Engine and Formatters page to learn more.


Watcher Id

The Watcher Id is the account ID of an existing user.

This node provides the capability to call any of the Atlassian Jira REST API end-points.
Property
Description

Name

The display name of the node within the flows.


Unique ID

A system-wide unique identifier for this plugin instance used to locate the service.


Path Segment

The Path Segment defines a mustache template for the URL’s path after the API version. The following example sets the path for setting an issue’s assignee. The path for setting an issue assignee with a str context value is /issue/{{payload.issueId}}/assignee. If the payload.issueId is PROJECT-123, the final URL is [protocol]://[hostname]:[port]/rest/api/[version]/issue/PROJECT-123/assignee, where protocol, hostname, port, and version came from the plugin instance configuration.


HTTP Method

The HTTP Method must evaluate to one of GET, POST, PUT, PATCH, or DELETE. Any other value will cause a non-recoverable failure.


Query Parameters

When needed, the Query Parameters must evaluate to a JSON object or string. The object contains the query parameters (URL parameters) as key-value pairs. Values may include any value convertible to string. Array values will result in the same key being supplied with each element as a value within the query parameters. The string must contain the URL parameters in the key1=value1&key2=value2&...&keyN=valueN format. If the Query Parameters uses the {} JSON context, mustache template substitution is applied prior to generation of the final JSON object.


Body Parameters

When needed, the Body Parameters must evaluate to a JSON object. The object contains the request payload as specified by REST API end-point. If the Body Parameters uses the {} JSON context, mustache template substitution is applied prior to generation of the final JSON object.

This node exposes sections of the Atlassian Jira REST API to manage users.
Property
Description

Name

The display name of the node within the flows.


Unique ID

A system-wide unique identifier for this plugin instance used to locate the service.


Action

Configuration option determining the type of operation to perform:

  • Find Users: Finds existing Jira users.
  • Get User Groups: Retrieves the groups assigned to a user.
  • Create User: Creates a new user.
  • Update User: Updates an existing user.
  • Delete User: Deletes an existing user.

Successful results for an action are placed in msg.payload.ipinfo.[uniqueId].response.


User Query

Performs a search of existing users’ displayName and emailAddress fields using the specified User Query. Specify an entire email address to locate an individual user.


Size Limit

The maximum number of users to return when performing the Find Users action.


Account ID

The user’s account ID uniquely identifies the user within Jira. If the Account ID is set to Standard Account ID Location, the account ID is obtained within the standard response location at user.accountId. The location is set by a successful Find Users action.


Create JSON Payload

The Create JSON Payload defines the initial user settings. See the Jira API v3 Create User page for detailed documentation on the structure of the JSON payload. The sample payload illustrates how to create a user with a few values defined dynamically using mustache variable substitution from the incoming message. Visit the Template Engine and Formatters page to learn more.


Username

The identifier for the user being updated. See the Jira API v2 Update User page for detailed documentation.


Update JSON Payload

The Update JSON Payload defines the update settings. See the Jira API v2 Update User page for detailed documentation on the structure of the JSON payload. This API is documented as experimental, but has been available since July 22, 2019. The sample payload illustrates how to update a user with a few values defined dynamically using mustache variable substitution from the incoming message. Visit the Template Engine and Formatters page to learn more.

Nevelex Labs, Main Office

Metro Office Park
2950 Metro Drive, Suite 104
Bloomington, MN 55425
Phone: +1 952-500-8921

©Nevelex Labs, LLC. 2018-2021, All Rights Reserved.

EULA