Content toolbox for Confluence Cloud
- Jonas Moehringer
We participated in Codegeist 2021, a hackathon hosted by devpost (https://codegeist.devpost.com ). Target was to develop an app in forge, a new development environment for the Atlassian Cloud products.
We submitted an app for Confluence Cloud, called Content toolbox for Confluence Cloud. It is our first Cloud-only app and already released on the Atlassian Marketplace. If you use Confluence Cloud, you can give it a try. We would love to hear your feedback. Just write us an email to info@ij-solutions.com
On this post I want to share the description of our Codegeist submission. It describes what the app does in detail:
Inspiration
If you have a Confluence space with documentation and you want to structure or modify a bunch of pages, it can be annoying to go from page to page to add labels or change text. Especially, if you want to add always the same label, replace the same word, or add something to the title of the pages. Of course you can write some code to do that automatically, e.g. by using an app that can execute scripts or by developing a tool which is doing this from outside Confluence via the REST API. However, you not only need to have system admin permission for most solutions, you also need to have the required skills and knowledge to write scripts and code, which is doing the tasks you want to automate in the right way. Our inspiration was to fill the gap of missing automation tool box for every user in Confluence spaces. Provide small tools which are easy to use and which help Confluence users to automate tasks to structure and modify content.
What it does
Providing a tool box to be used by every user with access to a Confluence space. The tools help to automate
Adding labels
Find&Replace text
Adding pre-/suffix to a page title
on a number of pages at once. The modifications can be made to
All pages in a space
All child pages of a page
Certain selected pages
How we built it
We used the Confluence space page module in forge and UI kit components only. With the app installed a single page is available in each Confluence space, on which the different tools are listed and can be executed by every user with access to the space to pages the user has edit permission on. The space page is structured in tabs, with one tool on each tab. Those tools are
Add label(s)
Find & Replace text in either title, body, or body + title
Add prefix or suffix to page title
For each tool it can be selected whether the change should be made on all pages in that space, all child pages of a page, or only to certain selected pages. The app contains of 4 modules, which are stored in single files:
Index: Contains main app function executed when the page is loaded (3 tool-tabs with forms for each tool)
Core: Functions which are called when the different tools are executed (from index). Contains the all functions which are calling the rest apis for the actual modification of content
Components: Definition of single forge UI kit components like select list or check boxes (e.g. page select list containing all pages in the space). Those components are called from the index file to be displayed on the space page.
Fetchdata: Contains rest apis to get data from Confluence, e.g. get a single page, get all pages in the space The app architecture is also displayed in the image gallery under project media.
Challenges we ran into
The following three challenges were the most difficult ones we faced during development.
We needed to find the right logic for page selection and fetching of page data to be modified by our app. Should the user only be able to select certain pages one-by-one? Should there be a simple way of selection provided, e.g. with “all child pages”, “all pages of space”? How can this be achieved and what conditions are necessary to display/hide the page selections? We finally solved this by using radio buttons to select whether you want to do the modification on all pages of the space, certain selected pages, or all child pages of a selected page. If you don’t select to do this on all pages of the space, another select list appears where the user can choose the pages to be modified.
If we modify the body of a page, what is the right storage format we need to fetch and how can that be modified? It was difficult to find a way to only modify the text and not e.g. macro parameters where the search string is also included. We finally solved that by writing a regex search which is looking for all strings between “<p>” and “</p>” html tags in a storage representation of the pages body. Then, we check if this text contains the search string and replace this string in the body. By this procedure we could assure that only the text is changed and not any macro parameters or something else which shouldn’t be modified.
We do the actual page modification in a different file than the one where we defined how the space page looks like with form, components, etc. It was a challenge to get the final result of the operation displayed correctly on the space page after the user pressed the submit button of the respective form. For adding labels, for instance, we first tried to add the labels in the respective function, then request the new labels on the page, and then return this back to the main app page to be displayed to the user. However, this didn’t work correctly, as the adding of the labels wasn’t completed until the result was returned. So, we always got the page labels before adding of the new labels. Finally, we decided to not request the new labels, but to just display that the operation was successful and to which pages the new label(s) have been added.
Accomplishments that we're proud of
We are proud of having built an app with UI kit in forge that helps all Confluence users to save time for content structuring and modification. To do such tasks manually is time consuming and can be annoying. We found a solution to automate that and thus save users time for concentrating on the actual content they produce in Confluence. By using concurrent requests we were able to achieve editing of multiple pages in a space at once without having to wait minutes until it is completed. As we built the app modular, it can easily be extended in the future. Already during development and especially in the final steps, several additional ideas came up to provide even more “tools” and functionality. The 3 tabs we have currently can easily be extended and also providing such a tool page in the space admin area could be a possibility to also have space admin tools, which might do more complex operations.
What we learned
Forge UI kit is great to built apps for Atlassian cloud products and it can help quickly to solve problems without being too complex. Other than custom UI, our experience was that an app with UI kit can easily and quickly be created, developed, and distributed to users. However, there are also some limitations at some points. Sometimes flexibility is missing regarding what can be set in the UI to display content to the user. As an example, we couldn’t achieve to display text in a different color (e.g. in red for error messages) or we couldn’t achieve to set vertical or horizontal alignment in table cells. At some points, those drawbacks limit the ability to display the content and app menus in the best way for users to be easily understood. The same applies for certain rest APIs or availability of the forge modules and ui kit components. For our app, we got everything we needed and it worked as expected. However, if you need something special for your app to work, which is not available in forge, you are limited regarding functionality. That was also something we learned, that forge is great and you can do a lot with it to built nice apps. On the other hand, it is still not complete and requires further development in some regards.
What's next for Confluence Content Toolbox
As mentioned above, during development additional ideas for small “tools” came up. So, the current functionality of the app, could be extended in the future. This also includes the possibility to not only have a toolbox page for all space users, but also one which is only available to space admins or even to Confluence administrators. Those pages could include the possibility to perform more advanced operations which require extended admin permission. We also want to bring the app to the Marketplace, so it can be tested and used by other Confluence users who are interested to save time when modifications to a bunch of Confluence pages becomes necessary.
Of course, this is very technical stuff. To show you the final result, here are some screenshot which illustrate the apps functionality.
More information can also be found in the documentation for this app: https://ij-solutions.atlassian.net/wiki/spaces/CCT