Jira

The Jira source reads data from a Jira instance. For information about supported versions, see Supported systems and versions.

When you configure the Jira source, 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.

Event generation

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

Events generated by the Jira source can be used in any logical way. For example:

With the Pipeline Finisher executor to stop the flow and transition the flow to a Finished state when the source completes processing available data.
For an example, see Stopping a flow after processing all available data.
With a target to store event information.
For an example, see Preserving an audit trail of events.

Event records

Event records generated by the Jira source 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 source finishes processing data. no-more-data - Generated when the source completes processing all available data. start - Generated when the source 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 source can generate the following types of event records:

finished

The source generates a finished event record when the source finishes reading data from the instance.

The finished event record generated by the source 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 source generates a no-more-data event record when the source completes processing all data returned by all queries.

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

start

The source generates a start event record when the sources starts reading data from the instance.

The start event record generated by the source 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 source 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 source uses credentials to request an access token from the service. The service returns the token to the source, and then the source 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 source

About this task

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

Procedure

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 flow for error handling. Stop Flow - Stops the flow.

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, you can use runtime resources or credential stores. Required for the Client Credentials grant.
Signing Algorithm	Algorithm used to sign the access token. Default is None. Required for the Access Token grant.
Signing Key	Private key that the selected signing algorithm uses to sign the access token. When using Data Collector 7.2 and later, the key must be Base64-encoded. Tip: To secure sensitive information, 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
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.

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.