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 Versions and Available Features.
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.
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.
- 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.
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:
|
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.
- start
- The destination generates a start event record when the destination starts writing data to the instance.
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.
- 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. Using simple or bulk edit mode, click the Add icon to add additional certificates.
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.