Requirement Yogi relies on "Application links" to communicate between Confluence and Jira.

• Jira has a given Applink ID (UUID) in Confluence,
• Confluence has another Applink ID (UUID) in Jira.

If you change the applink keys, all relations are broken. Your Jira issues won't be updated with the latest requirement text; the requirements won't list the related issues; and the list will fill up. To fix those, we've detailed the following steps.

Prerequisites

Those instructions are valid for Requirement Yogi 2.2.x and 2.3.x.

You have first removed and recreated an Application Link between Confluence and Jira. Note: This wasn't the right thing to do for us, but you probably didn't know it, or didn't have the choice, so we'll help you from here. So, long story short: The new Applink exists and is connected.

You've added a username for the new Applink in the Requirement Yogi administration in Confluence, tab "Integrations".

In Confluence

Shut down Confluence

We don't know what is the impact of performing these changes while Confluence is running, so by default we recommend shutting down Confluence. If you don't follow this recommendation, please at least disable Requirement Yogi temporarily before changing the database. (In development, we've always had success changing values in live, but in development we don't need reliability of data).

Get the old and new Applink ID

All the tables of Requirement Yogi in Confluence start with AO_32F7CE.

Depending on your database, the quotes can be:

• Not required,
• `
• '
• "
• [ ]

SELECT * FROM "AO_32F7CE_AOINTEGRATION" WHERE "SERVICEID" = "APPLINKID";

Here is the layout of the table:

Image Removed

SERVICEID should be equal to APPLINKID for all links to Jira instances that were created using Atlassian's "Application links" system (the API is designed to support other types of integrations, but we haven't programmed it yet).

Once you've determined what is the old and new "APPLINKID" (as per the table above), proceed to the next steps.

Change AO_32F7CE_AOREQUIREMENT_LINK

This table contains links and relationships between objects, and some of them are the Jira issues. 

Image Removed

In this table, only for records which have an APPLINK equal to the old applink and non-null, please update it to the new applink.

What happens if you recreate an “application link” (“an applink” in our vocabulary)?

• The applinkId will change, just on the side where you recreated it (Jira’s applink in Confluence will have a new ID, but Confluence’s link in Jira can remain the same in some situations),

• We reference this applinkId everywhere in our data, because it uniquely identifies a Jira instance when there are two of them, so it is very important to keep it aligned with the true applinkId,

• In Confluence, all links to Jira issues are identified by { applinkId, issueKey }.

• In Jira, all links to requirements are stored as { applinkId, spaceKey, key, baseline (nullable) }.

• In both software, the queue messages are targetted at one applinkId, so, if this ID changes, you need to update it.

Are you moving data across instances?

The advice below only stands when data remains on the same instance. If you are moving/copying data, for example from a local Confluence to a global Confluence, then please rather look at our backup/restore/import/export tool documented here:

Import/export of Requirement Yogi data to a Confluence or Jira instance.

How can I realign the applinks?

In Confluence, if an applink has changed, we have a wizard:

• Go to Requirement Yogi administration → tab Integations → Click on the invalid applink,

• Click “Fix applink”,

• A wizard will suggest to reassign all records to another ID. You can also entirely delete the records associated to an applink.

In Jira, there is no wizard.

• Go to the database and edit it in SQL,

• Status
  colour Red title warning

  There are risks of data loss when editing data in SQL. Please discuss with your system administrator and ensure you have a way to easily restore data if it is broken.

• Edit the table AO_42D05A_DBREMOTEREQUIREMENT, the column APPLINK, search for all references to the old applinkId and update them to the new applinkId.

• Edit the table AO_42D05A_DBQUEUE, the column APPLINKID, search for all references to the old applinkId and update them to the new applinkId.

• As explained in Database schema, table names might need quotes (backticks, double-quotes or brackets depending on your DBMS).

Example:

-- Simple SQL query to change the target of all links from issues to requirements
UPDATE "AO_42D05A_DBREMOTEREQUIREMENT"
SET "APPLINK" = 'your-new-applinkid76888b66-b3e3-3eb2-bbdc-34d51bd6c884'
WHERE "APPLINK" = 'yourthe-old-applink-applinkiduuid';

Change AO_32F7CE_AOINTEGRATION_QUEUE

You are going to move any message that was initially destined to the old Jira:

UPDATE "AO_32F7CE_AOINTEGRATION_QUEUE" SET "SERVICEID" = 'your-new-applinkid' WHERE "SERVICEID" = 'your-old-applinkid';

Here is the layout of the table:

Image Removed

If you have Requirement Yogi 2.3

If you have RY 2.3.x in Confluence, then you also need to update the table AO_32F7CE_AOISSUETEMPLATE.

;

-- More complex query to update-and-retry all messages in the queue that were destined for Confluence
UPDATE "AO_32F7CE42D05A_AOISSUETEMPLATEDBQUEUE"
SET "APPLINKID" = 'your-new-applinkid' WHERE "APPLINKID76888b66-b3e3-3eb2-bbdc-34d51bd6c884',
"STATUS" = 'yourRETRY', -old-applinkid';

In Jira

Shut down Jira

Same as for Confluence: We recommend shutting down Jira and performing a backup before starting. If you don't, at least disable Requirement Yogi for Jira.

Determine the Applink ID of Confluence

Yes, it is not the same as Jira's applink ID on the other side. However, this is much harder to determine. Please derive information by browsing the data returned by the following query:

SELECT * FROM BANDANA WHERE BANDANAKEY LIKE 'applinks%';

Change Jira's AO_42D05A_REMOTEREQUIREMENT

Our tables in Jira start with AO_42D05A. We keep a storage of requirement definitions that are linked to issues. Here is a structure of the table:

Image Removed

FIrst, you need to determine whether there are requirements duplicated between the two applinks.

SELECT "APPLINK", COUNT(*) FROM "AO_42D05A_REMOTEREQUIREMENT" GROUP BY "APPLINK"

If this request returned results for both the old and new applink, then it will be more difficult. Please do NOT use the next task ("Move requirements") and proceed to the following one ("Manually merge requirements").

Move requirements to the new applink

If the request above didn't return any result for the new applink, then you can just update all requirements to reassign them to the new applink.

UPDATE "AO_42D05A_REMOTEREQUIREMENT" SET "APPLINK" = 'your-new-applinkid' WHERE "APPLINK" = 'your-old-applinkid';

Or manually merge requirements

If (and only if) you have requirements for both the old and new applink, then you have to manually merge them:

• Find duplicates. The "primary key" of this table is APPLINK, SPACEKEY, KEY and BASELINE. If you exclude the APPLINK and have duplicates, then they need to be merged.
• Reassign their children. Find children in the table AO_42D05A_ISSUELINK (REQUIREMENT_ID = AO_42D05A_REMOTEREQUIREMENT.ID) and reassign them to the correct parent requirement,
• Delete the wrong record in AO_42D05A_REMOTEREQUIREMENT.

Restart Jira and Confluence and check your work

• Restart the instances, and check Requirement Yogi is enabled in both instances.
• Check in the Requirement Yogi administration in Confluence, tab "Integrations", that the queue has no error,
• Check you can create a link in Jira to a Confluence requirement,
• Check when you update a requirement, that the text is updated in Jira.

...

- Make it retry
"RETRIES" = NULL, -- Reset the maximum retries
"NEXTRETRY" = NULL -- Remove the waiting time
WHERE "APPLINKID" = 'the-old-applink-uuid'
AND "STATUS" IN ('FAILED', 'RETRY')
;

Where is the database schema documented?

See Database schema.