Jira

The Jira destination writes data to a Jira instance. For information about supported versions, see Supported Systems and Versions.

The Jira destination requires that Data Collector use Java version 17. For more information, see Java Version.

When you configure the Jira destination, you configure the Jira instance to send the request to and the authentication scheme to use for the request. You can optionally use a proxy server and configure TLS properties.

You can configure the destination to create a new Jira issue, delete an existing Jira issue, or update the properties of an existing Jira issue, including summary, description, priority, and issue type.

Note: This destination is a Technology Preview feature. It is not meant for use in production.

Event Generation

The Jira destination can generate events that you can use in an event stream. When you enable event generation, the destination generates event records each time the destination completes processing all available data.

You can use events generated by the Jira destination in any logical way. For example:

With the Email executor to send a custom email after receiving an event.
For an example, see Sending Email During Pipeline Processing.
With a destination to store event information.
For an example, see Preserving an Audit Trail of Events.

For more information about dataflow triggers and the event framework, see Dataflow Triggers Overview.

Event Records

Event records generated by the Jira destination include the following event-related record header attributes. Record header attributes are stored as String values:


Record Header Attribute	Description
sdc.event.type	Event type. Uses one of the following types: finished - Generated when the destination finishes writing data. start - Generated when the destination starts writing data.
sdc.event.version	Integer that indicates the version of the event record type.
sdc.event.creation_timestamp	Epoch timestamp when the stage created the event.

The destination can generate the following types of event records:

finished

The destination generates a finished event record when the destination finishes writing data to the instance.

The finished event record generated by the destination has the sdc.event.type record header attribute set to finished and includes the following fields:


Field	Description
webclient.pagination.calls.count	Not applicable.
webclient.offset	Not applicable.
webclient.last.page	Not applicable.
webclient.time	The time the write finished.

start

The destination generates a start event record when the destination starts writing data to the instance.

The start event record generated by the destination has the sdc.event.type record header attribute set to start and includes the following fields:


Field	Description
webclient.endpoint	The instance the data is read from.
webclient.offset	Not applicable.
webclient.method	The HTTP method used.
webclient.body	The body of the request.
webclient.time	The time the request was made.

OAuth 2 Authentication

The Jira destination can use the OAuth 2 protocol to connect to a Jira instance that uses basic or digest authentication, OAuth 2 client credentials, OAuth 2 username and password, or OAuth 2 access token.

The OAuth 2 protocol authorizes third-party access to HTTP service resources without sharing credentials. The Jira destination uses credentials to request an access token from the service. The service returns the token to the destination, and then the destination includes the token in a header in each request to the request endpoint.

The credentials that you enter to request an access token depend on the credentials grant type required by the Jira instance You can define the following OAuth 2 credentials grant types for Jira stages:

Client credentials grant

The stage sends its own credentials - the client ID and client secret or the basic authentication credentials - to the Jira instance.

For more information about the client credentials grant, see https://tools.ietf.org/html/rfc6749#section-4.4.

Access token grant

The stage sends an access token to an authorization service and obtains an access token for the Jira instance

Owner credentials grant

The stage sends the credentials for the resource owner - the resource owner user name, password, client ID, and client secret - to the Jira instance.

For more information about the resource owner password credentials grant, see https://tools.ietf.org/html/rfc6749#section-4.3.

Configuring a Jira Destination

Configure a Jira destination to write data to a Jira instance.

This destination is a Technology Preview feature. It is not meant for use in production.

In the Properties panel, on the General tab, configure the following properties:


General Property	Description
Name	Stage name.
Description	Optional description.
Produce Events	Generates event records when events occur. Use for event handling.
Required Fields	Fields that must include data for the record to be passed into the stage. Tip: You might include fields that the stage uses. Records that do not include all required fields are processed based on the error handling configured for the pipeline.
Preconditions	Conditions that must evaluate to TRUE to allow a record to enter the stage for processing. Click Add to create additional preconditions. Records that do not meet all preconditions are processed based on the error handling configured for the stage.
On Record Error	Error record handling for the stage: Discard - Discards the record. Send to Error - Sends the record to the pipeline for error handling. Stop Pipeline - Stops the pipeline.

On the Connection tab, configure the following properties:


Connection Property	Description
Authentication Scheme	Determines the authentication type used to connect to the Jira instance: None - Performs no authentication. Basic - Uses basic authentication. Requires a user email and API token. Use with HTTPS to avoid passing unencrypted credentials. Bearer - Uses bearer authentication. Requires a username and password. OAuth 1 - Uses OAuth 1.0 authentication. Requires OAuth credentials. OAuth 2 - Uses OAuth 2.0 authentication. Requires OAuth credentials.
Jira Instance	URL of the Jira instance to connect to. Enter the URL in the following format: `https://<account>.atlassian.net`
Keystore Management	Authentication and encryption used to connect to the Jira instance. Automatic - Uses automatically-generated keystore and truststore configurations. For most HTTP and HTTPS requests. Manual - Manually configure the keystore and truststore to use. For manually-configured HTTPS requests.
Keystore Location	Where to load the keystore from: Local - Loads the keystore from a local file. Remote - Loads the keystore from the provided key and certificate chain. Required for manual keystore management.
Keystore File	Path to the local keystore file. Enter an absolute path to the file or enter the following expression to define the file stored in the Data Collector resources directory: `${runtime:resourcesDirPath()}/keystore.jks` By default, no keystore is used. Available for manual keystore management.
Keystore Type	Type of keystore to use. Use one of the following types: Java Keystore File (JKS) PKCS #12 (p12 file) Default is Java Keystore File (JKS). Required for manual keystore management.
Keystore Password	Password to the keystore file. A password is optional, but recommended. Tip: To secure sensitive information such as passwords, you can use runtime resources or credential stores.
Private Key	Private key used in the remote keystore. Enter a credential function that returns the key or enter the contents of the key.
Certificate Chain	Each PEM certificate used in the remote keystore. Enter a credential function that returns the certificate or enter the contents of the certificate.
Keystore Key Algorithm	Algorithm to manage the keystore. Default is SunX509. Available for manual keystore management.
Truststore File	Path to the local truststore file. Enter an absolute path to the file or enter the following expression to define the file stored in the Data Collector resources directory: `${runtime:resourcesDirPath()}/truststore.jks` Required for manual keystore management.
Truststore Type	Type of truststore to use. Use one of the following types: Java Keystore File (JKS) PKCS #12 (p12 file) Default is Java Keystore File (JKS). Required for manual keystore management.
Truststore Password	Password to the truststore file. A password is optional, but recommended. Tip: To secure sensitive information such as passwords, you can use runtime resources or credential stores. Available for manual keystore management.
Truststore Key Algorithm	Algorithm to manage the truststore. Default is SunX509. Required for manual keystore management.
Default Protocol Versions	Use only modern default secure protocol versions. Available for manual keystore management.
Default Cipher Suites	Use only modern default cipher suites. Available for manual keystore management.
Use Proxy Server	Enables using a proxy server to connect to the system.
Proxy Server	Proxy server endpoint.
Proxy User	User name for proxy credentials.
Proxy Password	Password for proxy credentials. Tip: To secure sensitive information such as user names and passwords, you can use runtime resources or credential stores.

For Basic authentication, on the Connection tab, configure the following properties:


Connection Property	Description
User Email	Authentication user email address.
API Token	Authentication API token.

For Bearer authentication, on the Connection tab, configure the following property:


Bearer Property	Description
Token	Authentication token to access the requested resource.

For OAuth 1 authentication, on the Connection tab, configure the following properties:


OAuth 1 Property	Description
Consumer Key	Name of the OAuth consumer key.
Consumer Secret	OAuth consumer secret.
Access Token	OAuth 1.0 access token.
Token Secret	OAuth 1.0 token secret.

For OAuth 2 authentication, on the Connection tab, configure the following properties.

For more information about OAuth 2, see OAuth 2 Authentication.


OAuth 2 Property	Description
Grant Type	Grant type required by the HTTP service.
Token Endpoint	URL to request the access token.
Client ID	Client ID that the HTTP service uses to identify the HTTP client. Enter for the client credentials grant that uses a client ID and secret for authentication. Or, for the resource owner password credentials grant that requires a client ID and secret. Required for the Client Credentials grant.
Client Secret	Client secret that the HTTP service uses to authenticate the HTTP client. Enter for the client credentials grant that uses a client ID and secret for authentication. Or, for the resource owner password credentials grant that requires a client ID and secret. Tip: To secure sensitive information such as the JWT signing key, you can use runtime resources or credential stores. Required for the Client Credentials grant.
Signing Algorithm	Algorithm used to sign the access token. Required for the Access Token grant.
Signing Key	Private key that the selected signing algorithm uses to sign the access token. Tip: To secure sensitive information such as the JWT signing key, you can use runtime resources or credential stores. Required for the Access Token grant using a signing algorithm.
Token Headers	Headers to include in the access token Available for the Access Token grant.
Token Claims	Claims to include in the access token. Specify in JSON format. Enter each claim required to obtain an access token. You can include the expression language in the token claims. For example, to request an access token to read from Google service accounts, enter the following claims with the appropriate values: `{ "iss":"my_name@my_account.iam.gserviceaccount.com", "scope":"https://www.googleapis.com/auth/drive", "aud":"https://oauth2.googleapis.com/token", "exp":${(time:dateTimeToMilliseconds(time:now())/1000) + 50 * 60}, "iat":${time:dateTimeToMilliseconds(time:now())/1000} }` Required for the Access Tokens grant.
Owner User	Resource owner user name. Required for the Owner Credentials grant.
Owner Password	Resource owner password. Required for the Owner Credentials grant.
Owner Client ID	Resource owner client ID. Available for the Owner Credentials grant.
Owner Client Secret	Resource owner client secret. Required for the Owner Credentials grant.
Additional Parameters	Optional parameters to send to the token endpoint when requesting an access token. For example, you can define the OAuth 2 `scope` request parameter. Using simple or bulk edit mode, click the Add icon to add additional key-value pairs.

On the Request tab, configure the following properties:


Request Property	Description
Action	Action to perform. Choose one of the following actions: Create issue - Creates a Jira issue with the provided details. Update issue - Updates the Jira issue with the specified issue ID or key. Delete issue - Deletes the Jira issue with the specified issue ID or key.
Summary	Jira issue summary. You can use `record` functions to define the summary. For example, `{record:value(‘/summary’)}`. Required to create an issue.
Project	Jira project key. You can use `record` functions to define the project. For example, `{record:value(‘/project’)}`. Required to create an issue.
Priority	Jira issue priority. You can use `record` functions to define the priority. For example, `{record:value(‘/priority’)}`. Available when creating an issue.
Issue Type	Jira issue type. You can use `record` functions to define the issue type. For example, `{record:value(‘/issue_type’)}`. Required to create an issue.
Description	Jira issue description. You can use `record` functions to define the description. For example, `{record:value(‘/description’)}`. Available when creating an issue.
Issue ID	Issue ID or key for the Jira issue to modify. You can use `record` functions to define the issue ID. For example, `{record:value(‘/issue_id’)}`. Required to update or delete an issue.
New Summary	Updated Jira issue summary. This overwrites the previous issue summary. If you leave this field blank, the issue summary does not change. You can use `record` functions to define the summary. For example, `{record:value(‘/summary’)}`. Available when updating an issue.
New Priority	Updated Jira issue priority. This overwrites the previous issue priority. If you leave this field blank, the issue priority does not change. You can use `record` functions to define the priority. For example, `{record:value(‘/priority’)}`. Available when updating an issue.
New Issue Type	Updated Jira issue type. This overwrites the previous issue type. If you leave this field blank, the issue type does not change. You can use `record` functions to define the issue type. For example, `{record:value(‘/issue_type’)}`. Available when updating an issue.
New Description	Updated Jira issue description. This overwrites the previous description. If you leave this field blank, the issue description does not change. You can use `record` functions to define the description. For example, `{record:value(‘/description’)}`. Available when updating an issue.