Connector for Jira

This topic describes the Jira connector introduced in 9.10, which supports single source for multiple projects.

This topic provides details for the Jira connector, including:

  • Connector Overview
    • The name of the .NET assembly file
    • The connection methodology
    • Use case scenarios
  • Connector Operation
    • Details for creating an Integration Source and Outbound Actions.
    • Architectural and functional details that ensure the running of the use case through the Inbound and Outbound action functionality of the Integration Platform.
  • Field Mappings
    • Details on mandatory fields, restricted fields, and how to map list item field values.
    • Examples for using transforms, profile maps and resolution rules.
  • Ongoing Operation
    • Steps for creating a Jira issue from a vFire Call or from a vFire workflow task.
    • How the updates are handled between the Jira issue and vFire call/task.
    • How to cancel the Jira issue from vFire and how to close the vFire call/task from Jira.

The Alemba.Connector.Jira.icnf needs to be configured before using the Jira Connector. For assistance configuring the ICNF file, contact your Account Manager to engage an Alemba Professional Services Consultant.

For compatibility and version support details, refer to the vFire Connector Matrix.

You should familiarize yourself with the information in Installing Connectors before installing any connectors, and read the Integration topics for more information on how to configure them.

Connector Overview

The vFire to Jira interoperability concept allows for the creation of issues in Jira triggered by actions sent from vFire. Once an issue is created in Jira, updates can be passed between the issue and the call or task in vFire that created it.

The Jira connector:

  • Sends transactions to the Jira REST API to perform actions such as creating issues in Jira, updating fields and comments in the issue, and updating issue status.
  • Retrieves transactions from Jira at polling intervals (vFire 9 Connector Service) to perform actions such as updating fields or adding notes to the vFire call or task.

The type of action performed is part of the Integration Platform settings, creating adequate transactions, ensuring proper communication, and maintaining reconciled information between vFire and Jira.

This connector can be used with the cloud version of Jira and the installed version.

Use Case Scenario

The interoperability concept can be broken down into several use cases that are listed in the table below.

Use case

Action performed in vFire

Action performed in Jira

Event

Scenario

Create transaction

A vFire call is forwarded externally; or

A vFire External Supplier Task is forwarded externally; or

A vFire Outbound Action Task is activated.

A Create message is sent to Jira.

In calls and External Supplier tasks, the outbound action is selected by matching the External Supplier and/or Contract.

Upon receipt of the Create action, Jira creates an issue based on the Outbound Action set up in the vFire Integration settings or Outbound Action Task settings.

Update transaction (outgoing)

The vFire call is updated; or

The vFire External Supplier Task is updated; or

The vFire Outbound Action Task is updated.

An Update action is sent to Jira.

Upon receipt of an Update action, Jira does any of the following:

  • Updates fields in Jira if mapped fields were updated in vFire
  • Adds a comment in Jira if 'Action & Solution' was updated in vFire

Update transaction (incoming)

The Jira issue is updated.

An Update message is sent to vFire.

Upon receipt of an Update action, vFire does any of the following based on integration settings:

  • Updates the call or task
  • Adds a note to the call or task
  • Takes no action

Notify transaction

A note is added to the vFire call or task.

A Notify action is sent to Jira.

Upon receipt of a Notify action, Jira adds a comment to the issue.

Cancel transaction

The vFire call or task is closed; or

The vFire call or task is taken back in vFire.

A Cancel action is sent to Jira.

Upon receipt of a Cancel action, Jira does any of the following:

  • Updates issue Status to the value defined in the vFire Source Connection Parameters; and
  • Updates fields in Jira if mapped fields were updated in vFire

  • Adds a comment in Jira if 'Action & Solution' was updated in vFire

Complete transaction

An issue is completed in Jira.

A Complete message is sent to vFire.

Upon receipt of a Complete action, vFire does any of the following based on integration settings:

  • Closes the call or task
  • Updates the call or task
  • Adds a note to the call or task

  • Takes no action

Connector Description

The table below provides a description of the Connector for Jira.

Information fields

Name

Connector name

Atlassian JIRA Connector

Third-party application

Atlassian Jira

Assembly

Alemba.Connector.Jira.dll

Configuration file

Alemba.Connector.Jira.icnf

Operation Method Jira REST API

Connection Parameters

When setting up a Jira source, the parameters listed below have to be defined.

Connection parameters

Description

URL

The address for the Jira system. For Jira Cloud, enter the web address. For installed Jira, use the server address.

https://myJIRAsystem.atlassian.net

https://myJIRAserver

Login ID

The Username of a Jira user, not their email address. This user must have sufficient rights to the project(s) and issue type(s), as well as issue create, edit and transition permissions.

Password

The password of the user defined in the Login ID.

Action and Communication Protocol

The connector allows issues to be created in Jira based on information sent by vFire. The creation and update of issues relies on actions being implemented between Jira and vFire. These actions are supported by a particular communication protocol composed of a set of specific transactions, as illustrated below.

  • vFire sends a Create message to initiate an action for Jira to perform.
  • Both vFire and Jira can send Update messages to each other when required.
  • vFire can send Notify messages to Jira when required.
  • vFire can send a Cancel message to stop any further processing of the issue in Jira.
  • A Complete message is sent by Jira when the issue is successfully completed.

Connector Requirements

Ensure the port for the REST API is open in the firewall. The default port is 443 for https.

Ensure the content type application/json is accessible through the firewall.

The Alemba.Connector.Jira.icnf needs to be configured before creating the Integration Source for Jira. Developer Notes for the Jira ICNF are available for developers experienced in customizing ICNF files. For assistance with the ICNF file, contact your Account Manager to engage an Alemba Professional Services Consultant.

Installation

No install is required for this connector. Upon install or upgrade to vFire Core 9.10 or higher, this connector is visible in the Integration module, ready to be configured.

An earlier version of the connector is available from 9.8, but this earlier version does not support multiple projects from a single integration source.

Diagnostics

The connector has the facility to trace information. The data can be obtained through Polling tracing or Application tracing.

Additional Information

This connector does not include any Federated CMDB population functionality.

Connector Operation

Steps required to make the Jira connector available for use:

  1. Verify the REST API is Accessible from the vFire server.
  2. Configure the Alemba.Connector.Jira.icnf file, as explained here.
  3. Configure vFire Core with a Source for Jira.
  4. Configure vFire Core for Outbound actions.

Users of the 9.8 Jira connector who are upgrading to 9.10 are advised to reconfigure the connector after upgrade.

Verify the REST API is Accessible

In a web browser, enter the endpoint address from the connector source connection details and append /rest/api/2/serverInfo. (case sensitive)

https://myJIRAsystem.atlassian.net/rest/api/2/serverInfo

The following page should be returned:

If this page is not returned there may be a blocked port on the firewall. Please contact your Network Administration team to resolve.

The Jira connector requires the configured port to be open on the firewalls between servers, including application/json messages. The default ports are 80 for http and 443 for https.

Configure a Source for Jira

Before you start

The Alemba.Connector.Jira.icnf file needs to be configured before creating the Source for Jira. For assistance configuring the ICNF file, contact your Account Manager to engage an Alemba Professional Services Consultant.

  1. Select and then Admin. From the submenu, select Integration.
  1. Select the Sources option from the explorer pane.
  2. Select the button on the toolbar. In the pop up window, select Atlassian JIRA Connector from the drop-down list.
  3. In the Integration Source Details window, complete the details.
  4. Name Key in a name for the integration source
    Status This field is pre-filled with the Active status
    Connector This field is pre-filled with the Connector type
    Assembly.TypeName This field is pre-filled based on the selected connector as defined in the Connector DLL, and is read-only
    JIRA Credentials
    URL

    Key in the address for the Jira system. For Jira Cloud enter the web address. For installed Jira use the server address.

    Login ID

    Enter the Username of a Jira user. This user needs access to the project(s) and issue type(s), as well as issue create, edit and transition permissions.

    Password

    Enter the password of the user defined in the Login ID.

    Further fields are displayed on this window, but you do not need to complete them at this stage.

  5. Select the button on the toolbar to test the connection.
  6. After 3 failed login attempts Jira may block the account and require a 'CAPTCHA' validation before unblocking it. Use a web browser to log into Jira with that login ID to complete the validation, and then attempt another test connect from the connector source.

  7. Save the details.

If the Source details are later changed, the vFire Connector Service must be restarted in order for the changes to take effect.

Configure the Outbound Actions

Outbound Actions are used by calls that are forwarded externally and by External Supplier tasks that are forwarded externally. The outbound action is selected by matching the external supplier and/or contract in the call or task to the external supplier and/or contract in the Outbound Action.

Outbound Action Tasks do not use these settings, and instead contain their own set of mappings which are configurable through the task in the workflow template.

Before you start

The Outbound Actions checkbox must be enabled in the Integration Platform Settings.

The integration Source for the Jira connector must be configured.

  1. Select and then Admin. From the submenu, select Integration.

  2. Select Outbound Actions from the explorer pane.
  3. In the Filter by Source field, select the Jira source name from the drop-down list; for example if you created a source with the title "My Jira Connector", this will be displayed in the list.
  4. All available outbound actions are listed in the browse table. Choose the one you want to work with and then select .
  5. The Outbound Action Type [action name] window is displayed.
  6. To create a new mapping select
  7. To edit an existing mapping, select the mapping and then select
  8. In the Mapping window, complete the details.
  9. Name Type a name for the mapping. This name appears in the Mappings table.
    Screen Set

    Select a call or External Supplier task screen set from the multi-tiered list. The screen set determines the fields that will be available for this mapping under the Fields - Outgoing and Fields - Incoming tabs.

    Call screen set

    Select to enable the Outbound Action to trigger when a call is forwarded externally. Call screen sets are defined by your system administrator.

    External Supplier
    screen set
    Select to enable the Outbound Action to trigger when an External Supplier task is forwarded externally. External Supplier task screen sets are defined by your system administrator.

    Outbound Action Tasks do not use these settings, and instead contain their own set of mappings which are configurable through the task in the workflow template.

    If you change the screen set after defining outgoing or incoming field mappings, a warning is displayed indicating that some field mappings may become invalid.

  10. To associate an external supplier and contract with the Outbound Action mapping, complete the details in the Suppliers & Contracts tab.
  11. External Supplier Select the external supplier configured for Jira.
    Contract Select a contract.

    If you do not specify a contract, the Outbound Action will be matched by the external supplier only.

  12. Select to add the external supplier and/or contract to the browse table. Whenever a call is forwarded to that external supplier and/or contract, this Outbound Action mapping will be applied.
  13. You cannot specify the same supplier and contract (per screen set) for more than one Outbound Action mapping. However, you can link an external supplier to one mapping and the same supplier plus a contract to another mapping. In this case, the most specific mapping will be applied: if the call/task is forwarded to a supplier and contract matching the supplier and contract specified on the second mapping, this mapping will be applied. If not, it will use the default mapping for that supplier.

  14. Select the Action tab and ensure that the rules for Incoming and Outgoing Transactions using this mapping are as wanted.
  15. The standard Jira REST API generates only two types of incoming transactions: Updated and Completed

  16. Select the Fields - Outgoing tab and specify how field values from the vFire Core call must correlate with the field values in Jira when an outgoing message is sent by vFire Core.
  17. To map a field, click Add. In the Add Fields window, select the fields (from Jira) you want to map to fields on the call/task, and click OK. On the browse table, click the corresponding cell in the Internal Field column. Then click the field selector button to pick a static value or a field relating to the screen set you selected earlier (including any custom fields created in Designer).
  18. Depending on the field’s data type, additional options can be selected in the field selector, including: field transformations, profile maps, or resolution rules. You can only select a field that is compatible with the field specified in the Action Field column.

  19. Select the Fields – Incoming tab and specify how the field values from Jira must match the field values on the call or task in vFire when an incoming message is received by vFire Core.
  20. To map a field, click Add. In the Add Fields window, select the fields from the selected Screen Set (including any custom fields created in Designer), you want to map to fields used in the external system. On the browse table, click the corresponding cell in the Action Field column. Then click the field selector button to pick a static value or a field from Jira. These fields are defined at the level of the connector.
  21. Depending on the field’s data type, additional options can be selected in the field selector, including: field transformations, profile maps, or resolution rules.

  22. In the Update column, select the conditions for populating the field on the call/task.
  23. Always always matches the vFire field value with the value in Jira. This means that any change to this field in Jira automatically updates the field value in vFire.
    Only When Blank only populates the vFire Core field with the value Jira if the field in vFire is blank. This means that an existing value on the vFire call or task cannot be overridden by a field value in Jira.
    On Initial Population Only is not relevant for Outbound Actions

  24. Save the mapping and the outbound action.

Field Mappings

This section provides information on how to map fields between vFire and Jira, limitations of certain fields, and examples for creating profile maps, resolution rules, and using transforms.

Mapping Fields between vFire and Jira

Mandatory Fields

All mandatory fields in Jira must be included in the vFire field mappings Fields - Outgoing tab.

If mandatory fields are not populated during Create transactions and Update transactions, the transactions will fail and the Jira issue will not be created created or updated.

By default, only the Summary field is mandatory in Jira. However other fields can also be set as mandatory within Jira by the Jira administrator. In this case, those fields must also be mapped as outgoing fields.

At a minimum the Jira Summary field must be mapped as an Outgoing field.

List Item Fields

The following Jira fields do not display a list of available list items in the vFire field mappings Fields - Outgoing tab. When mapping to these fields, enter the name of the Jira list item as a value into the field mappings, or map to a vFire field that contains the name of the Jira list item.

The values for these fields must already exist in Jira. Sending an unknown value to Jira will cause the Jira issue creation to fail.

Person fields
(e.g.: Reported By)

When mapping to person fields in Jira, enter the person's Jira Username as a value, or map to a vFire field that contains their Jira Username. This value must already exist in Jira.

When the Reported By field is not mapped, it is automatically populated in Jira as the person record used in the Integration Source settings.

Version Requires the name of the Jira list item (not the reference number); for example, if the Version field in Jira contains a list of versions that includes "ABC v9.0" you must pass "ABC v9.0" to Jira.
Label Requires the exact name of the Jira value you want in the field. This value must already exist in Jira.
Security Requires the exact name of the Jira value you want in the field. This value must already exist in Jira.

Restricted Fields

The following fields cannot be changed in Jira through field mappings and are not available in the Fields - Outgoing tab:

Project This value must be defined in the Alemba.Connector.Jira.icnf file.
Issue Type This value must be defined in the Alemba.Connector.Jira.icnf file.
Comments Updated each time the vFire Action & Solution field is updated in a call or task, or when a note is added to a call or task in vFire.
Resolution Automatically set by Jira.

For assistance with configuring the Alemba.Connector.Jira.icnf file contact your Account Manager to engage an Alemba Professional Services Consultant.

 

Examples of Field Mappings

The following examples illustrate some of the more commonly used outbound action field mappings that are configured in the Fields - Incoming and Fields - Outgoing tabs.

Using Profile Maps

Profile Maps are used to map list values (dropdown values) between Jira and vFire. These can be configured in the Fields - Incoming and Fields - Outgoing tabs.

  1. Select a dropdown type field in the Internal Field column.
  2. Select Profile Map... in the Action Field column
  3. Configure the profile mapping.
  4. Save the Profile Mapping.
  5. In the Behaviors tab the setting Create new is disabled and not supported for use with the Jira Connector.

Using Resolution Rules for Single QD Fields

Resolution Rules are used to map data from Jira to an entity in vFire, enabling Single QD fields in vFire to be populated from values in Jira. Resolution rules can also create a new entity if it does not already exist in vFire, such as a User. Resolution Rules are only available in the Fields - Incoming tab.

  1. Select a Single QD type field in the Internal Field column.
  2. Select Resolution Rule... in the Action Field column
  3. Set up a resolution rule.
  4. Save the resolution rule.
  5. In the Behaviors tab the setting Create new is available but should be used with caution, ensuring all required data is mapped for the new item.

Using Transforms

Transforms are used to modify data and populate a field with the modified/converted data, e..g concatenate two field values and populate a field with the results. See screenshots below.

Ongoing Operation

Once the interoperability has been set up, Jira issues can be created from vFire calls or vFire workflows.

The vFire 9 Connector Service must be running.

vFire Call to a Jira Issue

Follow these steps to transfer a call from vFire to Jira as a new issue:

  1. Open the call that is intended to be transferred.
  2. Click External to forward the call externally.
  3. Specify the External Supplier and the Contract defined for Jira
    See Configure the Outbound Actions.
  4. Click Forward to Supplier to transfer the call to Jira.
  5. If you are the contract manager for the external supplier you want to forward the call to, you can forward the call directly to that supplier. If you are not the contract manager for the external supplier, you first need to forward the call to a contract manager, who will then forward the call to the supplier.

  6. Once the call has been transferred, a button labeled Take Back is visible on the Call Details page. This button allows for the cancellation of the Jira issue and disables the reconciliation of information between the vFire call and Jira issue. The status of the Jira issue is updated as defined in the Jira Connector Source settings.

Linking an Analyst to a Contract

You may discover that when you forward a call externally and select the External Supplier and Contract that no analysts are available to forward the call or task. To resolve this:

  1. Create an external contact
  2. Create and link a contract to the external contact.
  3. Link the contract to all analysts who will be externally forwarding the call.

vFire Workflow Task to a Jira Issue

Two workflow tasks can be used to create issues and trigger actions in Jira:

External Supplier task

Specific external supplier and contract pairs have to be detailed in the External Supplier Task in the workflow template before it can execute in the request. In this case, settings for field mappings defined in the Outbound Actions page of the Integration platform are used when information is transferred to the Receiver system.

Outbound Action task

The Outbound Action Task in the workflow template enables the choice of a source and an action, as well as to define a task-specific mapping to be used by the selected action. These actions are executed when the task activates in the request.

When a note is added to the parent request of these tasks, the Comment field in Jira is updated.

Updates between Jira and vFire

It is not possible to transfer objects between vFire and Jira.

Update Intervals

The vFire 9 Connector Service retrieves updates from Jira at polling service intervals. When there are multiple updates to a Jira issue within a single polling interval, that update will appear in the vFire call or task as a single update.

vFire Call History and Jira Issue Comments

The Jira Comment field is updated from vFire when data is added to the task or call using the Action & Solution field, or when a Note is added to a task, call or request. No field mapping is required for the Action & Solution field or for Add Note.

The vFire call or task history is updated when a comment is added to the Jira issue, to show that comments were added, however the Comment text is not displayed in the history. Use field mappings to display the Jira Comment text in a vFire text area field on the vFire call or task screen.

Canceling a Jira Issue

On a vFire call or task, performing a Take Back or Close action will update the status of the Jira issue (as defined in the Alemba.Connector.Jira.icnf file), and break the link between them; essentially 'canceling' the Jira issue. No further updates will occur between issue and call/task. If the vFire call or task is forwarded externally again, a new Jira issue is created.

Changes are not saved upon pressing Take Back. Save any updates to the call before using the Take Back button.

For assistance with configuring the Alemba.Connector.Jira.icnf file contact your Account Manager to engage an Alemba Professional Services Consultant.

Closing a vFire call or task from Jira

Completing a Jira issue updates the vFire call or External Supplier task based on the Incoming Actions settings defined in the Action tab of the mapped Outbound Action. Depending on those settings the call/task may be updated, have a note added, perform no action, or be closed. In order to close a call or complete a task, the Close option must be selected. The options Update, Add Note, or Take no action will not close the call or task.

vFire Outbound Action Tasks do not allow configuration of incoming actions; completed Jira issues always perform a Complete transaction on the Outbound Action Task.

When a Complete transaction is sent to a vFire task, the task closes, its color changes to green, and any success paths in the workflow are activated.

Field mappings can be used to set call or task closure field values when the Jira issue is completed, such as Closure Reasons.