We’re currently working on a prototype idea for managing automation around runbooks within our organisation. Our runbooks are stored in Confluence as individual pages.
Basically, we want to do some things like:
Send a reminder when its been a certain amount of time since a runbook was last reviewed. We’re not sure what the reminder actually is yet, but something like raising a Jira issue or posting on the page and @ing the person would be appropriate actions
Calculate some sort of indication of runbook “health” using properties available on the page (last activity, last update, last reviewed, usages of the word “TODO” etc)
There is more to it than that, but that is enough to get an idea.
We thought that Forge would be a good solution to this, with the idea being:
Make a macro within Forge that you can include into the runbook. This macro both acts as a form of “enrollment” (i.e. this runbook should get reminders) and as a way to present the health information to the user
Make a scheduled trigger that runs on some sort of interval that checks all of the “enrolled” runbooks to see if they need to have a reminder triggered
First question: Is Forge a good platform to use to implement the above?
We’ve been playing around with it for a while and our lack of skill in both Forge and Javascript aren’t exactly helping, but there are a few things we can’t seem to do, like:
We figured that once a runbook has been “enrolled”, we could iterate through all of the macro instances, grab their config and pull the last review date from that for the purposes of scheduling reminders. We have no idea how to do this. Do we have to iterate through all the pages that meet certain criteria via the Confluence API or is there a shortcut to just find our own app macro instances (and their linked Confluence pages)?
For context, yes I also work at Atlassian, but I figured “why not go through the external developer community to ask our question” because I feel like the answer probably has value from a knowledge base point of view.
Our runbook manager idea is an innovation week project, an opportunity to learn about Forge and to try and solve a problem that we have within the team RE the quality and reliability of our runbooks.
Great question! I would probably not recommend trawling through every Confluence page to check if the page contains the macro. While this would be possible given infinite resources, you may run into issues with time or resource limits.
One possible solution I can think of would be to use the Storage API to store the ID of the page to be reminded of. In your scheduled trigger, you can then use the storage API to get all the page IDs to action.
You may need to do a check in the scheduled trigger for each page to check whether they still include the macro or not (in case it has been deleted from the page).
Welcome to the Atlassian developer community @ToddBowles, even as fellow Atlassian.
I understand why you are asking, “Is Forge a good platform for this case?” But I think that’s a bit of a wrong question. The more fundamental question is, “Is Confluence a good platform for this case?”
Obviously, there is investment in existing content. And, when starting, I can see how Confluence is compelling for authoring runbooks. When you have none, this is the obvious place to start.
However, your new use cases are much more “workflow” oriented. A “review” is work, right? And you’ve already suggested the idea of raising a Jira issue, so I think you see the connection too. The idea of “health” might not be as much human workflow as automation workflow (like scanning a doc for TODO) but similarly isn’t in the “wheelhouse” of Confluence.
As a partner engineer who tries to help fit products together (both Atlassian and external), I think you should first solve for that runbook workflow & health check separately. Maybe Jira with Automation for Jira? Then integrate the parts, potentially with Forge. Otherwise, you are trying to rebuild some deep capabilities on top of Forge, rather than assemble parts.
Of course, ask the integration guy, and out comes the golden hammer of integration.
My suggestion would be to use both Jira and Confluence. You can have your content in Confluence and let it manage that part (which it’s really good at) and then use Jira to manage the work around that (which it’s really good at).
Since this is an internal app (and you don’t need to deal with the marketplace limitations) - Forge can provide the glue for you.
You can have a Forge app that listens for content creation/updates in Confluence - this the. Triggers appropriate creation/updates of Jira issues. The reverse can also be done.
Then you can have a macro on the run book itself (or gasp - a webpanel) that at runtime pulls in the various bits of information on the run book.
I don’t think we’re going to move away from Confluence for runbook storage, but I am curious to know more about how you think Jira Automation can help manage review cycles for our runbooks @ibuchanan.
Speaking of which, when you refer to “deep capabilities” are you talking about workflow management? i.e. transitioning a runbook through a series of states based on user action/inaction with the intent to capture a review flow?
@kchan We actually came up with the storage idea ourselves and it works well enough, but it feels a bit weird. Like there should be an easier way at the API level to find all of the pages that our macro is being used in. We considered the tag idea as well.
I assume the idea here is that when the macro executes (i.e. after its put on the page) we register that page into our internal storage as an “enrolled runbook”, and then during the schedule we iterate through those pages to do things? That’s basically what we did.
@danielwester Raising a Jira ticket to manage the flow of the review is a good idea and something we considered, but just don’t have the skill to implement right now. The idea being that when its time for the review, the scheduler creates a Jira ticket for each page that needs a review, assigns it to the owner and then watches the ticket for state transitions? It sounds workable, but it also requires some sort of configuration saying which Jira project to use for runbook review management, which seems like a bunch of added complexity. Can you do installation specific configuration (i.e. global within a site) or do you need to configure that per runbook? Any recommended links or examples that show the approach that we could read up on?
