...

...

Field Mapping is defined in two stages (see below for more) and it requires contract bind to complete.

Technical user permission!

It is very important to keep in mind to extend Technical user permission (the one from connection) if new contracts are added for new projects.

Verify permission on different levels:

• Project roles (https://confluence.atlassian.com/jira/managing-project-roles-185729625.html)
• Permission Scheme (https://confluence.atlassian.com/jira/managing-project-permissions-185729636.html)
• Issue Security (https://confluence.atlassian.com/jira/configuring-issue-level-security-185729623.html)

You can browse contract's queue logs by pressing log icon:

Image Removed

More about Log Browser you can find below.

Fields Mapping

• Main Field Mapping setup is described in (2) Contract chapter.
• Additionally Field Mapping Templates chapter describes how to use predefined fields set.

There are some validators implemented around Field Mapping (select only relevant remote field type for your local one, provide local field name, etc.).

Section
Column width 8% Configuration synchronization can be forced on contract level: Image Removed If you see warning flag next to the link - that means there were some changes in configuration that awaits to be sent to the remote. (2) Contract There is a lot of configuration on contract page. There are validators that play a gatekeeper role for contract consistency. Nevertheless, there may be some backdoor that, if reported will be continuously improved. To make a contract valid you need to bind it with remote contract. So contract always works in pairs (local-remote). If you could not bind a contract to the remote: check if remote JIRA has pushed its configuration changes (how to do that - see Contract above) try to synchronize configuration locally too (how to do that - see Contract above) if after a while nothing changes check JavaScript error in web browser (usually available after pressing F12) check log files for errors (JIRA_HOME/log/atlassian-jira.log) In this example we have local contract named Default contract that binds to remote contract Default . When bind is done you should see remote contract triggers status (Active/Inactive). That gives you some hint about: synchronization scope mistakes on remote contract setup Column width 900px Info This chapter is for advanced users/admins. Diagnostic can be made on different levels. All levels are described in this chapter. Panel borderColor #0288D1 bgColor #F7F7F7 borderStyle solid Column width 500px Table of Contents Column width 400px Introduction Diagnostic Levels Center Level Configuration Level It relates to all configuration items in the plugin, such as (1) Connection, (2) Contract, Field Mapping Templates. That is the first level to check. Synchronization (from Adminstrator's Guide->Basic chapter). Pages in this section: Connection Diagnostic, Contract Diagnostic, Field Mapping Diagnostic Synchronization Level At this level you can diagnose data synchronization (issues, fields, comments, attachments). Infrastructure Infrastructure can be more difficult to diagnose because of many external factors that can interfere with synchronization. That level refers to SSO, HTTP accelerators, proxies, etc. Unresolved problems from other levels may lead to infrastructure. Architecture Info Deeper understanding of the plugin architecture may be helpful to resolve problems. The plugin uses two queues to handle messages (IN, OUT). Each JIRA instance has these queues. Please, read below all marks carefully. This is quite low level introduction which understanding may be crucial to resolve some problems. Message are stored in queues. Messages are flush after some period of time (see Services). There are several services and each service may have several tasks in sequence. For example OutgoingService do following: Process outgoing messages in NEW status (message types: Create, Update, Comment) Process outgoing messages in RETRY status (message types: Create, Update, Comment) Process outgoing messages in RETRY status (message types: Attachment) Process outgoing messages in NEW status (message types: Attachment) So you can image that single flush may not be able to process all data-synchronization at once.  Each service can execute in different order each time (depending on cron and execution duration). Each service has some tasks that change message statuses which need to wait for next service execution to process further. Communication depends on execution from both JIRAs. Flushing local queues is not enough to make synchronization happen. They need to be flushed on remote JIRA too. You can make flush faster from Synchronization web panel on issue (described below). Messages (and services) have two main categories: Data (fields, comments, attachments) Confirmation / Response (only for acknowledge) Queues are in JIRA DB. You can browse them with right tool (SQLDeveloper, Heidi, MySQL Query Browser, etc.). Communication is made using HTTP protocol. You can sniff this communication with tools like HTTPNetworkSniffer. Changes on issues are in 90% made using JIRA REST API. However this API is called from local JIRA (not remote). So this is internal HTTP communication. There are different strategies to handle: create-update, comments, attachments. So HTTP messages may differ. Data format is JSON. Preinstalled Components During installation plugin create one custom fieldsfield: InTENSO [Synchronizer] - Synchronized issues There is another custom field that can be setup manually: InTENSO [Synchronizer] - Synchronized issues view  Under the hood there are 7 services responsible for synchronization task: Outgoing Job -  it is responsible for sending changes data to remote JIRA, Incoming Job -  it is responsible for handling data receipt from remote JIRA, Outgoing Response Job - responsible for sending changes confirmation to JIRA which started data synchronization, Incoming Response Job - deals with incoming responses (mark data as synchronized), Archivization Job - move all synchronization data marked as done to archive, Pull Job - when JIRA is behind firewall(connection is in passive mode) and is not able to send synchronization data to remote instance, pull job in remote JIRA fetch data and performs synchronization, Pull Response Job - when JIRA is behind firewall(connection is in passive mode), this job in remote instance fetch all acknowledge information(it's similar to Outgoing Response Job, but works only when connection is in passive mode). You can decide how often jobs run, to do that set whatever Cron expression you like in general configuration of the synchronizer. See also SchedulersServices Configuration Synchronization Level (1) Connection Connection setup has a test which should be executed in first place (it may not be successful until the remote JIRA does not have corresponding connection set). So configuration sequence is as follows: setup local connection setup remote connection & test test local If you get negative test over and over: check log files for errors (JIRA_HOME/log/atlassian-jira.log) this is very likely that it may lead to infrastructure Info The plugin uses connection to synchronize configuration. Even though no (2) Contract is defined yet, there may be some communication over network between two JIRA instances. You can look for these errors in log files too.  Section Section Image Removed
Section
Info

In some cases you can find an error message in the log file that refer to Field Mapping problem:

ERROR Unsupported field type detected. Field Status (status) has no field mapper!

That means the field 'status' is not supported and cannot be synchronized. (For that particular field see Workflow Synchronization.)

However this error:

{"errorMessages":[],"errors":{"project":"project is required"}}

may have source in wrong Field Mapping (Remote Field names).

Synchronization Level

Synchronization
Issue Panel 

There is a web panel on issues that have a (2) Contract set.

Image Removed

Panel sections:

• General warning are shown on top (

  Status
  colour Yellow title warn

  ) and they should NOT be ignored. They may provide you quick answer why synchronization is not performed.

• Connections & Contracts
  • First line is a (1) Connection name and mode (

    Status
    colour Green title active

    or

    Status
    colour Yellow title Passive

    )
  • Below is a (2) Contract name and its status (

    Status
    colour Green title Enabled

    or

    Status
    colour Yellow title disabled

    )
    • Additional contract configuration is listed below.
      So for example if comments are not synchronized you may see that they are not enabled or you need to use External Comments Tab.
  • There can be many Connection/Contract for one issue.
• Message Types
  • Left group is for CREATE, UPDATE, ATTACHMENTS
    • Each message should receive RESPONSE (number of responses should match sum of messages)
    • Arrow next to CREATE informs whether issue was create in local JIRA (->) or remote (<-)
  • Right group is for COMMENTS
    • The flag icon informs that there is a message that waits for processing. You can see also that there is one response missing for comments.
• Outgoing & Incoming
  • 1/23 means that 23 outgoing messages were processed successfully. One is still processing.
  • It is not very likely you will see NEW & PROCESSING messages in Incoming queue because they are processed instantly. However, if you see messages there for a while that may indicate a problem.

Show Logs opens Log Browser in context of given issue (for more see Log Browser).

Image Removed Can be used to force queues processing. It is good for evaluation to speed-up a communication a bit. You can flush after making a changes that should be synchronized. Processing incoming changes and responses. You may need few seconds to see the change on the issue. After flush you should also refresh a page (F5).

Log Browser is available in Administration -> Add-ons -> IssueSYNC -> Logs Browser
 

Image Removed

• Queue Log - shows logs corresponding to QueueIn and QueueOut in the plugin. It is good to diagnose synchronization: messages, events/triggers, HTTP results.
• Plugin Log - it is low level log. There is information about Services execution, processing messages, etc.
• Diagnostic File - allows to download result from QueueLog, PluginLog and QueueIn/QueueOut content. Bundled and zipped files can be sent to our support for further investigation.

Log Files

JIRA has two folders with log files:

• JIRA_HOME/log
• JIRA_DISTRIBUTION_FOLDER/logs

In the first one, the plugin creates intenso-synchronizer.log file with most of its logs. In case the file size will reach 20 MB intenso-synchronize.log.1 will be created. After a while old log files should be removed.

Reading logs can be difficult because it contains error codes. For example:

2015-09-22 11:12:24|INFO |2|syn001|(SCHEDULED)| 

syn001 is a code that translates to "Archivization task was run!" (SCHEDULED)

Complete codes list can be found in plugin jar (downloaded from marketplace or from your JIRA_HOME/plugins/installed_plugins directory) in file synchronizer-extended-logger.properties

• Last log lines can be browse in Log Browser in Plugin Logs tab.
• Log files can be bundled and downloaded in Log Browser (Diagnostic File tab). In case of problem you can sent them to our support.

In some cases JIRA_HOME/log/atlassian-jira.log can includes some additional information that are not included in intenso-synchronizer.log. You may investigate these logs too (search over 'intenso' keyword) or send the file to our support.

Database

Queues can be browsed directly in database (use your favorite DB client):

• AO_6D516B_QUEUE_IN
• AO_6D516B_QUEUE_OUT

There is also a log queue that contains more details about communication:

• AO_6D516B_QUEUE_LOG

QueueIn Statuses:

• NEW (0)
  Message has arrived.
  
• PROCESSING (1)
  Update after create scenario - waits until response with created issue id will return.
  Message is awaiting some other dependent messages. Status very rare to happen.
• DONE (5)
• ERROR (6)
• RETRY (4) <- This one can be set manually (SQL Update Statement) to force resent of ERROR messages. *

QueueOut Statuses:

• NEW (0)
  Message has arrived.
• SENT (2)
  Message sent to (or pulled by) the remote.
• DONE (5)
• ERROR (6)
• RETRY (4) *

Few words about the sync flow

1. Everything starts when event selected in contract configuration occurs. Changes are filter by field mapping and synchronization string is created. This data are saved in database and are waiting for Outgoing Job to be send. If you want to see what data will be sent look into database table(A0_6D516B_QUEUE_OUT).
2. Outgoing Job send synchronization data stored in A0_6D516B_QUEUE_OUT to remote JIRA instance where data are saved in databse A0_6D516B_QUEUE_IN table. 
3. Incoming Job fetch data in status NEW / RETRY and build internal rest request to JIRA REST API. Depends on result update status and send response to JIRA which started conversation(more technically save data in A0_6D516B_QUEUE_OUT table).
4. Outgoing Response Job fetch response related data from A0_6D516B_QUEUE_OUT  and sends response to JIRA which started synchronization.
5. Incoming Response Job fetch data from A0_6D516B_QUEUE_IN table in database related to responses and update status of synchronization data from initial A0_6D516B_QUEUE_OUT records from point 1.

Disabled Contract

Contract can be disabled either one or both ways. Here are some rules that should apply

• If contract is disabled in LOCAL JIRA - all events (triggers) will be ignored. No data will recorded into queues.
• If contract is disabled in LOCAL JIRA but enabled in REMOTE - incoming messages will arrive but won't be processed.
• If contract is enabled in LOCAL JIRA but disabled on REMOTE - events will be processed, changes will be recorded in queues and sent to REMOTE; however REMOTE won't process communication any further (no response will arrive until contract will be enabled again in REMOTE).
• Both disabled in the same time - no communication recorded in queues, nothing is sent in context of given contracts.

HTTP / Firewall

In case of connection problem, one thing to check are firewall rules. Communication can be blocked either by local or remote environment.

Firewall should have exceptions that allow to pass HTTP communication on JIRA server port. For more details please check documentation for your firewall software.

HTTPS / SSL

If one JIRA communicates with another one via SSL protocol it is required that server has a valid certificate installed. You can use this plugin to do that https://marketplace.atlassian.com/plugins/com.atlassian.jira.plugin.jirasslplugin/server/versionhistory

This is required because it is server-server communication rather than client-server.

cURL

Use cURL tool to check connection problems.

• Tests should be executed on JIRA server.
• You need access to the server (SSH, Remote Desktop, etc.).
• If cURL is not available on the server please install it (http://curl.haxx.se/download.html) or ask your administrator to do that.

Execute cURL command like this:

curl -D- -u techUser:techUserPassword -X POST --data @test.json -H "Content-Type: application/json" https://my.jira.domain/rest/api/2/issue

Where:

• techUser is a technical user set in (1) Connection configuration
• techUserPassword is a password of technical user (you may consider to clean .bash_history file afterward for security reasons, because password is passed in open text)
• @test.json is a file (described below) that should be in the same directory where you run your cURL command
• https://my.jira.domain is your JIRA baseURL

Example test.json file:

{
    "fields": {
       "project":
       {
          "key": "DEMO"
       },
       "summary": "Issue created from REST.",
       "issuetype": {
          "name": "Bug"
       }
   }
}

This is create issue message (see JIRA REST API for more). You may need to customize this message to correspond your projects, issue types, required fields on create issue screen.

Expected result:

HTTP/1.1 201 Created
Server: Apache-Coyote/1.1
X-AREQUESTID: 753x265x1
X-ASEN: SEN-L5760827
Set-Cookie: JSESSIONID=4E76FC9C1CF6DC2968E99F9FCC212C2B; Path=/; HttpOnly
X-Seraph-LoginReason: OK
Set-Cookie: atlassian.xsrf.token=B4ZU-DJPZ-5KS0-30HD|2c3e821cadc54f8863793fd9e0f7698797800b37|lin; Path=/
X-ASESSIONID: 1sxm55y
X-AUSERNAME: admin
Cache-Control: no-cache, no-store, no-transform
X-Content-Type-Options: nosniff
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Mon, 21 Sep 2015 10:33:25 GMT

{"id":"10300","key":"DEMO-17","self":"https://my.jira.domain/rest/api/2/issue/10300"}

That test's result means:

• JIRA sees itself over the network using baseURL.
• Technical User has permissions to create issues.
• You know what fields are required to create given issue type in given project (may be helpful when defining Contract and Fields Mapping).

HTTP/1.1 400 Bad Request
Server: Apache-Coyote/1.1
X-AREQUESTID: 768x268x1
X-ASEN: SEN-L5760827
Set-Cookie: JSESSIONID=432B1110B607CFD9E17607472A03C6B4; Path=/; HttpOnly
X-Seraph-LoginReason: OK
Set-Cookie: atlassian.xsrf.token=B4ZU-DJPZ-5KS0-30HD|6a7aa3728c16031343a5d8eafe35ded827fb441a|lin; Path=/
X-ASESSIONID: 1j9b05l
X-AUSERNAME: admin
Cache-Control: no-cache, no-store, no-transform
X-Content-Type-Options: nosniff
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Mon, 21 Sep 2015 10:48:21 GMT
Connection: close

{"errorMessages":[],"errors":{"project":"project is required"}}

That result means the test has FAILED:

curl: (6) Could not resolve host: host-from-baseURL

Execute similar cURL command like int Test#1 but

instead of local JIRA Technical User, provide remote user with proper permissions You may need to ask remote JIRA administrator to create a test user for you.

HTTP Accelerators
Proxies 

Some problem may occur with HTTP accelerators like Varnish. You may consider to disable it for confirmation if it generates the problem.

SSO

Atlassian Crowd solution is supported.

In case of custom JIRA seraph authenticator - the result is unknown and depends on implementation. Please, contact our support if you find a problem with authenticator.

Epilog

Challenge

Changes made in one JIRA are isolated, they are not propagated automatically to remote JIRA instance. This delay may cause many problems and unexpected behavior and attract lot of attention and efforts to revert changes.

This section gives better understanding and described how to handle such situations.

What can change?

1. Connection settings - for example infrastructure changes, or password changes - what will be the symptoms in this situation? All messages will get error status, they can be retry when problem will be solved.

2. Contract changes - has major influence on remote JIRA instance

3. JIRA technical user change permission, roles or is no longer presence.

4. JIRA project settings can change - required fields and others

5. Workflow can be changed - has influence on status synchronization

6. More than one customfield of type Issue  Status Synchronization, or Synchronized issues will be added.

What influence can those changes have on JIRA in time aspect?

Basically if we edit local contract remote JIRA still send different data so the result is invalid, even parallel change do not guarantee that data will be consistent. Possible solutions:

• Block contract edition (by policy)

• Make contract changes in maintain window, to be sure that no one will create issue

How to deal with changes?

Synchronization Issue Panel	There is a web panel on issues that have a (2) Contract set. Info This panel can be disabled in general plugin configuration. Image Added Panel sections: General warning are shown on top ( Status colour Yellow title warn ) and they should NOT be ignored. They may provide you quick answer why synchronization is not performed. Connections & Contracts First line is a (1) Connection name and mode ( Status colour Green title active or Status colour Yellow title Passive ) Below is a (2) Contract name and its status ( Status colour Green title Enabled or Status colour Yellow title disabled ) Additional contract configuration is listed below. So for example if comments are not synchronized you may see that they are not enabled or you need to use External Comments Tab. There can be many Connection/Contract for one issue. Message Types Left group is for CREATE, UPDATE, ATTACHMENTS Each message should receive RESPONSE (number of responses should match sum of messages) Arrow next to CREATE informs whether issue was create in local JIRA (->) or remote (<-) Right group is for COMMENTS The flag icon informs that there is a message that waits for processing. You can see also that there is one response missing for comments. Outgoing & Incoming 1/23 means that 23 outgoing messages were processed successfully. One is still processing. It is not very likely you will see NEW & PROCESSING messages in Incoming queue because they are processed instantly. However, if you see messages there for a while that may indicate a problem. Show Logs opens Log Browser in context of given issue (for more see Log Browser). Image Added Can be used to force queues processing. It is good for evaluation to speed-up a communication a bit. You can flush after making a changes that should be synchronized. Processing incoming changes and responses. You may need few seconds to see the change on the issue. After flush you should also refresh a page (F5).
Anchor logbrowser logbrowser Log Browser	Log Browser is available in Administration -> Add-ons -> IssueSYNC -> Logs Browser   Image Added There are three tabs: Queue Log - shows logs corresponding to QueueIn and QueueOut in the plugin. It is good to diagnose synchronization: messages, events/triggers, HTTP results. Plugin Log - it is low level log. There is information about Services execution, processing messages, etc. Diagnostic File - allows to download result from QueueLog, PluginLog and QueueIn/QueueOut content. Bundled and zipped files can be sent to our support for further investigation.
Log Files	JIRA has two folders with log files: JIRA_HOME/log JIRA_DISTRIBUTION_FOLDER/logs In the first one, the plugin creates intenso-synchronizer.log file with most of its logs. In case the file size will reach 20 MB intenso-synchronize.log.1 will be created. After a while old log files should be removed. Info Reading logs can be difficult because it contains error codes. For example: 2015-09-22 11:12:24|INFO |2|syn001|(SCHEDULED)|  syn001 is a code that translates to "Archivization task was run!" (SCHEDULED) Complete codes list can be found in plugin jar (downloaded from marketplace or from your JIRA_HOME/plugins/installed_plugins directory) in file synchronizer-extended-logger.properties Last log lines can be browse in Log Browser in Plugin Logs tab. Log files can be bundled and downloaded in Log Browser (Diagnostic File tab). In case of problem you can sent them to our support. In some cases JIRA_HOME/log/atlassian-jira.log can includes some additional information that are not included in intenso-synchronizer.log. You may investigate these logs too (search over 'intenso' keyword) or send the file to our support.
Database	Queues can be browsed directly in database (use your favorite DB client): AO_6D516B_QUEUE_IN AO_6D516B_QUEUE_OUT There is also a log queue that contains more details about communication: AO_6D516B_QUEUE_LOG QueueIn Statuses: NEW (0) Message has arrived. PROCESSING (1) Update after create scenario - waits until response with created issue id will return. Message is awaiting some other dependent messages. Status very rare to happen. DONE (5) ERROR (6) RETRY (4) <- This one can be set manually (SQL Update Statement) to force resent of ERROR messages. * QueueOut Statuses: NEW (0) Message has arrived. SENT (2) Message sent to (or pulled by) the remote. DONE (5) ERROR (6) RETRY (4) * Few words about the sync flow   Everything starts when event selected in contract configuration occurs. Changes are filter by field mapping and synchronization string is created. This data are saved in database and are waiting for Outgoing Job to be send. If you want to see what data will be sent look into database table(A0_6D516B_QUEUE_OUT). Outgoing Job send synchronization data stored in A0_6D516B_QUEUE_OUT to remote JIRA instance where data are saved in databse A0_6D516B_QUEUE_IN table.  Incoming Job fetch data in status NEW / RETRY and build internal rest request to JIRA REST API. Depends on result update status and send response to JIRA which started conversation(more technically save data in A0_6D516B_QUEUE_OUT table). Outgoing Response Job fetch response related data from A0_6D516B_QUEUE_OUT  and sends response to JIRA which started synchronization. Incoming Response Job fetch data from A0_6D516B_QUEUE_IN table in database related to responses and update status of synchronization data from initial A0_6D516B_QUEUE_OUT records from point 1.
Disabled Contract	Contract can be disabled either one or both ways. Here are some rules that should apply Status colour Blue title since v0.8.1 If contract is disabled in LOCAL JIRA - all events (triggers) will be ignored. No data will recorded into queues. If contract is disabled in LOCAL JIRA but enabled in REMOTE - incoming messages will arrive but won't be processed. If contract is enabled in LOCAL JIRA but disabled on REMOTE - events will be processed, changes will be recorded in queues and sent to REMOTE; however REMOTE won't process communication any further (no response will arrive until contract will be enabled again in REMOTE). Both disabled in the same time - no communication recorded in queues, nothing is sent in context of given contracts.

Column
width 8%