TIBCO Scribe® Online Connector For Jira

The TIBCO Scribe® Online Connector for Jira is based on the CData driver for Jira. Integrate Jira with your CRM system to give salespeople up-to-date information on customer support issues or software development progress. The Connector supports source and target operations for common Jira objects, including issues, comments, and attachments. This Connector based on Scribe.Connector.AdoNet library and CData Jira ADO.NET provider.

Possible use cases for the Jira Connector include:

• Get information about Issues
• Manage Issues and Sprints
• Change issue statuses
• Manage ProjectComponents and ProjectVersions

Connector Specifications

Supports version 7.1.0 of the Jira API.

	Supported
Agent Types
Connect on-premise	X
Connect cloud	X
Data Replication Apps
Source
Target
On Schedule Apps
Source	X
Target	X
On Event Apps
Source	X
Target	X
Flows
Integration	X
Request-Reply	X
Message

Supported Entities

The Jira Connector supports the following entities. Click a linked entity name for additional information when using that entity in TIBCO Cloud™ Integration - Connect.

Standard Operations

Entity	Query	Create	Update	Delete	Upsert
Attachments	X	X	X	X
BoardIssues	X
Boards	X
BoardSprints	X
Comments	X	X	X	X
Configuration	X
Dashboards	X
Fields	X
Filters	X
Groups	X
IssueAffectedVersions	X
IssueChangelogs	X
IssueComponents	X
IssueFixVersions	X
IssueLinks	X
Issues	X	X	X	X
IssueSubtasks	X
IssueTransitions	X
IssueTypes	X
ProjectComponents	X	X	X	X
Projects	X
ProjectVersions	X	X	X	X
RoleDetails	X
Roles	X
SprintIssues	X
Sprints	X	X	X	X
Statuses	X
Users	X
Votes	X
Watchers	X
Workflows	X
Worklogs	X	X	X	X

Special Operations

Supports the Execute Block to execute stored procedures, where each stored procedure is represented as an entity and each input parameter is represented as a field within that entity. See Execute Block and the CData Jira documentation for additional information.

Setup Considerations

There are no special setup considerations for this Connector.

API Usage Limits

Selecting An Agent Type For Jira

Refer to TIBCO Cloud™ Integration - Connect Agents for information on available agent types and how to select the best agent for your app.

Connecting To Jira

1. Select Connections from the menu.
2. From the Connections page select Create to open the Create a connection dialog.
3. Select the Connector from the list to open the Connection dialog, and then enter the following information for this Connection:
   • Name — This can be any meaningful name, up to 25 characters.
   • Alias — An alias for this Connection name. The alias is generated from the Connection name, and can be up to 25 characters. The Connection alias can include letters, numbers, and underscores. Spaces and special characters are not accepted. You can change the alias. For more information, see Connection Alias.
   • URL — Enter the URL used to access your Jira account.
   • User — User name used to access your Jira account.
   • Password — Password used to access Jira account.
   • Additional Parameters — Optional field where you can specify one or more connection string parameters. See the Connection String Options section of the CData documentation for a list of parameters that can be used and their default values. Note that in some cases the CData Jira ADO.NET Provider does not fully support all of the possible parameters.

     Syntax for the Additional Parameters field is as follows:

     • All blank characters, except those within a value or within quotation marks, are ignored
     • Preceding and trailing spaces are ignored unless enclosed in single or double quotes, such as Keyword=" value"
     • Semicolons (;) within a value must be delimited by quotation marks
     • Use a single quote (') if the value begins with a double quote (")
     • Use a double quote (") if the value begins with a single quote (')
     • Parameters are case-insensitive
     • If a KEYWORD=VALUE pair occurs more than once in the connection string, the value associated with the last occurrence is used
     • If a keyword contains an equal sign (=), it must be preceded by an additional equal sign to indicate that the equal sign is part of the keyword
     • Parameters that are handled by other fields or default settings in the Connection dialog are ignored if used in the Additional Parameters field, including: 
       • ConvertDateTimeToGMT
       • Logfile — This parameter is not visible in the Connection dialog, but is set by the Connector. The default size is a maximum of 10MB. Any CData log files generated by this setting are stored in the default Connect on-premise Agent Logs directory, C:\Program Files (x86)\Scribe Software\TIBCO Scribe® Online Agent\logs\. The format for log file names for CData logs are as follows: <ConnectorName><GUID of the Connection><DateTimeStamp>.log
         Note: For information on setting log file verbosity, see Verbosity in the CData Help.
       • MaxLogFileSize — This parameter is set by the Connector to a maximum of 10MB.
       • Other
       • RTK
4. Select Test to ensure that the agent can connect to your database. Be sure to test the Connection against all agents that use this Connection. See Testing Connections.
5. Select OK/Save to save the Connection.

Metadata Notes

Relationships

• Hierarchical relationships, such as grandparent, parent, grandchild relationships are not supported. See Hierarchical Data for examples.
• Parent/Child relationships are not supported.

Naming

Connection metadata must have unique entity, relationship, and field names. If your Connection metadata has duplicate names, review the source system to determine if the duplicates can be renamed.

Using An RSD File As A Schema

As mentioned in the Naming section of this document, all table, relationship, and field names in your source system must be unique. If you have a situation in which you cannot modify a duplicate name or if you want to limit the columns of information returned, you can use an RSD file to define the schema for your source data and include the item with the duplicate name. Using an RSD file has the following requirements: 

• You must use an On-Premise Agent because the RSD file must be stored in the Connector folder on the Agent.
• After the Connector is installed, navigate to the Connector installation folder and create a sub-folder named db where you will store the RSD file. If your Agent and your Connector are installed in the default location, the folder path is as follows: 

  C:\Program Files (x86)\Scribe Software\TIBCO Scribe® Online Agent\Connectors\Scribe.Connector.Jira\db\myschema.rsd

  Warning: Keep a copy of the .rsd file in a safe location. If there is a Connector update, the entire Connector folder is deleted and replaced with the files for the updated Connector. After a Connector update you must create the db folder and add the .rsd file to that folder again.
• In the Connection dialog for your Jira Connector, add a Location parameter with the full path to the RSD file in the Additional Parameters field, for example:

  Location="C:\Program Files (x86)\Scribe Software\TIBCO Scribe® Online Agent\Connectors\Scribe.Connector.Jira\db\"

• When configuring your RSD file, note the following:
  • Refer to the Custom Fields information in the CData Help for detailed information on RSD files and examples.
  • Refer to Jira REST API examples for details on configuring different field types.
  • When adding and configuring custom fields in the RSD file, include the custom field ID and the datatype. These are required for updating the other:relativexpath and other:urlname parameters. For example, if the field is a SelectList field, the other:relativexpath field is configured as "fields/customfield_13440/value" .
  • For datetime fields set the xs:type parameter to "datetime".
  • For array or JSON type custom fields, the other:aggregate parameter is required.
  • For most other fields set the xs:type parameter to "string" .
  • The StatusId column in the RSD file is required for the Jira Issues object.
  • When the RSD file is complete and stored in C:\Program Files (x86)\Scribe Software\TIBCO Scribe® Online Agent\Connectors\Scribe.Connector.Jira\db\ and the Additional Parameters have been configured in the Jira connection dialog, reset metadata for the connection to retrieve the new or updated schema and make it available when configuring flows. If you do not see the tables and fields configured in your RSD file when working in a flow, try resetting metadata again. See Resetting Metadata.

Jira Connector As An App Source

Consider the following when using the Jira Connector as an app source.

Custom Fields

By default, Jira objects expose only default and system fields. To access custom fields for Issues and other objects, as well as system fields, add the IncludeCustomFields=TRUE parameter in the Additional Parameters field on the Connection dialog. For more details on this connection string, see IncludeCustomFields in the CData documentation.

Pseudo Columns

Pseudo column fields are used in the WHERE clause of SELECT statements in Native Query Blocks and offer more granular control. To use them, set Pseudo Columns in the Additional Parameters field on the Connection dialog. Enabling Pseudo Columns allows you to use native Jira Query Language (JQL) for some Jira objects. See Jira datamodel in the CData documentation.

Use pseudo columns only inside the JQL property. This approach ensures that your queries are translated directly into Jira query language without any modifications. For more information, see Pseudo Columns in the CData documentation.

Filtering

Filter entities by using SQL and JQL. Every Jira object has different filtering abilities. Refer to the CData documentation for additional details on filtering. To enable JQL, set the Pseudo Columns connection string setting in the Additional Parameters field on the Connection dialog.

Net Change

Net Change is supported.

When a datetime is configured on the Query block on the Block Properties Net Change Tab to query for new and updated records, that configuration is treated as an additional filter. The Net Change datetime filter is applied as an AND after any other filters specified on the Block Properties Filter Tab. TIBCO Cloud™ Integration - Connect builds a query combining both the Net Change filter and the filters on the Filter tab. See Net Change And Filters for an example.

Some Connectors for TIBCO Cloud™ Integration - Connect only support one filter. For those Connectors you can use either Net Change or one filter on the Filter tab, not both.

DateTime

Some entity fields do not support the equals (=) operator for datetime comparison, such as the Created field in the Issues entity. Queries for a specific date can be constructed like this:

created > "2011/01/15" and created < "2011/01/16"

For more information about datetime filtering with examples, see Created in the Jira Software Support documentation.

Native Query

The Jira Connector supports SQL queries in Native Query Blocks to create customized queries for Jira. The query can be as simple or complex as you need it to be; however, it should return a single result set. The native query text is sent to Jira exactly as it is entered without any modifications.

You can use SELECT , UPDATE , INSERT and DELETE clauses. If support for Enhanced SQL is enabled, you can use Joins and Aggregate functions. For additional details, see the SQL Compliance section of the CData documentation .

After entering the SQL query, you must select Test to validate the query. Invalid queries are not accepted by the Connector. See Native Query Block and Creating Native Queries For Microsoft SQL Server for additional information.

When testing a Native Query in a flow, if the source datastore does not return any data, TIBCO Cloud™ Integration - Connect cannot build the schema for the underlying metadata and the flow cannot be saved. To allow TIBCO Cloud™ Integration - Connect to build the schema, do the following:

1. Create a single temporary record in the source datastore that matches the Native Query.
2. Test the Native Query and ensure that it is successful.
3. Save the flow.
4. Remove the temporary record from the source datastore.

Jira Connector As An App Target

Consider the following when using the Jira Connector as an app target.

Batch Processing

Batch processing is not supported.

Notes On Standard Entities

Issues

• Filtering - The less than (<) and greater than (>) operators are not supported when filtering by Issue Id.
• StatusId — This field is read-only when accessed directly. It can be modified with the Execute Block using the ChangeIssueStatus stored procedure. See ChangeIssueStatus in the CData documentation.

TIBCO Cloud™ Integration - Connect API Considerations

To create connections with the TIBCO Cloud™ Integration - Connect API, the Jira Connector requires the following information:

Connector Name	Jira
Connector ID	AFFB2AAF-52D0-4CD8-8B2F-D12439490100

TIBCO Cloud™ Integration - Connect Connection Properties

In addition, this Connector uses the Connection properties shown in the following table.

Name	Data Type	Required	Secured	Usage
URL	string	Yes	No
User	string	Yes	No
Password	string	Yes	Yes
Additional Parameters	string	No	No

License Agreement

The TIBCO End User License Agreement for the Jira Connector describes your and TIBCO's legal obligations and requirements. TIBCO suggests that you read the End User License Agreement.

More Information

For additional information on this Connector, refer to the Knowledge Base and Discussions in the TIBCO Community.