Reporting in Jira | ACP-420 Jira Service Projects Study Session

This week we dug into Reporting in Jira Service Management. One important thing to remember is that “reports” refer to a specific thing in Jira Service Management - the Reporting tab in your project. This tab includes a number of default reports, as well as the ability to add some custom reports. Personally I haven’t used the Reporting feature too much, however, it is an important tool in our toolkit.

If you’re looking to take the ACP-420 reporting takes up 7% of the exam… so while it is important to understand, if you’re short on time you may want to focus on other areas! That said, reporting (including JQL and dashboards) is one tool I use on (almost) a daily basis, so while this is only a small part of the exam, it is a huge part of my day-to-day life.

Reports

Jira Service Management comes with a number of out-of-the-box reports to help teams improve how they operate. On a practical level every team needs to keep an eye on their metrics, as these help identify potential areas of improvement, ensure team members can see what’s going on and suggest area that the team is doing well in. 

In terms of access only Project Admins can configure or modify reports. Agents can view them, but can’t configure, and customers and collaborators cannot even see the reports. Keep this in mind when you try to share something, as only Agents and Admins will be able to view them!

While it isn’t covered in the course, there are limitations to the built-in reports. For example, they’re only able to pull the last 365 days worth of data. This makes it challenging to perform long-term analysis of trends (e.g. how did December 2023, 2024 and 2025 compare?). There are also limitations in what information can be pulled into reports, so it is not uncommong for groups to begin using them, and then get very frustrated when they realize there’s a use case they cannot solve.

Also not related to the exam but there are multiple add-ons to help provide additional reporting for teams. If you’re working with a group that needs something more, it’s definitely worth checking out the marketplace for addons. Also also, while it is non-ideal, you can always export Jira data into a spreadsheet and analyze it there. I try to avoid this as it removes data from the system (instantly making it stale), but in a pinch this can work.

Filters & JQL

While Reports are a specific feature, Jira also has two other tools that will help you analyze what’s going on, filters and dashboards. We’ll start with filters as these define a set of work items that can be analyzed in a dashboard, and are something I use on a very regular basis.

Filters are exactly what they sounds like - they’re a way to filter down all the tickets in Jira to find the ones you want. I found it helps to think of Jira as a (really really) big spreadsheet. When I apply a filter in Jira, it’s the same when I filter a column in my spreadsheet. For example, filtering for just the JAYQUILL project will only show tickets in the JAYQUILL project. I can then apply additional filters until I get just the tickets I want.

Generally filters can use any field available in Jira. This lets you do things like make lists of tickets that are about to violate a specific SLA, create reports on tickets from specific teams, or determine which specific users put in the most tickets by region of the globe.

There are two main types of filters:

1. Basic Filters - Basic filters let you use drop downs to determine what fields and what values you are looking for. While this is reliatlvely simple, it is incredibly powerful as it lets you quickly isolate lists of issues you’re looking for.

2. Advanced Filters - Advanced filters rely on Jira Query Language (JQL, pronounced “Jayquill”) to filter down tickets. If you’re familiar with things like SQL you’ll have a basic idea of what JQL does, but it is drastically different. Personally I mainly use JQL to find tickets (mostly by habit), but there are some things that JQL does that Basic Filters cannot, so there are use-cases where you’ll need JQL. 

---

Want to lear more about JQL? Check out my online learning course! 2+ hours of info on how to find things in Jira!

---

In the past the ACP-420 had more in-depth questions related to JQL, however, the recent refresh (in April of 2025) resulted in many of the JQL questions being dropped in favor of other questions related to configuring Jira Service Management for customers and agents. That said, JQL is a very useful skill to have and one you’ll find yourself using on a (very) regular basis.

Once you’ve created a filter you have the option to save and share it. Be sure to give it a good name when you save it, as typically this is the only way to figure out what that filter does (and the only info someone looking at the filter has in terms of it’s function). By default filters are not shared with anyone - this is a major source of frustration as team members will make filters and fail to share them. This will result in an error message if someone else tries to use it.

The fix is simple - just share it with an individual, group, project or your entire org. This step, however, is frequently missed, so it’s something I always double check!

Dashboards

Dashboards are Jira’s built-in data visualization capability. On their own they don’t do anything, however, you can add gadgets to them to help visualize or analyze underlying filters. Gadgets take a filter (or entire projects worth of work items) and visualizes them. Common examples include:

1. Issues Statistics - A simple chart showing what % of work items fall into the various values in a field (e.g. priority)

2. Two dimensional issue statistics - A more complex chart showing how work items break down over two dimensions (e.g. assignee and work item type).

3. Created vs. Resolved - A chart showing how many tickets are created and resolved over some time period you designate.

While there are some built-in data sources (e.g. selecting an entire project) I find it much more useful to first build out filters that define what information the dashboard will show. This does take some time, however, it helps ensure that the dashboards I build only include the specific work items I need to analyze.

Like filters, Dashboards are private by default. THis means you have to manually share them with individuals or groups after you save this. You can also end up in a sticky situation where you share the dashboard properly, but not the underlying filters. THis will result in someone seeing a dashboard, but not seeing any data in it (and is a very common issue!).

Check out our full session below!

Introduction to Jira Software | ACA-900 Study Session

Our study sessions for ACA-900 Jira Software Essentials are underway! This certification is intended for folks who use Jira Software on a daily basis. This includes folks like software developers, project managers, scrum masters, analysts and more. It also explicitly excludes anything an admin needs to worry about and focuses just on what regular users need.

Why study for the ACA-900 Jira Software Essentials?

There’s a few reasons you may want to study for this exam (but there can be others!).

1. Rounding your skills - Personally this is why I study for certifications. Typically i know how to use a tool, but only in ways that I happen to need to use it. This means I miss out on a lot of knowledge about how the tool works, what it can help me do and use cases. Studying for certifications helps me round out my skills and better understand what my tool can do.

2. Prove your skills - Earning a certification is one way to prove your skills to others. You may want to do this to get a new job, or signal to your current employer that you know something specific (like how to use Jira). Holding a certification means you’ve passed a bar in that area, and can be an important stepping stone in your career.

3. Curiosity - Sometimes folks are just curious! They want to learn how something works, not to earn a piece of paper, but just because they want to learn.

Our study sessions will prepare you to earn the ACA-900 exam, but if you choose not to take it that’s ok too! You’ll still learn a lot (and hopefully have some fun at the same time).

Roles

A major use case for JIra software is to support agile project teams as they develop a product. Agile teams have a few main roles that we need to understand so we can best use the tool. An important thing to remember is that these roles may be used differently by various organizations. For the purposes of the certification we’ll use these roles and examples, but be aware it can differ in real life!

Also note that these roles may or may not exist in Jira - however - they are important to understand as they help define what people will be doing in Jira (including things like permissions and tools they need).

1. Product owner - This individual is responsible for the backlog, and for ensuring the development team is aware of priorities. They don’t do the work, but instead tee up what’s next.

2. Developers - These are the folks who do the work (e.g. write the code). Typically this is a team of 5-7 folks, and they are responsible for things like estimating relative complexity, accomplishing their work and sharing it with customers.

3. Customers - These are the people who will use the end product. Outside of sitting in on regular demos they don’t take a very active role as they are mainly represented by the product owner.

4. Scrum master - This is an individual who is trained in agile methodology and acts as a coach for the team. They won’t (or shouldn’t!) be involved in daily work, but instead help the team understand how to apply agile tools and techniques to accomplish their goal.

What is Jira?

Before we get into how to use Jira we need to understand what it is. Jira is a work management tool made by Atlassian. It can do a lot more than support agile teams, but for the ACA-900 this is our main focus. It is available in two main types - Data Center (DC) and Cloud. Here, we’ll be talking about Cloud, but the lessons we learn are applicable to both types.

Cloud is further broken into different tiers - Free, Standard, Premium and Enterprise. Essentially the higher the tier, the higher the cost - but you get more features. The biggest differences between them is the availability of AI tools at Premium and less restrictions on things like automations.

The biggest unit of Jira is the instance - basically a copy (check out this video to get a free one to play in!). Every instance is different from every other instance, and requires a license to access.

Within an instance will be some number of projects. Projects are essentially containers that let you more easily organize work. They might be created for specific teams, or projects, or any other grouping.

Work Items are put within projects and represent things you need to do (note these used to be called “Issues”). Work items can represent almost anything, from scheduling a vacation flight to writing complex code to grocery shopping.

What is the ACA-900 exam?

The exam is up to 30 questions about Jira Software, and requires 72% or higher to pass (21 or more questions correct). You get 60 minutes to take the exam, which gives you two minutes per question. Some questions will take longer, others shorter, but two minutes is a good amount of time to answer them (and a great reminder to pace yourself!).

The certification is also valid for 24 months (although there are ways to renew it!). Check out more about the ACA-900 certification here

So what’s next?

Now that we understand some underlying and basic concepts and ideas it’s time to get hands on! Next up is Navigation (16% of the exam) where we’ll cover topics like how the Jira interface is laid out, where various menus are and keyboard shortcuts.

Also check out the ACA-900 Study page where I’ll be centralizing all the info I can find on the ACA-900 (including things like flash cards to help you study).

Automations | ACP-420 Jira Service Projects

After a one week hiatus for Team25 down in Anaheim (more on that on Thursday!) we’re back with some ACP-420 studying, this time focusing on Automations. Automations exist in a number of Atlassian products (Jira, Jira Service Management, Jira Product Discovery and Confluence) and allow the system to take action for us.

Personally I use automations very frequently in Jira Service Management. Most commonly I use them to assign tickets to agents via a “load balancing” assignment rule. This helps ensure that when a new ticket comes in it gets assigned to the agent with the most bandwidth (e.g. least number of tickets). I also use them extensively in Confluence to generate new pages on a regular basis, assign labels and identify content that is stale.

These, however, are by no means the only things Automations can do for us. Other examples include creating Jira tickets when a Confluence page is published, generating sub-tasks at the push of a button, calling webhooks, changing the work item status and more. 

Before we begin

The best way to learn about automations is to go play with them. Every tier of Jira Service Management Cloud allows for automations (although the lower the tier the less automation runs you get per month). Make some time (right now!) to go open Jira and explore what automations have to offer. This will give you a good understanding of what’s in there, and what is possible.

You’ll also be able to browse automation templates. These are a great starting point for uncovering what is possible, and also a great starting point if you’re not quite sure how to get something off the ground.

It can also be hard to figure out what to automate. I start this process by thinking through what I do (or what my team does) on a daily basis, and identifying things that are repetitive and clearly defined. Once I have a list of these I sit down and ask myself which one is the biggest (or most annoying) and see about automating it.

When you’re working with a team be sure to get feedback from them on what should be automated, and what is worth automating. Getting more perspective at this stage is incredibly important, as the team will have a better view of what is a time waste than just one person. It can also have the great side effect of getting folks interested in finding more things to automate. I’ve seen groups go from “we don’t know it exists” to saving loads of time simply by having some engagement around automations.

Automation Scope

Automations have two main scopes - Global and Project.

Global automations can be created by Product admins and allow the automation to run across an instance, or across a specific list of projects. In my mind this is similar to how schemes let projects share configurations and allow Product admins to automate tasks across projects. This is incredibly useful when you have a number of projects that do something similar - for example every new engineering project has a separate Jira project, or you have multiple customer service teams. When you go this route just be sure to let folks know there are global automations! If folks aren’t aware they’re running (or what they do) you’ll get a lot of very confused questions about why things are changing.

Project automations are scoped to a single project and can be created by either Product or Project admins. Most of the time people will be making a project admin as this is their level of access. It’s important to remember these can only impact a single project. If you have the need for an automation to run across projects you’ll need to work with a Product admin to make a global automation. Project scoped automations allow individual teams to determine what they need to do without impacting other groups. This gives you the ability to tailor how the automations work to fit your unique needs.

Anatomy of an Automation

There are two required parts to an Automation - triggers and actions, as well as two other optional components - conditions and branches.

Triggers - Triggers are what tell Jira to run the automation and are required for every automation.  Common examples include a manual trigger (e.g. someone clicks a button), when an issue is created and via a schedule. There are, however, many other triggers! Triggers can also fire when something happens in github, a task is reopened and more.

Conditions - Conditions let you control when an automation should continue and are optional. For example you may have a condition that the automation should only proceed if a specific user is assigned to the ticket. Conditions also allow for “if/then” logic, which lets you have different outcomes for a single automation depending on different information. For example you could assign a ticket to one user if it comes from a specific country, and to another user if it comes from a different country.

Branches - Branches are optional and allow an automation to run against multiple work items that meet some criteria. For example you could have a branch that runs against every ticket that meets specific JQL criteria, or run against every ticket that has a specific Epic as a parent. I commonly use branching to update child work items with a single click.

Action - Actions are required and are what the automation does. Actions include things like changing the value of a field on the work item, moving a ticket through a status and many others. Typically actions are what people think of when they think of an automation as they do something in the system. 

Audit Logs

Every time an automation runs Jira records it in the audit log. This is an incredibly useful tool as it records every time an automation is triggered. This lets admins chase down bugs or other problems in the automation. They can be a bit bare at first, so I typically recommend folks include a step in their automation that adds to the log. This helps ensure useful information is begin recorded (or at least information the admin can follow up on later to see what has happened).

Other Items

In addition to its scope and setup, automations offer some other options we need to be aware of.

Run as - By default automations will show up in logs as “Automations for Jira”. You can, however, change this on an automation-by-automation basis. For example you could have it run as the person who triggers it, or another user (or even a service account). Keep in mind this is what appears in the work item history, so be careful about selecting a person as this could be confusing when reviewing logins!

Failure notification - from time to time an automation can fail. In this case Jira will send an email to someone (by default whoever creates it) letting them know about the failure. This is a very useful notification, but you can, however, change who receives it. 

Who Can Edit - You can control who has the ability to edit a specific rule. This is useful if you want to ensure the rule is accidentally (or otherwise!) changed.

Check to allow - By default automations will not trigger automations. This is a safety mechanism to ensure automations don’t run wild… you can, however, check this box to allow automations to “chain” - or trigger others. This can be useful in cases where you want to automate longer processes or concepts.

Additional Information

There is some additional information we should know about automations.

Step limits - Automations are limited to 65 steps (any combination of triggers, conditions, branches or actions). While I’ve personally never run into this particular limit, I can easily see more complex/sophisticated automations pushing this limit. This requires admins to sit down and determine what is really needed, or what can be broken out into different automations.

Run limits - Except for Enterprise every tier of Jira Service Management cloud has a limit to the number of times an automation can run. See this link for the current limitations, but these are important to keep in mind (Especially if you’re on Standard or Free!).

Time - Jira evaluates automations as they meet their trigger condition. This means that if you have a lot of automations that trigger on issue creation it can take a while for them to run. This can make things frustrating as automations may seem to be delayed - when in reality Jira is just checking to see what it should do. I you notice significant delays go check the audit log to see how long things are taking and see if you can remove or adjust things to speed it up.

Parting Thoughts

Automations are something I need to take a deeper look at, mainly because I’m sure there’s more I can be automating. Many groups I work with, however, don’t use them at all either because they don’t know what they can do, or they don’t know automations exist. I find this to be a massive loss for those groups as there is a lot of work we (as humans) don’t need to do!

Make time to get familiar with automations and you’ll be surprised at what you can do (and what you don’t have to do any more).

Team25 Wrap Up

Team 25 is in the bag! It was a great 4ish days of Atlassian stuff, but for me it wasn't the swag, or the keynotes or the F1 cars that was the bar part it was the people.

The people

I got to meet at least a dozen folks I only know from a screen name or an email. I met another dozen I never met before anywhere, but had seen some of my videos or took one of my courses. This was a wonderful reminder to me that we the impact we have on others is always broader than we think, and that it’s possible to build connections even with a limited medium like chat or youtube.

Some of the people I met were during the live Confluence Challenge put on by Aura. I had a lot of fun participating in this challenge (even if I didn’t win!) and it was a great reminder that we all can learn more - even about topics people call us “expert” in.

More AI

With the announcement of Rovo being included in premium and enterprise we can expect a lot more ai in our lives. I'm really happy to hear this since up until now I haven't been able to use Rovo due to the cost. I've already got (more than) a few ideas about how I can leverage it to speed up my teams and their ability to find information.

Less silos

With the introduction of more AI, and more data sources, we can expect to see less silos dividing teams. This is something I struggle with, so seeing more tools that will help break down those walls is great. I'm especially curious to see how Loom can fit into this as it's a tool I currently use frequently to build out how-tos and other documentation. Being able to do a recording, and then have Rovo figure out the step by step documents will be a huge time saver. 

I’m curious to see Rovo in action - especially around the knowledge discovery areas. I currently find myself using at least a half-dozen systems every day, meaning any one of them can have info I need about something. Using a tool like Rovo to more easily traverse them and find that knowledge will be immensely beneficial (and time saving!).

Cloudy Skies Ahead

One announcement from the keynote was the introduction of two new cloud versions - government and isolated. The first is intended for government groups and reflects Atlassians recent FedRAMP designation. This is essential to work with government agencies, so will unlock a lot of folks.  The isolated cloud is exactly that -  a company-specific cloud. This means groups can get additional security by being separate from the regular cloud (someone jokingly called this DC in the cloud). This will solve a lot of headaches for folks who need more isolation, but currently can't get it

Teamwork makes the dream work

Atlassian will begin offering the Teamwork Collection - which includes Jira, Confluence, Loom and Rovo (I believe it will be $15/month per person). Typically I see groups using Jira and Confluence, so adding Loom and Rovo is a great step forward. Loom allows groups to more easily record and share video/screens, while Rovo will help break silos by letting folks more easily find information and create Agents to help them automate tasks.

Bringing these all together is a great step as many groups already use some comination of these, and as a group they work well together. I’m personally curious to seeing how groups adopt Loom and Rovo. I’ve used Loom quite a bit and really like how easy it is to share information (although Rovo is new to me….).

Strategy Collection

Most people think of Atlassian’s products as being more tactical. Jira, for example, is mainly concerned with organizing work in the next week or two. Confluence is about capturing and sharing knowledge. This can make it challenging to get an overall look and where things are headed, and where teams need to make changes to shift to a specific target.

The strategy collection looks to help fill that gap. It includes three products that help groups get a grasp of their strategic plan and what they need to line up to get it done. The entire package is also being made available to existing Align customers for free.

Align let's groups more easily plan work across teams and see what projects and tickets are floating around. For smaller groups this may not be needed as the folks planning are aware of what’s going on, but as groups get bigger (and work gets more complex) having a single place to see all the threads - and adjust them - is critical to keep things on track.

Focus is Atlassians’ goals planning app and let's groups set goals and then align work to those goals (similar to OKRs). I haven’t personally used this product, but I can see how large organizations would benefit from being able to set a top-down direction that work ties into. Personally I find it incredibly challenging to meaningfully move the needle when I don’t have that direction, so very curious to see how other groups use it.

Talent is a new offering that helps groups determine what skills they need to accomplish their goals but also what gaps they'll have. For example if they're planning a large release in six months, talent can help them identify what team members they need, or who needs training to hit that target. I find this to be an interesting addition to Atlassian as up until now they’ve mainly been focused on the work (e.g work items, OKRs, code). This represents a shift into the things that make the work possible (the people) , which makes me curious to see where they’ll keep moving into.

This overall package feels like a bit of a shift, or maybe the recognition that the strategic level needs some love.

Community –Leaders– Champions

The Atlassian Community had some updates as well. The biggest - well, at least to some of us - is that “Community Leaders” are now being called “Champions”. This is a good shift, as it also represents an expansion in what a Champion does. Up until now we’ve mostly been involved (to some degree) in creating and hosting events. A new type of Champion is emerging, one that is an internal advocate within their company. I’m excited to see how this evolves the group as it will be more inclusive of folks who are engaged, but don’t want to host events.

We also learned more about the change of “Atlassian University” to “Atlassian Learning”. I like the name change as it feels more approachable, but the big news for me was about their Learning Management System. Instead of taking an off-the-shelf solution, Atlassian decided to build their own entirely from scratch. To me this is incredible as it ensures it will meet the specific needs of folks using it, but also demonstrates an immense amount of investment in the Learning community. (I can’t think of any other company putting this amount of resource into their Learning experience). It’s definitely worth checking out, and they’ve got some other interesting updates coming to it in the future.

Swag

Ok , the swag was fun! I did manage to get away mostly with stickers (mainly because I only brought a single bag!). I did notice a lot of vendors had socks this year… which is terrible (at least for me)! I’ve just declared “sock bankruptcy” and replaced all my mismatched socks with about 20 pairs of identical socks… this way I never have to worry about mismatches.

Final Thoughts

Overall team was an amazing (if exhausting) experience. It helped build loads of new connections, shared some amazing news and brought everyone together. If you weren’t able to make it to team this year I’ll encourage you to check out the following resources, and I hope to see you there next time!

• My content - I’ve got some recorded content from team 

• Official live streams - Atlassian streamed some of the bigger talks, worth checking out

• Local ACE events - Your local Atlassian Community chapter may have some events you can attend

TEAM25 Day 0

Team25 technically begins on Tuesday with Day 1… however, Community Champions (more on them later) begin on Monday - Day 0. This day is used to give the Champions time to connect with each other (many of us know each other only from the internet, so in person time is incredibly important and to learn about changes and improvements to the Champions and Community programs - and there’s a lot!

No More Community Leaders

One of the bigger announcements (at least to the Champions!) is that the group is no longer called Community Leaders, Creators, SMEs, etc… we’re now collectively called Atlassian Champions. Personally I really like this update as it better describes what we are and what we do. Before it was hard to tell which group we fell into and how they’re different. For example I began as a Creator, but them also became a Community Leader… which was odd, since I don’t lead a Community in the same way someone who sets up live events does.

This doesn’t impact most folks who use Atlassian products, but will have a big impact on the overall community as the Champions are the ones who help drive adoption, raise issues, host other sessions and more.

No More Atlassian University

Atlassian University has been rebranded as Atlassian Learning. Selfishly this is one more thing I”ll mis-name as time goes on (looking at you “Work Items”), but on the whole I like this update as well. The term “university” has a certain connotation and weight to it… you only go to University after years and years of school, plus Universities can be rather expensive. Calling it “Learning” better positions it to be accessible by more people (98.97% of folks with access to Atlassian products are NOT admins of any kind), which will lead to more folks leveraging it

Another thing I learned about this update is Atlassian invested in building out it’s own learning platform to host their content. I really like the new UI and features (although it did disrupt my live learning since I had to learn the new platform on the fly…..). I find it particularly impressive, however, because it means Atlassian is truly committed to making Atlassian Learning successful. They could have relied on an off-the-shelf solution, but instead dedicated time, money and resources to make a high-grade experience for folks… and it’s free!

No More Multiple Accounts

Atlassian Community has had a… major annoyance… for years - your account was tied to your email and couldn’t (easily) be transferred. This resulted in folks having multiple accounts as they change jobs. For example, there’s at least 3 different “Robs” floating around out there… Not only was this annoying since you had a new log in, it meant all your articles, questions, badges, kudos, etc all got lost when you had a new account.

Up until now the best way to solve this was to use a personal email account instead of a work account. Now, however, Community has made accounts portable! Once you change jobs (or get a new email) you’ll be able to transfer your account to that email. This means your articles, badges, etc. will move with you as your shift jobs.

Day 0 Done!

There’s been a lot of great info from Day 0 - but day starts today! Be on the lookout for more content, including live learning opportunities that I’ll have, to stay up to date!

Advanced Topics - Final ACA-920 Study Session

We made it! This session was the last in our 5 series arc for the ACA-920! Here we covered some more advanced topics within Confluence, and also spoke a bit about register for, and taking, the exam.

Task Report Macro

In addition to serving as a knowledge base and place to keep information, Confluence allows for task tracking. Tasks take the form of checkboxes you can insert onto pages (either via a macro /action item, typing in [] then adding a space or clicking the checkbox icon in the toolbar). These tasks can be placed anywhere, and if you @ mention someone in them you’ll assign them to that person. You can also add a date (typing in // then a space) to put a due date on it.

Personally I use tasks as an in-the-moment way to record to-do items. I find this to be better than having to switch to Jira (or some other app), make whatever ticket I need, and then go back to Confluence. Instead I can use [] to easily add the task, fill it out, and keep taking my notes or leading the meeting. This does, however, lead to tasks that I lose track of.

Enter the Task Report Macro. This macro gathers tasks from an indicated space (along with some other filters, like label, assignee and status). This gives you a great way to instantly create dynamic lists of tasks (even across spaces). I use this to quickly make task lists for my team, although I will convert bigger ones into Jira tickets if it’s approprite.

Additionally you can return to your home page and click on the “tasks” menu to see all tasks you’ve created, or are assigned to you. This, however, doesn’t let you change the assignee (it’s personal!).

Attachments Macro

Confluence pages support various kinds of attachments including links, documents, files, videos and images. This can quickly get out of hand (especially for longer pages), so we have the Attachments Macro to help us see what’s on the page. Personally I don’t use this all that much (my pages tend to be a bit macro-free) - however, it can help you figure out what attachments are on a page.

Additional Content

We also spoke about two additional types of content we might run into:

1. Whiteboards - Whiteboards are a way to visually collaborate in Confluence. They’re similar to Vision, LucidChart and Miro and allow teams to collaborate on a digital whiteboard. Personally I find these very useful, as unlikely other tools they are natively embedded in Confluence. This means anyone with a license can use them and place them in context with other information (unlike other tools where I may be the only license holder in my org). Whiteboards also are integrated with Jira, making it easy to represent tickets and do things like sprint planning from directly within Confluence.

2. Databases - Databases provide a way to structure information. To me they’re in between a table and a Jira project in terms of functionality. Commonly I use them for lightweight project planning (typically done in a spreadsheet), but also for organizing Confluence space restrcutures. Check out this video for more information on them.

The Exam

While you don’t have to take the exam, it can be a great thing to help validate your skills and round out your resume. If you choose to take it, here’s some tips:

1. Practice! - Get hands on in Confluence and practice making pages, playing with restrictions, archiving things and the like. Nothing beats real experience in terms of understanding things.

2. Review - Take time to review the ACA-920 recordings, official training and more. This will help cover any gaps in your knowledge.

3. Sign up - Once you’re ready you’ll need to sign up and pay $100 to register. You should check if your company covers exam fees - you might be able to get reimbursed.

4. Take the exam - You’ll have two options - at home and in a center. Taking the test at home can be a pain as you need a “clean” environment with no distractions.. plus their software can bug out. That said, it can be easier than trying to find a testing center near you. Going to a testing center can be easier though, since you’ll just walk in, register and get started. Both options a proctored (someone is watching to make sure you don’t cheat), but if you go to a center you can take bathroom breaks…

Interacting with Pages - ACA-920 Confluence Essentials

Up until now we've mainly covered the different ways we can create and edit pages. This makes a lot of sense as this is the main thing folks do in confluence (create things!). There is, however, another part to this which is how we manage those pages.

Drafts

We started going over drafts. These are the bane of my existence, as I frequently make a new page and entirely forget about it... This means the page sits, in draft mode, forever. This wouldn't be such a big deal, expect it means I'm the only one who sees it (Org admins can come in and see them, but this is typically an extraordinary measure). The result is my content hierarchy is littered with pages that are in draft mode. Most of them will be fairly blank or not useful, but I’ve lost track of the useful pages I’ve just forgotten to publish.

The fix is easy - just publish the page! Once that's done, it's live and folks can see it. The only exception is sharing the edit link with someone else to collaborative edit the draft.

Presenter Mode

One feature I don't use much is presenter mode. Found in the more actions menu or via the “R” key when you’re viewing a page. All this does is this will change the display to something thats easier to present to others. While this doesn’t seem like much, it does make it a lot easier to share your content with a group (or in a meeting). It also lets you create a QR code for individuals to scan so they can follow along on their phone. Typically I find myself just sharing my screen with the page up, but presenter mode does a much better job of formatting and displaying things for viewers.

It also has a number of options for more easily navigating the page with arrow keys, or skipping to specific sections that you want to dig into - both things that are harder in the regular view or edit mores.

Page Preview

You can also preview your page before you publish changes. This is available in the more actions menu, or via or CMD/Ctrl+shift+E. This lets you see what it looks like, and gives you a chance to change things before you commit to them. I use this fairly frequently as I want to see how macros and other formatting look on the page. Another way you could do this is just to publish the page - however - this will result in the page history updating to include that new “version”. This can quickly clutter things up and make it harder to keep track of whats the “real” version vs. something you were just playing around with.

Page History

One feature I do use very frequently is the ability to view a pages version history. Confluence keeps track of EVERY change to a page,.meaning you can, at any time (as long as you have the edit permission) see every change ever made to a page. You can even compare two different versions, and restore old ones if you need to. 

Typically I find myself using this to see what’s changed since I last viewed a page (although if you have Atlassian Intelligence you’ll have the ability to compare drafts via AI, which does the heavy lifting for you!). That said I do find myself restoring older versions fairly frequently as I realized I’ve made a mistake or need to roll back something.

One thing to be aware of is that you can delete entries in the version history (check out the note below for why this may be an issue). Personally I don’t find many uses for this - other than removing older versions of policies to ensure folks can’t track the changes, or removing “extra” versions I’ve accidentally added by publishing a page too early. If you delete a version it’s gone forever, and the number will update to reflect that (e.g. if I delete v3 above, the current version will become version 3).

Note - Page history is usually not robust enough to meet specific audit requirements (e.g. versions can be deleted), so if you’re looking for a way to maintain audit history or become compliant with various frameworks you may need a specific add one that helps.

Knowledge Bases and Workflows - ACP-420 Study Session

This week we covered two, very different, topics! 

Knowledge Bases

First we went over how to connect confluence to Jira. Connecting a knowledge base helps us support agents and customers. Customers will be served help desk articles as they put in tickets - this can result in them not needing to enter a ticket (called deflection), which allows agents to focus on more challenging requests. Agents, on the other hand, get in-Jira access to help Articles to solve tickets. This shortens the distance they need to go in order to get answers, and makes them more effective.

An important thing to keep in mind when linking confluence is it will only be as useful as the information in confluence. This means that if your information isn't organized, or is missing, it won't be very helpful!

Project admins can control which space(s) are linked, as well as which request types will be allowed to use articles. You can optionally filter content by label - for example only allowing article with “google-account” to appear under “Google account help” requests. Once it’s setup, articles will be displayed to customers as they enter tickets, allowing them to self-serve and preventing the need for a ticket entirely.

Once confluence is linked agents can also do things like categorize and label them, but also add new articles (assuming access is setup properly). Personally I find this to be incredibly helpful as agents will constantly be finding out new things that should be documented, and having a way to quickly add that to your KB is critical. Giving agents the ability to organize content as they see fit is also very useful as they may have slightly different needs or perspectives than other groups. Each space can categorize and label articles, allowing each group to decide how to best organize things. Agents also have the ability to search for articles directly from a ticket - this makes it much easier to use as they don’t have to dig around in menus and can instead quickly find what they need.

Workflows

Workflows are the series of stages a work item moves through in Jira. They represent the status of any given work item - for example “in progress”, “blocked” or “pending approval”. They're comprised of a few things, but before we dig into those we need to consider how they differ between team and company managed projects.

Team Managed Workflows

Team managed project admins can edit their workflows at any time, and the workflow is tied to a request type - not to an issue type This means they can't be shared across projects, but on the plus side it means admins can easily adjust things.  Team managed projects do have some limitations (like no transition screens), but otherwise function similarly to company managed projects.

Company Managed Workflows

Company managed projects have their workflows tied to workflow schemes. These allow Jira admins to define a workflow across multiple projects, easily allowing them to scale operations and manage things. This means company managed project admins can't change their workflows, however, it does mean that it is much easier to manage workflows across an organization.

Company workflows also have some more options and features that are not available to team-managed projects.

Workflow Parts

• Status - this is the status of the work item. They can be broken into three basic categories - to do, in progress and done. Note that status indicates where in the workflow something is - not how it is completed. Instead company managed projects have a resolution, which describes how the ticket was resolved. Resolutions are. A global setting and typical examples include won't do, done and duplicate.

• Transitions - transitions are how issues move between statuses. A global transition allows any issue to move to a particular status, but more commonly custom transitions are used to control the flow of work. For example you ight not allow a ticket to move from open to done, instead it first must be in in progress. 

• Conditions - Conditions let you have specific criteria that must be met before a transition can be used. For example a specific person must have approved it, or a specific field is filled in.

• Triggers - Automatically transition work items based on events - e.g. code commit it bit bucket.

• Validatiors - validators can be used to ensure work items meet specific criteria before they're transitioned. For example you could require specific fields are filled in, or specific users are triggering the transition. These gives teams additional ways to enforce how tickets move, although they can be frustrating if teams don't know they're there.

• Post Functions - post functions do something after the work item transitions. For example they can be used to clear the resolution when a ticket is reopened.

• Properties - Properties allow more in-depth configuration of your workflow. They support other features and let you do things like restrict what someone can do in a specific status, or which resolutions are available.

We didn't get through all the workflow material, but we'll pick right back up with it during our next session after TEAM25 on April 14th!

📄 Advanced Editing | ACA-920 Confluence Essentials Session #3

Last week we covered the basics of editing - including things like making pages and how to use the editing functions… now it’s time to get a bit deeper into what options are available for us when we edit pages.

Atlassian Intelligence (AI)

AI is available in Cloud Premium and Enterprise and offers some interesting tools to help us edit our content. At its most basic AI can help us generate ideas or create things like outlines. Personally I find this useful for helping get past writer’s block as it can help redirect my thoughts or help me get over being stuck. AI can also change the tone of what we’ve written, which can be helpful if our audience changes (or if we can’t get the tone quite right).

There are, however, more interesting use cases for AI that I’ve found. One is its ability to summarize content. Instead of having to read an entire page, you can have the tool simply summarize it for you. This is great for longer pieces of content, or, more commonly, when I’ve found something right before a call and I don’t have time to read everything. Summarize also works on recent changes - something I find to be very useful. Some pages change very frequently, so having the tool just summarizes what’s new since I last viewed it helps me stay on track and understand what’s changes.

Another useful tool is the ability to define terms and acronyms. At first I didn’t think I would use this all that much, but I’ve found it to be one of the better features… especially if I’m new to a team or unfamiliar with how they operate. (New joiners also find this very useful!). It helps us understand what these terms mean, and also gives us context for why the tool thinks that is the definition in the form of links and references (to help rule out hallucinations.

Macros

Our next stop in the advanced editing section was on Macros. These are essentially small programs or extensions that give us more functionality in Confluence. This can be a basic thing, like adding a coloured panel to a page, or a more complex thing, like mirroring content across multiple spaces. Macros are available either from the “+” menu in the edit toolbar, or by typing in “/” when editing (my preferred method).

There are many, many, macros, so we didn’t talk about all of them, but there were some favorites:

1. Table of Contents - dynamically builds a linked table of contents based on headers. One that I use on almost every single page I build as it makes it much easier to find things.

2. Excerpt - defines an area of the page that can be pulled into other pages. Allows you to mirror content - something I use frequently for “background” information that can be pulled into an index.

3. Expand - Puts a collapsible section on the page that can show, or hide, information in it. Helpful for breaking up the page and managing what’s visible.

4. Panels - Adds a panel to the page that includes colours. Useful for visually calling attention to something (like a warning).

5. Labels list - Displays a list of all the labels in a specified space. Helpful for managing labels (particularly identifying near duplicates).

I am working on a series of youtube videos that break down the common macros - so stay tuned for something that is (hopefully!) fun!

Restrictions

We finished out our advanced session by talking about Restrictions. This is probably the most confusing part of Confluence for most folks, so taking time to understand them is important! The ability to add a restriction to a page is a Space-level permission. This means your space admin can allow, or prevent, you from adding them (so if you don’t see them, chat with a space admin!). 

There are three types of restrictions:

1. Everyone can view and edit - Anyone who has view access to the space can see this page, and anyone with edit access for pages can edit it. This is the default, and most permissive, permission.

2. Everyone can view, only some can edit - Anyone with view access to the space can view it, but only people specified in the restriction can edit the page. This is fairly common as sometimes only specific people (e.g. experts or certain folks) should be able to change things.

3. Only some can view or edit - The most restrictive. This hides the content from anyone who isn’t on the “view” list, and prevents editing unless you’re on the “edit list.

There are two considerations we have to keep in mind that commonly trip folks up (and given their importance are very likely going to show up on the exam if you take it!)

1. View permissions inherit down to children - This means if Page A has a child, and I restrict View access on Page A, it’s child will also be restricted.

2. Edit permissions do not inherit down to children - This means if I can edit Page A, it doesn’t necessarily mean I can edit it’s children.

Check out the recording below - and hope to see you in the next session!

🧵Atlassian Loom for Beginners

Despite chrome constantly crashing I had a great time showing folks that he basics of Loom. I find it a great tool for recording audio, video screen shares and screenshots, and even better it integrates natively with confluence and Jira - two tools I love in constantly.

The App(s)

Loom has two apps - a chrome extension and a desktop app (both downloadable here). My Loom journey began using the chrome extension, which is a great, lightweight way to record Looms (Looming?) and save them to your library (what Loom calls your storage). Of course this only works/makes sense if you happen to use Chrome, but if you do it’s a great way to quickly begin Looming (on second thought maybe I’ll call it weaving?). Clicking the Loom icon immediately opens up the recording panel where you can decide how you’d like to record. You can optionally include your screen, video and audio, letting you record the range from silent screen recordings to fully A/V walkthroughs of something.

Recently, however, I’ve started working with the desktop app, which is a bit beefier in terms of size, but offers more features(namely recording and screenshots via hotkeys, drawing on screen and capturing mouse clicks). The additional features have made it more attractive (especially the hotkeys and capturing mouse clicks) as they speed up by workflow and make it easier to clearly indicate what I intend to share.

Library

Once recorded Looms (what I'll call a screenshot or recording from. Loom) are stored in your Library. This is basically cloud storage that you can organize to easily keep track of Looks, but also let's to easily share and collaborate. Collaboration takes the form of comments, @ mentioning and shared-editing (more on editing below). Comments can be dropped on an overall Loom, or at specific timestamps (something I find really useful when I need to point out a specific question or clarification).

In addition to your Library you can also add Spaces to Loom. These function similarly to a Confluence space and let you organize content by whatever grouping you like (team, department, product, etc). Spaces can be public or “closed”. Everyone in your workspace can see all open spaces, but have to be invited in to see closed spaces. This lets teams keep sensitive information private, while being able to easily share with those who need it.

Editing

Once recorded Looms can also be edited in the cloud - either by you or shared editors - making it very easy to quickly create content. Other solutions I use will provide either recording or editing, so having both in one spot, and an easy to use interface, is a great win.

Editing can be as simple as cutting a few seconds of lead, or removing and replacing sections with other videos. You can also easily add shapes, texts and call outs to the video - as well as a button linked to a page or other content.  With the premium tiers you'll also have access to some AI tools to help remove pauses and/or filler words (although personally I haven't used these).

Integrations

Loom is made by Atlassian, the same company that is responsible for Jira and Confluence, and their main focus is on helping teams work better, together. This is expressed in Loom by having native integrations with Jira and Confluence, letting you instantly start recordings from Jira tickets or Confluence pages. I’ve found this to be a really useful (and time saving) feature as I can create recordings in the moment I’m thinking about them vs. having to wait and figure it out later.

Pricing

As of writing Loom has a free tier which allows you to have up to 50 people in the same workspace. They’re limited to 25 total videos, but it’s a great way for smaller teams to quickly share visual information. As you go up in tiers you get access to more storage, editing and AI tools. Personally I haven’t used the AI too much so I’m unsure if it’s worth the cost, however, the editing features do make the premium tiers very useful.

Final Thoughts

Loom is a great, lightweight way to quickly record information and share it (even on the free plans). The premium features, like editing,make it worth the investment (especially if you use other Atlassian products). It’s definitely worth checking it out!

If you’re looking for a more in-depth look check out the video below:

Configuring Fields in Company & Team Projects | ACP-420 Jira Service Projects Study Session #7

This week we continued our exploration of configuration, focusing on issues/work items and request Types, and this is another area that project admins will have a split experience in. 

Team-Managed Projects

Team managed project admins can do basically anything they want in terms of issue type setup (note that technically there are only request Types in team managed). This is good for smaller teams, or in cases where a project is a one-off. Not having to go through a Jira admin and modify schemes (or add new ones) is a massive time-saver, and also frees up the Jira admins to handle bigger, more complex challenges. That said, it’s also a bad thing, as you might quickly end up with multiple team-managed projects floating around that all require administration… and due to how they work there’s no single way to manage them all.

Team managed project admins can, however, add new request Types at any time. This gives them a ton of flexibility to quickly spin up new request types on demand. They can also make any changes they want to the fields and workflow (well dig into these next week) they want to. This includes recording fields as displayed to the agent (the issue view) and the customer (request view). Company-managed project admins can do this as well, however, it is important to note that these are spread across different tabs (“Request Form” and “issue view”) in company-managed projects, but they’re on a single screen in a team-managed project.

Company-Managed Projects

Company managed project admins are much more limited in terms of what they can change. They can manage request types (including making new ones), but can't make new issue types, add fields, change screens or modify workflows. Also, any request type they create has to be linked to an underlying issue-type that’s available to the project (via the issue type scheme). This, in turn, limits the available fields to what’s connected to those issues types. This makes them entirely dependent on a Jira admin to help with updates. (Although they can't make these changes, understanding what is needed is very helpful as it makes it easier to file a request and work with a Jira admin to make those changes).

Company managed project admins can, however, control what fields are displayed on the request (as long as they're available on the underlying issues). They can also change the display name (what a customer sees) to make the experience a bit easier. They can also change the display name of workflow statuses, which seems like a small thing, but can have a bit impact on someone's experience.

Next week well pick up with emailed requests and then dig into knowledge bases and workflow setup!  After that there's a week break for TEAM25 (if you're going let me know, I'd love to connect there!).

Pages and Basic Editing - ACA-920 Confluence Essentials

Pages are the basic building block of Confluence and what many of us think of when we think of Confluence. They’re basically Word or Google docs and allow us to create a wide range of information that we can easily share with users.

Page Creation

An important thing to remember is that pages are created under whichever page you have open. This means if you make a page while you’re viewing the home page, it will get dropped at the bottom of the Hierarchy under the home page. If you make a page under one called “design” it will automatically become a child of Design.

This confused me for years…

And is why I don’t like that “+Create” button that’s at the top of everything! I find it much too easy to forget where I’m at and make a page under some random bit of content. That said, it does create the page. My preferred method is to use the “+” buttons in the Hierarchy as I know exactly where the new page is going (under the page I clicked the “+” next to.

Pages can be created in a few ways, but most commonly folks use the “Create+” button that’s clearly visible at the top of Confluence (and basically impossible to lose!). Personally this isn’t my favourite way of creating pages - mostly because when I started using Confluence I started using the “+” button in the Content Hierarchy… but also because it can be easy to “lose” a page when you create it this way.

Child Pages

A great feature of pages is they can be nested under other pages. This allows you to quickly organize content visually, making it much easier for folks to browse through what you’ve created. For example, you can nest all the “Policies” under the “Policy” page. This makes it easier for content creation (since folks know where to put something) and content consumers (since they can find stuff). There’s no known upper limit to the number of layers, but best practice is to limit this to no more than 4 levels to keep things manageable.

Editing Options

After you create a page you’ll see the editing menu, which includes a number of features to help you make content. One important thing to note is that you cannot change the font or text size! Instead, you can change the Text Style - mainly to various headers. I initially found it annoying that you can’t change fonts or sizes, however, it does simplify things (no more “serif” or “sans-serif” arguments!). Headers also serve an important function - they act as links on the page. This lets you easily hyperlink a specific header to someone, or, even better, connect it to various macros (we’ll dig into them more in a future session).

There are some other text options, like bold, italics, strikethrough and color that you can access, along with building lists and indents. The final section (“The good stuff”) contains options for things like adding hyperlinks (you can just CMD+V over text if you’ve copied a link to hyperlink it), insert images and attachments, and include things like layouts and emojis.

Templates

Templates are pre-formatted pages that make it much easier to quickly create (and consume!) content. Confluence comes preloaded with 140+, but Space Admins can also add and edit these to fit your specific needs. I highly recommend you review what templates you have, and then work with your Space Admin to modify as needed.

You can also search through templates, or easily browse with the categories - something I never knew!

Atlassian Intelligence

Atlassian Intelligence (or AI… see what they did there?) is included in Cloud Premium and higher and offers a number of different options to use AI to help improve writing and summarize pages. Personally I mainly use it to summarize things since I’m (sometimes) too lazy to read, but it does offer some great built-in options to leverage AI to speed things ups.

Wrap Up

Our next session is March 28th at 6 AM PDT and covers Advanced Editing- I look forward to seeing you there, and check out the recording from this session below!

Fields, Screens and Schemes - Oh My! ACP-420 Jira Service Projects #6

Schemes! I definitely tripped over my own tongue with this one... Issue type screen scheme is way too hard to say.

Beyond not being able to say them properly I personally find them incredibly confusing! Mainly this is because I have been a Jira admin before... This means my hands on skills are lacking. I picked up small amount here's and there as I worked with the Jira admins though, and event that little bit was incredibly useful. Even just understanding that schemes are a thing is helpful as it makes it easier to talk to someone else about updating the system.

That said, this means is I need to dedicate more time to studying this part of the exam than I do for others (check out the new acp-420 page for some things I'm doing to drill this in). I’ll also be spending some time mapping out how all these schemes relate to each other. I find that visually drawing things helps my mind keep them separate.

Schemes and Fields, Oh My!

Schemes, however, are very important for us to understand as they are the shared configurations in Jira. They allow us as admins to create specific settings and then apply them across projects. For example all of our support projects could share the same issue types, workflows, screens and fields. Then, when we need to update them we just update it nice and it applies everywhere.

Fields, while not a scheme, are where a lot of this starts. After all, when I think of Jira I immediately think of all the information I need to fill out. One thing to remember is that fields aren't directly applied to projects or issue types. Instead they're grouped into screens. These screens are then added to a screen scheme which can be applied across projects.

There’s also two flavours of fields:

1. System Fields - these are default in Jira and tend to be critical. Things like Summary, Description and Key fall into this bucket

2. Custom fields - These are fields you create

Most of the settings we’ll cover here show up under “Issues” under the Settings menu:

Schemes for projects

There's seven total schemes that impact projects, with issue type security schemes being optional.  Each of these let us control different aspects of the project.

• Notification Schemes

  Notification schemes allow you to define what notifications are sent out when and to who.

• Priority Schemes

  Priority schemes allow projects to have a different list of priorities. While this doesn’t seem like much it can have a huge impact on end users!

  Personally I find a lot of folks frustrated at having to use the same list of priorities as everyone else (it also tends to get long… and repetitive…). This scheme lets you break out different lists of priorities for different projects.

  It also applies to Team-managed projects!

• Screen Scheme

  These allow you to associate screens with an issue operation (e.g. view/edit/create). Basically they tell Jira which screen to use for those actions.

  For example, you might have one specific screen displayed when creating bugs, but a different one available when editing bugs.

• Permission Scheme

  This defines what permissions are provided to what individuals, groups or roles in a project. Setting this up helps ensure that similar projects get similar permissions, making a project admin’s job a lot easier.

  While the project admin can’t directly edit permissions they can assign roles, so ensure this is setup to support them!

• Issue Type Scheme

  This scheme defines the issue types available to a project.

  For example your Project Management projects could have Epic/Story/Subtask while your Support projects get Bug/Incident/Request.

• Field Configuration Scheme

  This scheme connects your field configurations (how a specific field behaves, e.g. hidden, required etc) to a specific issue type.

  For example the “priority” field could be hidden on Bug tickets by default, but displayed on Project tickets.

Schemes for Issues

Three schemes apply directly to issues. These allow us to control things like the workflow specific issue types fulfill.

• Field Configuration Scheme

  This scheme ties fields you’ve created to specific issue types. For example, you may have a “Symptom” field. In order to make it available to an issue you first have to add it to a Field Config scheme, and then tie that scheme to the issue type.

• Workflow Scheme

  This scheme controls the workflow a given issue type uses. For example, the Bug issue type may have a specific set of statuses it moves through, while the Story issue type has a completely different set.

  This workflow allows you to standardize the flow of specific issue types across projects.

• Issue Type Screen Scheme

  While the Screen Scheme associates screens with operations, the Issue Type Screen scheme associates them with issue types.

  For example you might have a Screen Scheme that contains specific fields for “Create” and then apply that to specific issue types via an Issue Type Screen Scheme. A different Issue Type Screen Scheme could apply different “Create” screens to other issue types.

But what about Project Admins?

Jira admins don't get to have all the fun though. Project admins can control the request screens by adding, removing, and managing fields that appear on request Types with is issue layout. This allows each project to choose what order fields are displayed in, what name is display to the customer and some other options. Giving this local control to project admins makes it much easier for them to handle day to day requests to improve their project.. although they still need to work with a Jira admin to add fields, change workflows and the like.

Each screen scheme gets one layout (which the project admin can manage) per project (something we need to keep in mind as Jira admins!). Project admins will be able to modify the “view” screen by adding, removing and reordering existing fields (but they can’t create new ones). Project admins can also hide empty fields, which can help clean things up for teams that don’t need every field in their project.

There is an important note in Atlassian’s training “Project admins can only add fields that exist in their project’s View screen configuration. If they remove a field from the issue layout, the field still exists in the View screen configuration. It just isn’t visible for that particular project.”

FAQ

1. What is a good way to name my schemes?

   1. It can get confusing quickly! There’s some different ways, but folks typcially rename the default to something like . Project key - type — example : ABC-SS for the ABC project Screen Scheme

2. How do I change priorities??

   1. There is a Priority Scheme that allows you to change priorities based on the scheme used.

3. What is the new name for “issue”?

   1. Work item… although I bet I’ll still call it “issue” for a while…
      

Permissions and Roles | ACP-420 Jira Service Projects

Aren't time changes fun? Apologies to the folks who missed any/all of session 5 due to the time change... Luckily we have about 6 months before we get to do it again! (recording below if you missed out!)

Session 5 dug into permissions and roles. Personally I have to handle questions related to these topics on a weekly (sometimes daily) basis, so they are close to my heart. This also takes up 14% of the exam (but feels like half of my day sometimes!).

Check out the info below for more about what we covered, including the FAQ that folks had.

• Before you start!

  Before we get into how they work, you'll want to consider why you need them. It's very easy to dig in and start building roles or schemes. Resist the urge! Instead, step back and talk to your team and stakeholders about what is needed. I start by understanding the types of people who will be using Jira. Examples include agents, auditors, managers and the like. This is essentially building your list of roles, which will be useful when you start building.

  Once you understand the groups you can determine what they need to do. For example, some groups may need the ability to respond to customers, while others should only be able to view tickets. This mapping process can feel arduous, but is an important step in understanding your teams needs.

  This can take a while, but at the end you'll have a blueprint of what you'll go build. This makes it much much easier since all you'll have to do is push the right buttons - all the hard part (the thinking) is already done.

• Permissions

  Permissions are layered, like an onion! On a day-to-day basis I regularly only interact with these at the Project level, however, as admins we need to understand what falls into each layer, and be ready to troubleshoot issues that can span levels.

  • Organization - At the top is the organization level. This layer control things like the ability to @mention, or access the instance.

  • Product - Next comes the product - e.g. Jira service management. This level mainly allows you to manage who can use the product in your org.

  • Project - Next is project level. This is where most folks will have access as it allows you to be a project admin. Here you can control things like roles, customer access and the like.

  • Issue - The last level is the issue layer. Typically I don't see this level being used as it adds more complexity and most of the time you don't need to lock issues. That said for environments with sensitive data (e.g. hr, finance etc) locking issues is important.

  While there aren't 'gotcha' type questions on Atlassian exams, we do need to be careful and understand nuances to access. For example, 'assignable' and 'assignee' are both required permissions to be assigned a ticket (the first allows you to be assigned to a ticket, the second allows you to assign a ticket). Nuances like that are important for the exam, but also as a an admin to support our teams.

  Some nuances we should keep in mind include:

  1. Jira Admins are determined by who has access to the “jira-admins-(sitename)” group, or assigning a user to the Jira Admin product admin role

  2. “browse users and groups” lets people @ mention users, select users from picker fields, share issues and see names. It does not prevent folks from assigning issues (I ran into this at work recently!)

  3. “Browse projects” is the most important permission (according to Atlassian! :D) as it determines who can see a project and issues… without it you can’t see anything, regardless of your other permissions.

  4. In order to edit due dates and rank issues you need both schedule issues AND Edit issues

  5. Service project agents only applies if you’re in JSM

  6. Some perms can be disabled globally like liking, watching and voting.

• Roles

  I think of roles as types of people that work in Jira. There are four roles that come with Jira, and we can't remove them - admin, agent, collaborator and customer.

  Confusingly team and company managed projects have different names for them…for example 'agent' in team managed and 'service desk member' in company managed.

  That said each role contains the appropriate permissions for those types of people. Agents, for example, can open and edit tickets. Collaborators can open, and post internal comments, but not edit.  As an admin in a team managed project you can edit roles, but jna team.managed project you can't (unless you happen to be a Jira admin too).

  We aren't, however, stuck with just the roles were given. We can create new ones. This may require a Jira admin, but once they're created project admins can assign them to people, which indirectly allows project admins to control permissions. These roles can be incredible useful in meeting needs of your team, which makes understanding what they need to do and why even more important.

Next week we'll get into, looking forward to seeing you there!

FAQs 

1. Why are roles name differently in Team and Company managed projects?

   1. I have no idea! It is a bit confusing though…

2. How can project admins manage permissions in Company-managed projects?

   1. They can indirectly manage permissions by assigning Roles. This is where it’s important to have a good relationship with your Jira admin so they can partner with you to build Roles that make sense for your team.

3. Why is “schedule issues” necessary to re-order issues on a backlog board?

   1. This is a great example of a non-intuitive thing we have to just know. From what I understand it has something to do with how Jira stores rank order information… does it make sense? not really… Do we need to know this to help folks? yup.

Check out the session recording here

Services, SLAs, and Permissions - ACP-420 Jira Service Projects study session #4

Study session 4 is in the books! We covered three topics (detailed below), and will pickup with permissions next week since we ran out of time.

Next Week (Session #5)

IMPORTANT - Daylight savings ends (or begins? Not 100% sure how this works) this weekend. Please double check the time as it may shift by an hour.

Session #5 will pickup where #4 left off with permissions. Then we’ll get into:

1. Roles

2. Adding agents and customers

3. Team-managed permissions

4. Issue types, fields, screens in Company-Managed projects

What did we cover

• Features

  Project admins are able to turn on/off individual features within a Jira service management project. For example, if your group doesn’t use Services, just click the rocker to disable it. This has a number of benefits, but mainly it won’t clutter up your screen and it won’t confuse users with things they don’t need.

  That said, it can be frustrating if something is missing and you don’t know why!

• Services

  Services are things your team provides or supports. Some examples include databases, APIs and servers. Services can be grouped into Tiers, with Tier 1 being the most critical, and Tier 4 being least critical (e.g. folks won’t realize it’s offline). Services can also be linked to other services, for example, your website may depend on an API to work.

  Adding services to Jira service management lets your team more easily manage them as they can easily see what services there are, what tickets impact which ones, and how they relate.

  For example if the website is offline, you can easily see it is dependent on a specific server, and what issues impact that server.

• Service Level Agreements (SLAs)

  Service Level Agreements (SLAs) are agreements teams with with h customer groups on how quickly something is addressed. For example you might agree an account reset should be done inside two hours, or a server outage will be worked on continuously until it's solved.

  Jira service management allows us to define any number of SLAs, each of which can have different goals and different time targets. The tickets impacted by any given SLA can be defined by JQL, which means basically any grouping of ticket can be targeted. Within that you can break down specific time targets (how long someone has to meet the goal).

  SLAs also contain conditions, or rules when they start, pause and stop running. Typically SLAs begin when a ticket is created, however, this can be tied to some actions (assignment, comment, etc). Pausing an SLA is useful when the team is blocked (commonly info this when I'm waiting for the customer to reply). Stopping an SLA typically happens when a ticket is closed, but could also happen when a specific status is met or action taken.

  Finally, SLAs have calendars, which tell it which day(s) and time (s) to be counting down and a group can have any number of calendars. For example your 'account' tickets may use a 9-5 calendar while your 'outage' tickets may use a 24/7 calendar.

  Regardless of your initial setup I highly recommend making time on a regular basis (e.g. quarterly) to review SLAs and ensure they still meet your needs.

• Permissions

  We didn't get all the way through permissions but I'd highly recommend spending extra time here. Not only do I think it will show up on the exam, it's a common problem I run into in 'the wild', so the more we understand about how permissions work, the easier we can make others lives.

  There's 4 levels of permission, org, product, project and issue.

  • Org - access to your orgs entire instance. Allows control of things like admin, @mentioning and others.

  • Product - ability to control access to a product (e.g. Jira service management)

  • Project - ability to manage and control a project. This is typically the highest level of access I've had and allows things like modifying request types, changing rules, and managing SLAs. 

  • Issue - it is possible to restrict access to issues. Typically I prefer not to do this as it complicates things, but it can be necessary (e.g. for HR tickets).

Study tip

Keep Jira up on another screen or yab and switch into it to practice as you study. This will help cement ideas and remember things better. 

FAQ

1. Do services have to be linked to a physical thing?

   1. No! Services can be a physical thing, like a server, but are also typically non-physical things like API, websites etc.

2.     What is camel case?

   1. A way to notate fields and other information without spaces. (many systems don't allow spaces in names). Typically the first letter is lower case, and the letters of new words are upper. Examples:

   2. jiraServiceManagement

   3. pronounceJQLLikeJayquill (ok, that ones silly)

3.    Can SLA's be tied to Issuetypes or just Request types?
   

   1. Either! SLA's can be tied to any filter you can describe with JQL - so you can define a JQL query to pull tickets by either request, or issue, type... or almost anything else.

4. Can you use Atlassian Intelligence to build SLAs?

   1. Not yet :(

5. Can we prepare ourselves in just a month for the exam?

   1. In general I wouldn't recommend it as there can be a lot to learn! That said, if you can dedicate a lot of time to studying, practicing and understanding this can be possible. Personally I like to take 2-3 months to prep, but others can go faster.

6.  Why am I limited to a single workflow per request type?

   1. On a technical level I believe Atlassian limited this to ensure tickets know which path to follow.

   2. On a process level this makes also makes sense as any give type of request should follow the same workflow - e.g. under what circumstance would a "password reset" require an entirely different set of statuses? If it does, it's likely a different request.

Project Type Showdown, Request Types and Queues : ACP-420 Study Session #3

ACP-420 session three is in the books (embedded at the bottom of this page too)! We picked up right where we left off with team vs company managed projects, and got through setting up queues (more specifics on those topics below).

Study Tip

If you're in my sessions have a Jira service management instance up and follow along live. This will let you see the concept, but also uncover questions you may have and ask them live.

Topics

• Team vs Company Managed Projects

  These two project types certainly bring up conversation!  While both offer the ability to collect and manage tickets , they differ quite a bit on the management side.

  Team managed projects let the project admin adjust almost everything. You can add request Types, change workflows, add fields and more. This gives smaller, less technical, teams a lot of flexibility.

  Company managed project, on the other hand, have a wider array of features, but limit what a project admin can do. You can still make request Types, but can't modify workflows, fields, screens, notifications or access. This is because company managed projects use schemas, or shared configurations.  Schemes let an orgnaization share configurations across projects, vastly simplifying administration.

  There is some debate about whether groups should ever use team managed projects (ill dig more into this in a future blog post), but for the ACP-420 we are expected to know the differences.

• Request Types

  Request Types are customer facing forms that let customers out in tickets. Project admins can set them up and modify them as needed, including things like hiding fields, grouping in the portal and having more customer friendly field names.

  • In a company managed project these are all tied to an issue type, which provides the workflow for the request type.

  • In a team managed project there is no issue type, so each request type has its own workflow, fields and more.

• Queues

  If request Types are how customers enter tickets, queues are (one of) the main ways agents interact with them. Queues are essentially saved searches that project admins manage to guide agents on which tickets should be solved.

  Agents can select queues to view, but only project admins can edit queues. This means that we, as admins, need to take time and effort to craft queues that best support our teams. Admins can do things like

  * Define the tickets in the queue - this is done via Jira search (basic or jql) and can be refined at any time

  * Define what columns are displayed and in what order - this allows admins to tailor what information is easily access access

  Queues can be grouped into 'priority queues', basically groupings project admins select. This helps further guide agents by helping them work in one spot and not having to jump around between parts of Jira.

Questions

1. Why would anyone use a Team Managed project?

   1. It gives teams more local control of their project and removes reliance on a Jira admin (something many company's don't have, or have in limited supply).

2. Why would someone NOT use a team-managed project?

   1. Eventually many teams outgrow a team-managed project or need more support so they need to be converted. This takes time and effort, which can be avoided if you just start in a Company-managed project.

3. What is a “Jira-ism”?

   1. Anything that makes you hang your head in disappointment over decisions Atlassian makes that common sense would tell you could have been implemented in a much better way

4. Where can I get a recording of the sessions?

   1. Here!

5. When I go into Project Settings why does “request type” not appear?

   1. Request types only exist in Service projects, so you’re likely in a Business or Software project if you don’t see Request tyeps

6. What is a PICNIC?

   1. Problem In Chair, Not In Computer

   2. (Note - this won’t be on the exam!)

7. Why would I hide a request type from the portal?

   1. I do this to let my agents enter specific types of tickets but not customers, for example “hardware request” could be something only agents can enter after they think new hardware is needed.

8. Why should I bother changing the request type icon?

   1. The icon helps differentiate request types and makes the customer experience a bit better

   2. It also makes it easier for agents and admins to differentiate tickets easily

ACP-420 Jira Service Projects Study Session #2 Notes

Big News

It looks like the ACP-420 certification is getting a makeover. This is good news, since it means the content will be fresh and relate to new features... but also has a few implications for us. The biggest one is we won't be able to sit the exam until after April 15th (meaning my goal of passing by April 1st isn't possible!). While this could be frustrating, it does give us more time to prepare - especially since new content will likely be included.

Topics Covered

We got through most of the topics I hoped to. Below is a synopsis of what we covered (all in my own words - definitely review the great free training in the University!).

Check out the full recording here

Core Features

1. Issue types have their own workflow, and can have many request types

2. Request types are customer-facing and are associated with one, and only one, issue type

3. Workflows are the series of stages an issue type has, including transitions between them

4. Queues are saved views of tickets that agents (people who work on tickets) use to keep track of what to work on next

5. SLA's (Service Level Agreements) are time limits on tickets. These help agents prioritize tickets based on how much time is left.

Incident vs Problem

This concept appeared a few times, and is an important concept to understand in general (they’re also something I get mixed up quite a bit!).

• Incident - something that happened. e.g. I see an error message, a website doesn’t work, etc. I also think of this as being the smoke a fire creates.

• Problem - the underlying thing that caused the incident(s). e.g. a server was unplugged, there’s a bug in the code, etc. If the incident is the smoke, this is the fire.

Understand the different is important as we handle them differently. Personally I tend to see incidents well before problems - after all there’s a lot of users out there, so they tend to notice things first (although this isn’t always true!).

Use Cases

There are a number of different use cases for Jira Service Management. Honestly I’m not sure these will take up a lot of space on the exam, but definitely good to keep in mind as I bet some (or all?) may show up in your career!

Here are the use cases listed in the training course:

• Incident management - Managing incidents

• Problem management - Uncovering and resolving problems

• Change management - Handling changes to systems or processes

• Knowledge management - Keeping track of updates to knowledge articles/resources

• Asset and configuration management - Assets are our computers/software, and configuration is how they’re setup

Best Practices

I appreciate these appearing so early in the course. Many times we get stuck on the mechanics of a system (how does an SLA work, how can I enter tickets) and forget all the things that happen around/before that part (planning, validating use cases, etc). The best practices provided by Atlassian relate to things like gathering requirements before you begin, keeping things simple (always a good idea!) and using naming conventions to make things easier to use.

Another best practice that really resonated with me was to test things before you deploy them. I’ve personally not done this (and suffered for it!) - so I highly encourage everyone to test everything before you deploy it.

The section finished up by reminding us to be Jira Champions - people who use Jira regularly and make it part of our regular practice and habit. This is easier said than done (and something I’m guilty of not doing all the time! :D). It is, however, a good reminder - even if we earn the ACP-420 certification it doesn’t mean much if we don’t apply what we learn and share it with others.

Overall I found that these best practices don’t only apply to Jira Service Management - they can be applied to any system or practice.

Map Business Requirements

One of the first projects I worked on spent months mapping business requirements. They had dozens of sessions to understand what the business needed, included subject matter experts from all over the business and had several people focused entirely on this step. It felt like overkill at the time, but once we got to deployment, things went really smoothly. This taught me the importance of understanding the business requirements, understanding what the system can do, and the importance of bridging the gap.

This section focused on exactly that - talk to your users, understand their needs, and then figure out what in Jira will help them do that. This can be easier said than done as there can be a lot of folks to talk to! Fortunately Atlassian has some basic questions to ask, and splits those questions up by group (individual contributor and managers). While this certainly sin’t everything you’d want to do or ask, it’s a great start in understanding what is needed.

There’s several important reminders in there as well - like not over-engineering, and making sure whatever you create actually meets their needs. (It can be very easy to forget deploying Jira is a partnership and not just us telling them what Jira will do for them!).

What we missed

I had hoped to talk about the differences between company and team-managed projects and just ran out of time! We spoke about them briefly, but we’ll pick up there next week.

What’s next?

Next week we’ll pick up right where we left off! I hope to get through the following topics - which should get us more hands-on!

• Company vs. Team managed projects

• Map business requirements to Jira configurations

• Compare company-managed projects and team-managed projects in Jira

• Choose a project template in Jira

• Set up requests and queues

• Set up your services in Jira Service Management

• Configure SLAs to manage service quality goals

What it means to be a system admin

I ran a live training recently about being a Confluence Space Admin. In the context of Confluence, a Space Admin has specific privileges to do things like control access to a space, modify features, etc. The session covered the technical aspects of what admins can do (e.g. features to help manage everything, access controls, etc) but also discussed a more important topic to me - the non-technical responsibilities of a system admin. 

Non-technical importance

Frequently I find that individuals forget about the non-technical side of being an admin… after all, it is very exciting to get admin access to something. It means you get something special, something extra, that most folks never get. It also, however, means you accept a large responsibility - ensuring your system runs effectively and supports its users.

Personally I’ve been caught up in the excitement of being given extra access. There’s new buttons to go push, new things to learn and a big sense of power. Depending on the system the amount of power can be on the smaller end (resetting passwords and the like) to extremely sensitive (access to home addresses or social insurance numbers). Being an admin means being trusted with that access - and by extension to power and responsibility that comes with it.

The best advice I was given about being an admin was in the context of managing a human resources system that had social security numbers (United States government ID numbers). The senior admin told me that “Our job is to make sure the numbers are correct, not to use the numbers”. This had a huge impact on me as it highlighted the importance of making sure the system was accurate, regardless of what the information was.

“Our job is to make sure the numbers are correct, not to use the numbers”

— Sr Database Admin

For me this is what is important about being an admin. You don't only need to consider what the system does (serve up info, support collaboration, etc) you need to understand why you need to do those things and keep an eye on everything around the system. This includes things like planning, maintenance and leadership. Typically one, or all, of these things is forgotten, resulting in systems that are 'broken' (if you ask their users).

What should admins spend their time on?

For me, admins should be spending most of their time planning out how their system can be successful. This doesn’t mean we ignore the tools or features we have, but it does mean we think about the best way to use those tools to help our team. It also means we have to understand what our team needs to do and why they need to do it. For Confluence this could be thinking through an optimal structure, or figuring out what content is missing and how to get it. That said, it also means understanding what our team is trying to accomplish. For example if they need to onboard new hires they’ll have different needs than if they need to support customers.

Maintenance is another area that admins need to be very active in. It's not glamorous, it won't win awards, but it will ensure your system supports the people using it and that it is relevant to them. Maintenance means regularly review how the system is used, digging through content to ensure it’s updated and similar activities. In my experience most of the complaints about Confluence not working related to stale or content that is hard to find - two things that fall squarely on admins to manage.

Active Admins

Being an admin isn't a passive job (although it's easy to fall into that mindset!). Instead admins need to be active and lead their team in how their system is used. In general this should take the form of getting training on the system, reading manuals and talking with your team. For Confluence this can take the form of training users in best practices, building onboarding documentation and showing folks how things can work.

There is a lot that goes into being an admin, and it's incredibly easy to think it's only about the technical side or things or the extra access. For me, however, being an admin is a privilege and a burden. Admins enable their teams. Admins keep things running. Admins allow others to excel.

ACP-420 Managing Jira Service Projects Certification

I’m hoping to earn the ACP-420 certification! Join me for free, live study sessions every Tuesday at 6 AM PST now until March 28th.

I’ve been using Jira Service Management for a while now, and, like many systems, I never had any official training on it. Instead, I learned how to use it by doing, asking questions, and tripping over mistakes. This approach isn’t a bad one as it helps cement in lessons and gave me a great deal of confidence in figuring things out on my own.

It does, however, have a weakness - there’s a lot of aspects of Jira Service Management that I never get exposed to, or I only learn partially. This might be because the group I work with doesn’t use specific features so I never get exposed, or it could be because I figure out a way to do something that doesn’t include aspects of Jira Service Management. Regardless, it has resulted in gaps in my knowledge of how this system works - and by extension my ability to support my team.

What is this certification for?

So, to help plug those holes I’ve decided to pursue the ACP-420 Managing Jira Service Projects certification that Atlassian offers. ACP-420 is concerned with ensuring folks know how to manage and configure Jira Service Management for Cloud (sorry Data Center folks!) and covers a wide range of topics, including:

1. Translating business requirements - Knowing what a business is trying to do is critical in provided proper support. This includes taking their needs and translating them into things Jira Service Management can do.

2. Setting up project features like request types and SLAs - Jira Service Management has a ton of features. Understanding what they all do, how they impact the team, and how to configure them is paramount.

3. Managing permissions and notifications - Two of the most frustrating areas of Jira Service Management are being able to access things, and getting notified properly. As admins we need to know all about these.

4. Setting up dashboards and reporting - Providing teams with insights on how to improve their process or identify bottlenecks is a big part of knowing the system.

5. Setting up the intake portal - Tickets have to get into Jira Service Management somehow! Knowing how the portal works, and how to configure it, is important.

6. And more!

Why should I get certified?

I find there’s a few reasons to get certified. First, it helps improve our knowledge. Second, it may be required for our jobs, and third it can open a door for us.

I find the first reason the most interesting as I’ll learn more about the topic. As I noted above I tend to learn by doing or by necessity which means I end up with gaps in my knowledge. Earning a certification forces me to learn things I may not have otherwise had exposure to, resulting in a wide range of knowledge

Depending on your job a certification may also be required. Not having a certification like ACP-420 can mean not being considered for possible roles, or not attaining a promotion at work. The effort put into earning the certification can be well worth it (and many company’s will even cover the cost of the exam!).

Holding a certification also signals to others that you know a bit about that topic. While having a certification doesn’t mean you know everything about a topic, it does signal you know a certain amount. Having a certification can then mean you’ll have more opportunities open to you as others will see it as proof of your skills. This can make it easier to get interviews - after which your experience takes over.

Join me to study for the ACP-420

The biggest challenge earning a certification for me isn’t usually the content - it’s making the time to actually study! Between work, family and other things it’s incredibly hard to find time to go through the training materials (all of which are provided free by Atlassian). So, to help me get this done I’m hosting free, live, study sessions every Tuesday morning at 6 AM PST.

These sessions will be a shared time for us all to prepare for the ACP-420. We’ll go through Atlassian’s training, as well as help answer each other’s questions. I’ll also be summing up my study notes and sharing them here for folks to use.

Additionally, I’ve got 3 free exam vouchers I’ll be giving away. If you win you’ll be able to take the ACP-420 for free (provided you take the exam by June 1st, 2025!).

Resources

1. Atlassians page on ACP-420

2. Free training for ACP-420 (What we’ll be using!)

3. Sign up for my study sessions (and other great live training)

Don’t worry, get HAPI

Quick note! This blog post is sponsored by ScriptRunner.

What is scripting

Check out my prior post for more information on what scripting is. In short, it’s a way to expand what a system is capable of, and to allow a system to meet a specific use case. It is a very powerful tool… however, it can also be a bit challenging (and intimidating!) to learn.

Unless you have a background in writing scripts, getting started can be incredibly confusing. Systems will use different types of scripting, meaning lessons you’ve learned in one system may not apply to another one. If you don’t have a background in scripting, even the basic concepts can be challenging to learn as they can be unlike anything else you’ve done in the past.

Many scripting languages are also incredibly complex, requiring you to understand a variety of topics, but also know a wide range of commands. While this complexity can be warranted to support various use cases, it makes it very hard to learn it.

Jira is Groovy (well, it uses Groovy)

A lot of scripting in Jira relies on Groovy - a scripting language that has a lot of power and makes it easier to use Jira’s APIs (Application Programmer Interfaces). That said, it also has a bit of a learning curve - even if you know another scripting language like Javascript. Unless you happen to have a deep set of technical skills or a background in scripting, you may find yourself quickly overwhelmed with its “easy to learn” setup.

Personally, I find this to be a shame, as almost every group can benefit from scripting. It allows admins to unlock a lot of potential, and to alleviate a lot of manual processes that teams go through. This is especially true for teams using Jira, as many times there are steps in their process that can, and should, be automated.

The high cost of entry for Groovy means that many admins simply won’t learn it. If they’re very lucky they’ll have another resource at their company (or a contractor) who can help script, but many times they simply won’t have access to this powerful tool. Even if an admin does know scripting, they may find themselves lacking the time necessary to write out useful scripts.

When an admin gets lucky and happens to inherit a good script or have someone else build it out, they may find themselves in trouble as they may not understand the code. This makes it hard to troubleshoot issues or bugs that may crop up, but this also makes it hard to modify the code if they want to. Adjusting existing code is a very common approach to improving things, but if it’s too confusing to figure out, admins will simply not get those benefits.

When admins are lucky enough to have existing code they might also find themselves lacking any documentation about what it does, or how to adjust it. Poorly documented code is nothing new, but it still represents a big challenge. This reliance on “tribal knowledge” can make it impossible for an admin to make progress, or even understand what a specific script does.

How ScriptRunner’s HAPI helps overcome those challenges

Despite all of these challenges, scripting is still an incredibly valuable tool for admins. Fortunately, there is help out there in the form of HAPI. HAPI provides a simplified structure for interacting with Jira Groovy scripts that is substantially more intuitive writing scripts in Groovy without HAPI.

For example, this bit of Groovy code

Can be rewritten in HAPI as 

Not only is the new code substantially shorter( 4 lines vs 30) it is vastly easier to read and understand. I bet after you read the HAPI code you could explain what it does to someone else… much easier than just the pure Groovy version above!

This readability is one of the biggest advantages HAPI provides - simply read it left to right like you would a sentence in English to know what it does. For example, the code above could be read as 

“Create an issue in the SSPA project with the Task type. Make the summary “I need to create a ticket” and the description “well, that was easy”. 

Imagine being a new admin and being able to decode your scripts this quickly (or make new ones…)!

Seamless integration

HAPI is an extension to ScriptRunner, which might make you wonder if they play nice together. The good news is they do! Scripts using HAPI can seamlessly integrate with existing ScriptRunner scripts. This means groups already using ScriptRunner can easily add new scripts utilizing HAPI, but also easily refactor existing scripts to be more easily readable. Even better, scripts you write can use both HAPI and more traditional Java API calls in the same script so you’re not forced to choose one or the other.

This backwards compatibility is a great feature and means that even if an admin doesn’t know Groovy (or doesn’t want to risk breaking existing scripts), they can easily add new HAPI scripts to their environment. 

Quality of Life (QoL)

If HAPI stopped there and only made scripts easier to read/interpret and was compatible with Groovy, it would be amazing. Fortunately the nice people at ScriptRunner have gone a few steps further to make HAPI even more useful for admins.

One way they’ve done this is by adding auto-complete for your custom values. This means that as you type in commands, HAPI will start showing possible valid entries based on what you typed. This drastically reduces the risk that you’ll mistype a command, or pick one that doesn’t exist. Personally, I find this incredibly useful, as I typically find myself opening up documentation to double-check what commands there are.

In the example below we can see HAPI serving up possible completions to “setD” - something that Groovy does on its own.

HAPI, however, takes this a step further by pulling in valid options for fields. For example, if you wanted to add an issue to a project, HAPI would display a list of valid project keys in the code. Without this feature, you’d either have to look up what you wanted, or memorize every project key (trust me, don’t try this one!). By displaying valid options for fields directly in the code HAPI saves admins a lot of time.

In this screenshot we can see HAPI suggesting possible valid values for “Assignee”:

HAPI also works with other ScriptRunner features. For example, it can be used to build out custom listeners (scripts that detect when a specific event occurs, for example an issue being created or a field changing a value). While this can be done in with Atlassian’s APIs, having all of the features mentioned above make it substantially easier. Similarly, you can use it to extend Jira’s standard UI - again leveraging all of the benefits of HAPI in an existing (very useful) feature.

Availability

HAPI was originally built out for Jira Data Center (DC)... but the great news is it it is now available on Jira Cloud!

Conclusion

HAPI is a big step forward in terms of scripting in Jira. Its backward compatibility with existing ScriptRunner scripts, and the wide range of QoL features make it a great choice for admins looking to automate things. These features also make it a lot more approachable to someone who is just beginning to learn Groovy as it has a much flatter learning curve. Even better, it helps eliminate a need for a deep understanding of Groovy or Jira API’s, making it much more approachable to basically everyone.

Curious to learn more? Check out more info here!