Whilst Atlassian products are highly configurable and include rich automation capabilities, nothing beats the ability to write code that directly extends or modifies the behaviour. Forge is our latest extensibility framework and is available for use with multiple products including Jira Software, Jira Service management, Confluence and Compass.
This post shares a few ideas about how Forge can be used to customise products to really make them your own. Whilst not exactly recipes, each idea is accompanied by a list of ingredients to get you started.
1. Add a "helper" panel to the Jira issue view
Overview
Sometimes there are a number of rules relating to a type of issue. For example, within Atlassian, we use Jira to record API changelog entries and there are certain business rules relating to workflow transitions, reviews, publish dates, etc. Our Forge changelog helper app checks the details in the issue against these rules and displays a panel summarising any actions, etc.
Ingredients
- Add the Jira issue panel to your Forge app or start with the jira-issue-panel template when creating your app.
- Invoke the GET /rest/api/3/issue/{issueIdOrKey} API to get issue details.
- Add read:jira-work to the Forge app manifest for the above API request.
- If using UI kit, utilise the useProductContext hook to get the ID of the issue being viewed so it can be injected into the API invocation.
- If using UI kit 2 or custom UI, use a resolver to request the issue details. The resolver function can utilise the useProductContext hook to get the ID of the issue being viewed so it can be injected into the API invocation.
2. Create a Confluence macro that displays interactive office floor plans
Overview
Adding interactive floor plans to a Confluence page is useful if you're organising an event or providing instructions relating to a process like picking up parcels. Interactive floor plans APIs exist and can be used to power a pretty cool Confluence macro.
Ingredients
- Optionally create your app with the confluence-macro Custom UI template or otherwise add the macro module to your manifest. Custom UI is recommended in this case given the likelihood of needing specialised UI elements.
- You will likely need to implement macro configuration using the config field. Using macro configuration capitalises on the in built UI and experiences and will be the simplest way to configure which floor plan to show and other options.
- Optionally use tooling and an API to help manage floor plans.
- If the floor plan API requires an API key, you can store this in a secure environment variable.
- Add external permissions if using a floor plan API from an external resource.
3. Add an insightful comment to newly created issues
Overview
Whilst Jira's built in automation feature allows a project administrator to set up a rule to automatically add a comment to newly created issues, a limited range of conditions are supported and the comment text is static. Forge apps can overcome both of these limitations with ease.
Ingredients
- Use a product trigger to listen for issue created events, avi:jira:created:issue.
- Use the event payload to access details about the issue such as its summary and description.
- Optionally make API call(s) to other systems in order to implement your business logic.
- Invoke the POST /rest/api/3/issue/{issueIdOrKey}/comment API to add the comment, using api.asApp() since api.asUser() can not be used in a product trigger context.
- Add read:jira-work to the Forge app manifest in order to listen to the issue created events.
- Add write:jira-work to the Forge app manifest in order to add an issue comment.
- Add external permissions if your business logic results in external APIs being invoked.
4. Prevent workflow transitions unless an external condition is met
Overview
Let's say you have a Jira project that you use to track employee onboarding. Each issue corresponds to a new employee, and perhaps the onboarding can't complete without the individual attending a training course. With this example, a custom Forge app could check that the training course has been attended before allowing the issue to transition to Onboarded.
Ingredients
- Optionally create your app with the jira-workflow-validator template or otherwise add the jira:workflowValidator module to your manifest.
- Implement the business logic to validate the transition.
- Add external permissions if your workflow validation business logic results in external APIs being invoked.
5. Add a busy message to the JSM portal header
Overview
Most of us are probably familiar with call centres warning us about response times due to higher than normal call volumes. With Forge, it's simple do mimic this by way of the addition of a panel to the Jira Service Management portal header.
Ingredients
- Add a jiraServiceManagement:portalHeader module to the app manifest.
- Invoke the GET /rest/servicedeskapi/servicedesk API to get the service desks and build a CSV string of the JSM project keys enclosed by double quotation marks.
- Invoke the GET /rest/api/3/search API with JQL statusCategory != Done AND project in (${projectKeys})` and use the total value in the response to determine how many open requests exist.
- If the total requests exceeds a threshold, present your message.
- Add the following permissions to the Forge app manifest:
- read:servicedesk-request
- read:servicedesk:jira-service-management
- read:jira-work
- manage:servicedesk-customer
6. Capture and manage specialised data with Jira
Overview
Jira can be used to capture and manage specialised data such as job candidates, business rules or project risks. Custom fields can be used to store additional types of information such as a job candidates location, a business rule category or a risk mitigation rich text field. Apps can also customise the Jira Software issue creation form to show and hide fields, make fields mandatory or optional, set field values, change field names and descriptions, etc.
Ingredients
- Optionally create your app with the jira-custom-field-ui-kit template or otherwise add the jira:customField module to your manifest for each specialised field you require.
- Get familiar with or fork the forge-ui-modificiations-example app.
- Add the jira:uiModifications module to your Forge app manifest.
- Invoke the UI modifications APIs to tailor the issue creation form.
7. Display charts showing operational data for compass components
Overview
If you use compass to manage information relating to the components of your system, you could create a Forge app to display reports relating to each component. For example, let's say a set of components identified microservices, then it would be useful to be able to display operational charts such as CPU and network usage in the context of other microservice information surfaced by Compass.
Ingredients
- Optionally create your app with the compass-component-page Custom UI template or otherwise add the compass:componentPage module to your manifest. Custom UI is recommended in this case given the likelihood of needing specialised UI elements.
- Use the extension context to get the componentId for the component being viewed.
- Use the component API to get component details.
- Use the component details to surface reports to display.
- If necessary, invoke external APIs to retrieve data to be displayed.
- Use a Javascript charting API to ender the data in chart form.
- Add external permissions to your Forge app manifest if external APIs need to be called.
8. Snapshot data at a regular interval
Overview
This idea works for most products, but the gist is to capture data at a regular interval and store it for reporting or audit purposes. For example, let's say one or more of your Jira projects has a field identifying if an SLA has been exceeded, then you could write a JQL query to identify all issues that exceed violate the SLA. The GET /rest/api/3/search API can be invoked with the JQL and the total value in the response will identify the number of matching issues. This can be invoked on a daily basis using the scheduled trigger API and the number of issues could be recorded such that you have an account of the number of SLA violations over time.
Ingredients
- Optionally create your app with the scheduled-trigger template or otherwise add the scheduledTrigger module to your manifest.
- On each invocation of the scheduled trigger, compute the data to be stored. You will likely need to query one or more APIs to do this. If a significant number of API calls is required, you may need to use the async events API to spread the invocations over multiple Forge functions, passing context from one to another.
- Store the snapshot data using the Forge Storage API.
- Clean up older historical data to avoid exceeding quotas.
- Add the storage:app permission to your Forge app manifest.
9. Integrate Jira issues and Confluence pages to manage decisions
Overview
Let's say you have business processes that require decisions to be managed in a rigorous manner, and in particular, ensuring decisions have the appropriate sign-off. Jira is great for defining workflows whilst Confluence is great for collaborating on documents. Jira and Confluence work well together out of the box, but you can go beyond this with a cross product Forge app. In this case, lets say you want to collaborate on the decision in a Confluence page, but have a Jira issue to get the necessary sign-off. It's not hard to create a Forge app that listens to issues created in a particular project and then automatically creates a Confluence page conforming to a particular template, including a macro that renders issue details. For example, the process starts by creating a Jira issue in the DECISION project, and then filling out the linked decision page that was automatically created by the Forge app. The Forge app can also enforce your company's decision business logic such as rendering warnings and/or sending notifications when the decision is overdue..
Ingredients
- Read the blog post on building a cross-product Forge app for Jira and Confluence since it explains how to go about this in meticulous detail.
- Consider using the DACI decision making framework and its Confluence template.
- Optionally create your app with the product-trigger template or otherwise add the trigger module to your manifest.
- Add the read:jira-work and write:page:confluence scope permissions to your manifest.
- After deciding on the format of your decision pages, retrieve the page using the API so you can copy the storage format version of the page into the app (refer to the Create the addPage() function section of the blog for more details).
- Wire up your app logic to listen to Jira page creation events and call the Confluence REST API to create the new page with your template.
10. Add changelog history to components in Compass
Overview
Whilst Compass has integrations with code repository software like Bitbucket that can should low level change information, it's also useful to have higher level change information at hand. Depending on your microservices architecture and API capabilities of your changelog solution, it may be possible to automatically inject changelog data that specifically relates to each component and the dependencies of the component. If something goes wrong, this change history may help to quickly identify the cause.
Ingredients
- Optionally create your app with the compass-data-provider template or otherwise add the compass:dataProvider module to your manifest.
- Add external permissions to your Forge app manifest in order to have the correct permission to retrieve changelog information.
- Use the Fetch API to retrieve changelog information.
- External Authentication should may or may not be required depending on whether the changelog information access is open or restricted.
More ideas
If you've go a problem to solve, but are not sure how feasible a solution is, you may like to visit the Atlassian Marketplace to see if other apps are solving similar problems. Your best starting point would be to look at the categories in the left side bar to narrow down the range of apps to the particular problem area of interest to you. If there are apps in the Marketplace solving the problem, then chances are that it can be done, but you should be aware that some apps are built on frameworks other that have been around longer than Forge and there may be some differences in capabilities. If you see an app listing that has a Descriptor link in the Resources section on the lower right, then it is built with the Connect framework. The Connect descriptor is the equivalent of the Forge manifest as it details various aspects about the features the apps uses. You can use the Connect module equivalents guide to identify how to translate capabilities of a Connect app to Forge.
Where to from here?
Visit the Forge developer documentation and start building an app and if you have any questions, post a topic in the Atlassian Developer Community.