PMG Documentation

# JIRA Connector

The PMG JIRA Connector provides the ability to interact with Jira Software and Jira ServiceDesk.

# JIRA Connector configuration

The Jira connector uses basic authentication to connect to the API endpoints. The authentication data is stored in an XML format. An example is shown below:

Example Connector Configuration:

<jira>
    <scenarios>
        <scenario default="true" username="bob" password="ABCDEFG" baseurl="https://jirainstance.net/rest/" />
        <scenario name="Scenario" username="bob" password="ABC" baseurl="https://jirainstance.net/rest/" />
    </scenarios>
</jira>

Note -- the passwords must be encrypted with encrypt method 2.

Each Jira action has a scenario property which needs to be given a value that matches the name attribute of a scenario defined in this XML. Multiple scenario nodes can be added to this XML configuration to allow the connector access to multiple Jira environments.

# JIRA Connector Actions

# Create Issue

ACTION FUNCTION:

The JIRA create issue action gives the workflow designer the ability to create an issue in JIRA.

ACTION OUTPUTS:

Success

Failure

ACTION PROPERTIES:

Scenario: The name of the scenario defined in the connector configuration

Web Timeout(sec): How long in seconds the HTTP request is given before timing out. Leave blank to use the default timeout setting

Project Key: The key of the project in which the issue will be created

Parent Key: The parent issue key if the issue is a sub-issue. Leave blank if the issue is not a sub-issue

Issue Type Name: The name of the issue type

Summary: A summary of the issue

Description: A description of the issue

Results Variable: A workflow variable which will hold the response of the request. The data format is JSON

Error Message Variable: A workflow variable which will hold the error message (if any)

Extra properties can be added to the action XML to pass more information to JIRA when this action creates an issue. Additional property nodes need to have the attribute includeField="true". If the property has a subfield, it needs to be specified in the subField attribute.

For example, issue type has a subfield of name, so the property node look like:

<property name="issuetype" displayname="Issue Type Name" type="workflowmemo" includeField="true" subField="name" helpstring="Issue type name" ></property>

This property will add a JSON object to a JSON document which is passed to JIRA:

"issuetype": {
          "name": "Task"
       }

# Edit Issue

ACTION FUNCTION:

The JIRA edit issue action gives the workflow designer the ability to edit an issue in JIRA.

ACTION OUTPUTS:

Success

Failure

ACTION PROPERTIES:

Scenario: The name of the scenario defined in the connector configuration

Issue Key: The issue key including the project key

Web Timeout(sec): How long in seconds the HTTP request is given before timing out. Leave blank to use the default timeout setting

Summary: A summary of the issue (if this is a field that needs to be updated)

Assignee Name: The login name of the person to whom the issue will be assigned

Priority Id: The Id of the priority level (if this is a field that needs to be updated)

Error Message Variable: A workflow variable which will hold the error message (if any)

To clear a field value during an edit issue request, pass in the value null.

Extra properties can be added to the action XML to pass more information to JIRA when this action updates an issue just as properties can be added to the create issue action. Unfortunately, certain fields cannot be updated using the update issue action and if those fields are added as properties, the values will be ignored. It is likely that another action will be created to assist the workflow designer in updating those fields.

# Get Issue

ACTION FUNCTION:

The JIRA get issue action gives the workflow designer the ability to get an issue in JIRA. It returns a JSON document describing the issue.

ACTION OUTPUTS:

Success

Failure

ACTION PROPERTIES:

Scenario: The name of the scenario defined in the connector configuration

Issue Key: The issue key including the project key

Fields: Optional comma separated values that specify which fields to return. If left blank, all fields will be returned

Expanded Fields: Optional comma separated values that specify which fields should include additional information (if any). If left blank, no extra fields will be expanded

Web Timeout(sec): How long in seconds the HTTP request is given before timing out. Leave blank to use the default timeout setting

Results Variable: A workflow variable which will hold the response of the request. The data format is JSON.

Error Message Variable: A workflow variable which will hold the error message (if any).

# JQL Search

Action Function:

The JQL Search action gives the workflow designer the ability to issue JQL queries and receive responses. The response is a JSON array with JQL results.

Action Outputs:

Success

Failure

Action Properties:

Scenario: The name of the scenario defined in the connector configuration

JQL: The Jira Query Language statement to be processed. An example query follows: "priority in (High, Critical) AND project in (PIN)"

Fields: Optional comma separated values that specify which fields to return. If left blank, all fields will be returned

Max Results: a limiter option for the number of results to be returned

Start At: An optional position to begin the response result set

Web Timeout(sec): How long in seconds the HTTP request is given before timing out. Leave blank to use the default timeout setting

Results Variable: A workflow variable which will hold the response of the request. The data format is JSON

Error Message Variable: A workflow variable which will hold the error message (if any)

# Issue Comment

` Action Function:

The Issue Comment action allows comments to be added, edited, or removed from issues

Action Outputs:

Success

Failure

Action Properties:

Scenario: The name of the scenario defined in the connector configuration

Issue Key: The issue ID for the comment management to occur

Comment ID: For the "Edit Type" property selections of "Edit" or "Remove" the Comment ID specifies on which comment to manage

Comment Body: The body of text to use for the comment

Visibility Type: The visibility type to use for the comment

Visibility Value: The visibility value to use for the comment

Edit Type: Determines the type of edit for the comment. Options are "Add", "Remove", and "Edit"

Web Timeout(sec): How long in seconds the HTTP request is given before timing out. Leave blank to use the default timeout setting

Results Variable: A workflow variable which will hold the response of the request. The data format is JSON

Error Message Variable: A workflow variable which will hold the error message (if any)

# JIRA Watcher Action

Action Function:

The Jira Watcher action allows for working with watchers for an issue

Action Outputs:

Success

Failure

Action Properties:

Scenario: The name of the scenario defined in the connector configuration

Issue Key: The issue ID for the issue

Action Type: Determines the action to take for the watcher and the respective issue. Options are "Add", "Remove", and "Get"

Username: The username to add or remove based on the Action Type

Exclude Avatar Urls: true or false option to exclude avatar URLs

Web Timeout(sec): How long in seconds the HTTP request is given before timing out. Leave blank to use the default timeout setting

Results Variable: A target variable to store the results for the Action Type "Get". The results are a JSON document

Error Message Variable: A workflow variable which will hold the error message (if any)

# Find Users

Action Function:

The Find Users action allows for searching for users within Jira. Results are returned as a JSON array.

Action Outputs:

Success

Failure

Action Properties:

Scenario: The name of the scenario defined in the connector configuration

Username: a substring of a username to search

Max Results: a limiter option for the number of results to be returned

Include Active Users: Specifies if active users should be included

Include Inactive Users: Specifies if inactive users should be included

Exclude Avatar URLs: Specifies if avatar URLs should be excluded

Web Timeout(sec): How long in seconds the HTTP request is given before timing out. Leave blank to use the default timeout setting

Results Variable: A workflow variable which will hold the response of the request. The data format is JSON

Error Message Variable: A workflow variable which will hold the error message (if any)

# Get Project Categories

Action Function:

This action will get a category, or all categories, returning as a JSON document

Action Outputs:

Success

Failure

Action Properties:

Scenario: The name of the scenario defined in the connector configuration

Category key: The category key of the category to return, leave blank to get all

Web Timeout(sec): How long in seconds the HTTP request is given before timing out. Leave blank to use the default timeout setting

Results Variable: A workflow variable which will hold the response of the request. The data format is JSON

Error Message Variable: A workflow variable which will hold the error message (if any)

# Get Projects

Action Function:

This action will get a project, or all projects, returning as a JSON document

Action Outputs:

Success

Failure

Action Properties:

Scenario: The name of the scenario defined in the connector configuration

Project key: The Project key of the project to return, leave blank to get all

Expanded Fields: Optional comma separated values that specify which fields should include additional information (if any). If left blank, no extra fields will be expanded

Exclude Avatar Urls: true or false option to exclude avatar URLs

Web Timeout(sec): How long in seconds the HTTP request is given before timing out. Leave blank to use the default timeout setting

Results Variable: A workflow variable which will hold the response of the request. The data format is JSON

Error Message Variable: A workflow variable which will hold the error message (if any)

← Microsoft Teams →