Jira

The Jira origin reads data from a Jira instance. For information about supported versions, see Supported Systems and Versions.

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

When you configure the Jira origin, you configure the Jira instance to send the request to, the authentication scheme to use for the request, and the parameters of the request.

You can optionally use a proxy server and configure TLS properties.

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

Event Generation

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

Events generated by the Jira origin can be used in any logical way. For example:
  • With the Pipeline Finisher executor to stop the pipeline and transition the pipeline to a Finished state when the origin completes processing available data.

    When you restart a pipeline stopped by the Pipeline Finisher executor, the origin continues processing from the last-saved offset unless you reset the origin.

    For an example, see Stopping a Pipeline After Processing All Available Data.

  • 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 origin have 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 origin finishes processing data.
  • no-more-data - Generated when the origin completes processing all available data.
  • start - Generated when the origin starts processing 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 Jira origin can generate the following types of event records:
finished
The origin generates a finished event record when the origin finishes reading data from the instance.

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

Field Description
webclient.pagination.calls.count The number of times the stage has paginated.
webclient.offset The pagination value for the current pagination.
webclient.time The time the stage finished reading data.
no-more-data
The Jira origin generates a no-more-data event record when the origin completes processing all data returned by all queries.

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

start
The origin generates a start event record when the origins starts reading data from the instance.

The start event record generated by the origin 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 The pagination value for the current pagination.
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 origin 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 resources without sharing credentials. The Jira origin uses credentials to request an access token from the service. The service returns the token to the origin, and then the origin includes the token in a header in each request to the Jira instance.

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 Origin

Configure a Jira origin to read data from a Jira instance.

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

    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.
  7. On the Request tab, configure the following properties:
    Request Property Description
    Search using JQL Parameters of the request in Jira Query Language (JQL).

    For information on using JQL, including JQL fields and functions, see the Atlassian documentation.
    Include Comments Include Jira issue comments in the response.
    Max Results Per Page Maximum number of Jira issues retrieved per page.

    Default is 50.
  8. On the Output tab, configure the following properties:
    Output Property Description
    Max Batch Size (records) Maximum number of records processed at one time. Honors values up to the Data Collector maximum batch size.

    Default is 1000. The Data Collector default is 1000.
    Batch Wait Time (secs) Number of seconds to wait before sending a partial or empty batch.