Sync Jira between two sites with no middleware: how Hooq connects

Need work items to flow between two Jira Cloud sites? See how a Hooq connector links them directly, with no server of ours between them.

5 min read

Your team works in one Jira Cloud site and a partner, a subsidiary or a customer works in another. Work items need to appear on both sides and stay in step, but you do not want a third system sitting between the two sites, holding copies of your work. Hooq is built for exactly that case: site A talks to site B directly, one to one, with no middleware server of ours in between.

What "nothing in the middle" means#

Hooq is an Atlassian Forge app for Jira Cloud, installed from the Atlassian Marketplace. It runs on Atlassian's platform and Limbus Lab does not operate a server, database or storage for it. When a work item changes on site A, Hooq on site A sends a signed message straight to Hooq on site B, and Hooq on site B checks it before writing anything. The message travels over Atlassian's own infrastructure, not through a server that anyone at Limbus Lab runs.

Some sync apps pass your work items through a server run by the app's vendor. A useful question to ask any sync app is: does my data pass through a server operated by the vendor? For Hooq, the answer is no, because there is no such server.

What a Hooq is#

In Hooq, one pair of projects together with the rules for how they are synced is called a Hooq. You can have many of them. There are two kinds:

  • Same instance: two projects on the same Jira Cloud site. No connector needed.
  • Cross instance: a project on your site and a project on another Jira Cloud site that also has Hooq installed. This needs a connector.

Both sites must run the current version of Hooq. Connecting sites that run different versions is not supported.

The connector: how two sites learn to trust each other#

A connector is the trusted link between the Hooq on your site and the Hooq on the other site. One connector can serve several Hooqs, and each partner site gets one connector. You set it up on the Connectors page, and you need a Jira administrator on each site. The pairing uses two small text files, each under 16 KB.

  1. Administrator A opens Hooq, chooses Connectors, selects New Connector and downloads the public key file (it ends in .hooqkey). A public key identifies the Hooq on a site and is meant to be shared. It is not a password.
  2. A sends the key file to administrator B.
  3. B uploads it under Generate for partner and downloads a connector file (it ends in .hooqconnector).
  4. B sends the connector file back to A. It is valid for 5 minutes, so A and B do this part in one sitting.
  5. A uploads the connector file, checks the connector name and selects Save. The connector is now Pending.
  6. A selects Activate to complete the handshake. The status becomes Active.

Site B then shows an Active connector for site A without any further steps. The whole job takes about 15 minutes with a person on each site. The full walk-through is in Connect two instances with pairing files, and the statuses (Draft, Pending, Active, Failed) are explained on the Connectors page.

Creating the Hooq, with both sides agreeing#

Once the connector is Active, an administrator creates a Hooq with another Cloud instance. They choose a project on their own site, pick the partner site, and type the project key on the other side. The window tells them that sending the request allows the partner site to view their space configuration, including all fields.

The partner site then sees the same Hooq in its list with a banner, Incoming Hooq request, and an administrator selects Approve Hooq or Decline. Until the other site approves, only the Hooq tab is available. Nothing syncs on one side's say-so. See Create a Hooq for the steps.

After approval, you map work types, fields and statuses, publish the configuration and start the Hooq. A Hooq works only while it is running and its configuration is published.

What travels across#

Only what the administrators chose to sync travels from one site to the other. In practice, that is:

  • New work items of the work types you matched, which create a copy in the other project.
  • Changes to the fields you mapped. A change to any other field is ignored.
  • Status changes, using the statuses you matched in the Workflows tab.
  • New comments and attachments, including images and files shown inside descriptions and comments.
  • Worklogs, when the Worklogs tab is on.

Syncing is event driven: Hooq reacts when a work item changes, and most changes arrive within seconds. Files sent between two different sites can be up to about 3.5 MB each, a limit that comes from the Forge platform.

What Hooq leaves alone#

Hooq keeps its hands off several things by design:

  • It never deletes the copy of a work item when you delete the original. It marks the pair as no longer Hooqed instead.
  • It never sets itself as the assignee of a work item.
  • It does not copy work items that existed before you started the Hooq, unless you limit the Hooq with a JQL filter in the Work Types tab.
  • It does not add Jira issue links between the two work items. A panel on each work item, the Hooq - Work Sync Panel, shows the partner and offers Resync, a comment and an attachment.

The full list is on What to expect.

Who needs to be involved#

Only Jira administrators set up and manage Hooq. Everyone who can see a work item can use the panel on it. Before you start, write down which work types, fields and statuses match between the two projects. The Before you start page has the checklist.

Share this post

Related help pages

Back to Blog