Note! Make sure that your site URL specified in Site Properties matches the Encodify System real URL. Otherwise, the bidirectional sync from Jira to Encodify will not work.
1. Configure Jira service
1.1. Jira account
Add new Jira Service from the available service types to start the configuration process.
You have to configure Jira account first to let the Encodify system access Jira and synchronize data.
Parameter | Description |
|---|---|
Service Name | Descriptive name of the integration service. The name will be displayed in the configuration of “Send to connected service” action |
Account | You can select from existing accounts or leave “Create new…” to create the new one on this step |
Account Name | Descriptive name of the connected account |
Base URL | URL to Jira system you want to connect. It must be the direct link, that will not produce any redirections to another page |
User Name | Verified Jira user email address (latest Jira uses email for authorizing a user). All synced issues in Jira will be updated by this user
|
Password | Jira user password
1. Generate an API token for Jira using your Atlassian Account: https://id.atlassian.com/manage/api-tokens. |
Timeout | Time during which system is trying to get a response from Jira. If the time elapsed and no response received, the timeout message will be shown |
Timeout Message | A message to be displayed if Jira is not available during the specified timeout |
1.2. Jira service parameters
Parameter | Description |
|---|---|
Module | A module in Encodify that will be used for connection |
Jira Issue ID | Text field in the chosen module which will be used for linking module item with Jira issue. This field is updated automatically by the system and must not be editable manually |
Jira Issue Key | Text field in the chosen module which will be used for storing the Jira issue key. This key then can be used for linking the Jira stories to Epics on sync. When linked child item is created in Encodify, it can inherit the Jira Epic key via auto filling functionality and use it for joining to corresponding Epic.
|
User | Encodify user account. Synced items will be updated by this user.
|
Jira Project | Select Jira Project |
Jira Issue Type | Select Jira issue type. As Jira maintains a different set of fields per each issue type, it is necessary to create a separate connected service for each issue type you are going to use |
1.3. Jira service mappings
On this step, you can map the fields from Encodify to the fields in Jira. Click on the Jira field in Available fields section to add one to mapping.
Note! The following Jira fields are not currently supported and will not be synced even if you map them:
Components
Issue links
Labels
Sprint
Numeric fields with multiple values
In the Mapped fields section you have to select the corresponding field from the Encodify module to map it to Jira field. For multi-optioned fields, you can map each option individually.
The user fields like Assignee, Reporter, Custom user do not require to map each user individually. It is enough to map the Jira field to Encodify User field (User management module link is also supported). The users are matched by email address automatically.
Note! When setting a User in Encodify to be synced with Jira Reporter field the Jira issue is created on behalf of the Jira System user (which is reflected in Jira activity stream) and then Reporter is changed to the one that comes from Encodify field. So we can see small inconsistency that Jira story has a different reporter in the log and main issue screen.
The mapping between fields is bidirectional by default, but you can choose one direction by clicking the icons with arrows.
| Bidirectional mapping. Fields will be mutually updated if you make changes in one of the systems or another |
| Encodify to Jira mapping. A field from Jira will be updated if you make changes in Encodify but not vice-versa |
| Jira to Encodify mapping. A field from Encodify will be updated if you make changes in Jira but not vice-versa |
Note! It is not recommended to map Encodify field of Integer type to Jira field as Jira numeric fields are always of decimal type. In this case, the decimal part might be lost on Jira -> Encodify sync. Try to use Encodify decimal fields for mapping with Jira numeric fields wherever possible.
You can select “Default” option instead of mapping a certain option value, that means that this option will be set by default in Jira issue on sync.
For example, you do not have “Priority” field in Encodify module and you also do not want to have it for mapping with Jira fields. But this field is present in Jira and you wish it to be “High” for every Jira issue created by synchronization with Encodify. So you can set “Default” for option “High”.
Attachment Jira field should be mapped to Multiple Files field in Encodify. It is available only if Attachment functionality is enabled in Jira for the user specified in the Connected Service settings.
Special cases
The timeout for uploading the file is set to 5 min. The sync of file uploaded in Encodify item will be rejected if the file requires more time to be uploaded to Jira system.
File will not be synced if the size exceeds the limit set in Jira configuration.
If there are previously existing synced items in both Encodify and Jira with a different set of files uploaded, mapping the Jira Attachments to the Multiple File field in Encodify will not sync them immediately.
If Item in Encodify is modified, the files that are missing in Jira item will be uploaded to Jira item. Existing items are kept.
If Item in Jira is modified, the files that are missing in Encodify item will be uploaded to Encodify item. Existing items are kept.
If several files with identical names were uploaded to Jira, they will be uploaded to Encoce item with appending GUID number for each duplicated file (as Encodify does not support files with identical names in Multiple file field). GUIDs are generated by Jira.
When max file limit size is changed in Jira it is necessary to resave the Jira Connected service to re-read the configuration. Otherwise, there might be a case when the limit has increased but Encodify still use the old value and blocks uploading files larger than the old limit.
2. Configure action
If you want Jira issues to be updated when you perform CRUD operations in Encodify, you have to create actions for each event: Create, Update, Delete, Workflow that corresponds to the main operations possible in Jira.
It is recommended to filter those actions by issue type to make sure that the action will be triggered only if an item of the corresponding type was modified.
Note! Jira status change triggers the Workflow transition in Encodify only if the corresponding transition exists. Otherwise, the Status field value will be simply changed without firing Workflow actions.
Additional Information
Classes for debug
dk.encode.ebms.connections.jira.JiraServiceImpl
dk.encode.ebms.connections.jira.JiraSyncMessageHandlerImpl
dk.encode.ebms.connections.jira.webhook.JiraWebhookServiceImpl