Jira

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

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.

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: 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 the following type:
  • no-more-data - Generated when the destination completes processing all available 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 type of event record:

no-more-data
The Jira destination generates a no-more-data event record when the destination completes processing all data returned by all queries.

The no-more-data event record generated by the destination has the sdc.event.type record header attribute set to no-more-data and does not include any additional fields.

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.

  1. 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.
  2. 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. For more information about credential stores, see Credential Stores in the Data Collector documentation.
    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. For more information about credential stores, see Credential Stores in the Data Collector documentation.

    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 more information about credential stores, see Credential Stores in the Data Collector documentation.
  3. 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.
  4. For Bearer authentication, on the Connection tab, configure the following property:
    Bearer Property Description
    Token Authentication token to access the requested resource.
  5. 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.
  6. 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. For more information about credential stores, see Credential Stores in the Data Collector documentation.

    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. For more information about credential stores, see Credential Stores in the Data Collector documentation.

    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.
  7. 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.