Setting up write-backs

A write-back is a copy that Roko Platform keeps in another tool, so that people who work there can see the project without opening the platform. The platform calls this publishing. It writes one way: the platform creates and overwrites the copies, and it never reads anything back.

Background

Many organizations track work in Jira or Azure DevOps and keep documentation in Confluence. The platform stays the place where work is decided and changed. Publishing puts a copy of that work where the rest of the organization already looks.

Because the platform reads nothing back, an edit made in the tracker reaches nothing, and the platform overwrites it when the object next changes. Every published ticket and page carries a note that says not to edit it.

A linked tracker does two separate jobs. It lets a change request point at the ticket that asked for it, which works for all three trackers. Publishing is a second, optional job that only Jira and Azure DevOps offer.

What the platform writes

Roko PlatformJira

Goal

EpicGOAL-7 Title

Task

Ticket under the epic[TASK] Title

Change request

Ticket under the epic[CR] CR-57 Title

Each copy also carries:

• Labels: roko-goal, roko-task or roko-cr, and roko-deleted once the object is deleted in the platform.
• A description: the do-not-edit note, a status line, the body and a link to the spec. The platform does not copy the spec itself.
• A status: The platform moves the ticket to the matching status category. Roadmap and Draft map to new, work in progress and in review map to in progress, and Done, Complete and Closed incomplete map to done.
• Remote links to the goal's evidence.

When the platform writes

• On create and update. The platform publishes a goal, task or change request when it is created or changed.
• Not for drafts. A change request in Draft gets no ticket. The platform creates it when the change request moves to review.
• On a schedule. Every 15 minutes, the platform retries tickets that are pending or failed and republishes changed ones.
• Not for existing work. An update never creates a missing ticket. To publish work that existed before you turned publishing on, use Publish all unpublished.

Publish to Jira or Azure DevOps

1. Connect the tracker

   Open the project's Settings page and select the Tickets tab. Under Linked ticketing systems, open the Jira or Azure DevOps card, turn on Use this tracker and enter the connection:

   • Jira: Site URL, Account email and API token.
   • Azure DevOps: Organization and Personal access token. Publishing needs Work Items (write) as well as read.

   Choose This deployment's own identity instead of a token where your deployment supports it. Select Test credential to check the connection.

2. Set the destination

   On the Publish to Jira or Publish to Azure DevOps card, fill in Destination, What Roko creates and Where it lands:

   • Jira: the Project key, the Epic issue type and the Task issue type.
   • Azure DevOps: the Project, the Goal type, Task type and Change request type, and the Area path and Iteration path.

   Select Test connection, then Save destination.

3. Turn publishing on

   Turn on Publish to Jira or Publish to Azure DevOps and confirm with Turn publishing on.

4. Backfill

   Select Publish all unpublished to create tickets for the goals, tasks and change requests that already exist.

5. Check the result

   Select View all N tickets on the publishing card to open the Published in Jira or Published in Azure DevOps page. Each row shows a state: Pending, Live, Deleted there, Marked deleted, Stale or Failed. Use Republish on a row to write it again, or Recreate for a ticket that somebody deleted in the tracker.

Publish the working model to Confluence

1. Open the Confluence section

   On the project's Settings → Tickets page, go to Published copies in Confluence.

2. Enter the destination

   Enter the Parent page URL. The platform reads the site, the space and the parent page from that one URL. Enter the Account email and the API token of the Confluence account.

3. Set the title template

   The Page title template takes the placeholders {client}, {project} and {document}. Confluence requires a unique page title per space, so keep a placeholder that separates projects.

4. Turn it on

   Select Test connection, then turn on Publish this project's Working Model. The platform creates one page per document under the parent page and updates each page whenever its document changes.

Best practices

• Tell the team where edits go. Everybody who reads the tracker should know that changes happen in the platform, and that an edit in the tracker is lost.
• Use a dedicated project or space. A separate Jira project, Azure DevOps area path or Confluence parent page keeps published copies apart from hand-written ones.
• Backfill once, right after you turn publishing on. Later updates do not create missing tickets.
• Check the published tickets page after a change. Failed and Deleted there rows show where the tracker and the platform disagree.
• Grant write access only where you publish. A tracker that you only search and link needs read access.