Changing Applinks

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,

  • 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" = '76888b66-b3e3-3eb2-bbdc-34d51bd6c884' WHERE "APPLINK" = 'the-old-applink-uuid' ; -- More complex query to update-and-retry all messages in the queue that were destined for Confluence UPDATE "AO_42D05A_DBQUEUE" SET "APPLINKID" = '76888b66-b3e3-3eb2-bbdc-34d51bd6c884', "STATUS" = 'RETRY', -- 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.