In the last article, we laid the foundations for qualifying our requests and, above all, automatically directing them in JSM to the right support team.
You've been waiting for it: here it is! In this much more technical article, we're going to take a look at how to automate the routing of requests, as well as manage notifications and redirect requests in the event of an error. A lot more technical, because a large part of the set-up relies on scripts written in the Groovy language, and requires a grounding in development.
Alternative to scripting
Depending on the context and requirements, it may be possible to use other solutions that don't require an additional plugin, or to write scripts to perform certain operations, such as setting up automatic rules or using post-functions. But this will mean compromising on the expected level of customization.
As a reminder, my client uses the following plugins:
- Script Runner
- Automation for Jira (included in Jira Software and Jira Service Management Data Center)
- Assets - ex Insight (included in Jira Service Management Data Center version 4.15 and higher)
Step 1 - Direct a new request to the appropriate unit
The first step is to direct a new request to the corresponding cell. In concrete terms, this means automatically valuating the Support unit with the cell corresponding to all the criteria selected in the request, as soon as it is created.
In view of the specificities to be managed and the need to apply this function to different projects with different workflows, we have chosen to implement a script. Listener.
Script Listener
Listener scripts can be used to define code that will be executed when one or more events are triggered for a given request. For example, the creation of a ticket, the addition of a comment, etc. To find out more, please consult the editor's documentation.
For the moment, we want this script to be triggered by the creation of a request, for our three support projects. When triggered, it must :
- Retrieve request qualification fields, i.e. service type, category and sub-category;
- Search in the project's service record repository for the one corresponding to the combination of the three criteria;
- If a service record is found, retrieve the associated assistance cell and value it in the Support unit demand.
That's all well and good, but what does it actually do? Let's take a look at some extracts from the simplified script, corresponding to the need expressed above.
Script 1 - Automatic request orientation
We start by importing the classes we'll need, and declaring the various constants we'll use in the script.
Constants at the top of the script
I've chosen to declare the constants at the top of the script rather than as I go along, so that I can easily modify them in the event of a change, such as the renaming of a field.
You'll also notice that I use the custom field labels instead of their technical identifiers. Again, this is a personal choice I can afford to make. In fact, my client has a "one label = one field" rule. So we never have two fields with the same label. And I find it easier to read. Purists will prefer to use the technical identifier of the field.
We initialize the Jira Java API services we'll need.
We then retrieve the custom fields, i.e. the three criteria fields to identify the corresponding service record and the field for the support team that will be in charge of the request.
It is now possible to retrieve the data we need from the request.
We search our Assets repository for the service record based on the criteria.
Finally, if we find a service record, we retrieve the associated assistance cell and value it in the field Support unit of the request. And we register the change.
And that's it! In just 5 steps, we automatically updated the helpdesk when the ticket was created.
🚨 Alert! Alert! 🚨
At some customer sites, I've seen administrators with little or no knowledge of development retrieve scripts from the Internet and copy and paste them into their instance, modifying almost nothing, without necessarily understanding how they work. And this can lead to major problems, as you can imagine.
Never use a script you don't understand on your production instance. You must have a minimum command of what the script is doing, otherwise your data will be irretrievably altered.
User performing operations via script
Some of the scripts you set up will perform actions on behalf of the current user, i.e. the logged-in user who initiated the script. It is therefore essential that this user has at least the right to perform these actions.
In some cases, it is not advisable to open up rights to users. In such cases, you should explicitly use an account dedicated to scripts and automation rules.
Step 2 - Notify assistance cells
Now that a new request has been assigned to a cell, it's time to notify the agents concerned (and only them). In theprevious article for the introduction of the Support units that some of them would prefer not to be notified, or to be notified at a generic e-mail address, etc. These specific needs led us to opt once again for a script that would handle all cases.
We need this script to be activated every time the cell associated with a request changes, i.e. when a specific event is triggered... See what I mean? Yes, we're going to set up a new Listener script.
Have several scripts dedicated to an action rather than a single giant script
Why not simply manage the notification in the previous script?
That's a good question! And to tell you the truth, in the beginning, that was the case. We had a complete script that managed the association of the cell with the request, then the notification, all in one. However, as improvements were made and new requirements emerged, it became necessary to separate the two scripts. This way, we could use the notification script in other cases. For example, for teams wishing to be able to manually modify the cell responsible for a request.
It's generally good practice to separate uses into dedicated scripts or functions.
This new script must only be triggered by a specific event. To control its use, we create a new Jira custom event Assistance - Cell notification on which we'll be able to build. To find out more, please consult the publisher's documentation. how to add an event in Jira.
When the event is triggered, the script must :
- Retrieve the assistance cell associated with the request;
- Identify the cell's specific settings: notification required or not, use of a generic email or not, retrieve the list of agents who are members of the cell, etc. ;
- Prepare and send email notification to the right recipients.
Here are a few extracts from the script.
Script 2 - Notification of the helpdesk assigned to a request
As in the previous script, we have already imported the classes, declared the constants and initialized the services.
To avoid unnecessary errors, for example on a recipe instance, we check that outgoing mail is activated. If not, we can stop here.
We retrieve the assistance cell responsible for the request.
We find a cell on the application. We can check its particulars, i.e. whether it wishes to be notified, and if so, how:
- Agents only ;
- Only the generic e-mail address;
- All agents and the generic e-mail address.
If the cell wishes to receive notifications, we can prepare the e-mail: recipients, subject and message body.
All that's left is to send the e-mail. To do this, we use the Jira SingleMailQueueItem which will allow us to add our mail to the outgoing mail queue.
Now that our notification script is ready, we need to add a small piece of code at the end of our first script for identifying the responsible support team, which will enable us to trigger the event Assistance - Cell notificationHere is an extract:
We've just laid a solid foundation for our automation. 🥳 But we're not done yet... We now need to manage the additional use cases around demand creation.
Step 3 - Adjust the qualification of a request
Agents need to be able to modify the user's qualification choices once the request has been created. And this modification can then have an impact on the cell responsible for handling the request.
To manage this, we add a transition dedicated to changing the three qualification criteria in the workflow. This solution has the advantage of :
- Control the updating of these three criteria and their consequences by limiting this action to a single location;
- To be able to trigger a specific event when the transition is executed, which we can then "listen to" with our first script.
We therefore create a new custom event Assistance - Change of qualificationthat we are associating with our transition Change qualification.
We also add this new event to our first script, which we update to take account of this new case. Depending on the event that triggered the script (creation or change of qualification), we need to check whether the cell already associated with the request has changed, and adjust certain operations.
In terms of transition, we're thinking of :
- Associate a transition screen containing our three qualification fields (service type, category and sub-category);
- Remove the current manager from the request, as qualification may involve a change of cell.
Step 4 - Transfer a request manually to another support cell
The three support teams would also like to enable agents to manually transfer a request to another cell. The Strawberry team, on the other hand, would like this to be possible, but only to another cell working on the same perimeter.
We must therefore :
- Enable agents to select another assistance cell, regardless of the criteria used to qualify the request;
- Notify selected cell.
Here again, the most appropriate option is to add a new transition to the workflow (again, for the sake of control and easier reuse of previously implemented scripts).
We therefore add the new transition Change the cell responsible who :
- Opens a screen with Support unit. We apply a constraint to this field for the Strawberry project (via the field contexts we set up in the previous article), in order to propose only cells with the same scope of intervention as the current cell ;
- Trigger the helpdesk notification event.
Step 5 - Finalize settings
Now that the mechanics of automation are in place, we can finalize the parameterization of our projects. I won't go into the details of parameterization in this article, but in summary, we have :
- Set up a field configuration scheme to declare at least our three qualification fields as mandatory;
- Create application forms on the user portal side, sometimes with automatic enhancement of certain qualification fields. For example, in the Request a new computerwe have hidden and set the default value for the type of service in Equipment request and the category in Computer. Only the sub-category field is proposed, and is automatically filtered to display only consistent values:
- Create queues for each cell, so that they can easily visualize the tasks to be processed:
- Configured project screens so that qualification fields and the helpdesk are not available for direct modification.
Note: my client uses a plugin to better manage queues, which explains the slightly different display from the standard one in the screenshots above.
Go further
As seen in previous articles, we didn't stop there. With time and experience, we were able to enrich the various projects according to the needs of the teams, building on the elements already in place. As the scripts were designed for all teams and had minimal dependency on each other, we were able to easily add our own new features:
- Implementation of an HR reference framework with the notion of Person card : employee data is automatically loaded from the group's Active Directory. The Person card is then automatically associated with the reporter's request, enabling agents to view the reporter's information at a glance;
- Integration of application catalogs with service sheets and support requests: the application and module concerned by a service sheet are entered in the latter, automatically enhancing the corresponding fields on support requests. Reports can then be produced on the number of requests for a given application;
- Integration of the CMDB (asset repositories), particularly the Hardware assistance requests: each piece of equipment is associated with a person, so that all the requester's equipment is automatically included in an assistance request. This enables agents to quickly check the equipment already owned by the reporter, and get an idea of the situation. It is also possible to include a field in certain forms enabling the reporter to select the equipment on which he or she is having difficulty.
These are just a few examples of the uses to which these three reference systems can be put. Would you like to find out more about one of these frameworks and their interactions with projects? Don't hesitate to contact me, and I'll be happy to write a follow-up article on the subject.
In conclusion
Phew, we're finally done! And our efforts are paying off. Now, the user can easily open a request on one of the support portals. The request is automatically routed to the most appropriate support cell according to the choices made in the form. Agents belonging to the cell will be notified when required.
In the event of an error in the user's prequalification, no need to worry: the agent who took charge of the request can easily modify the selected criteria, which re-triggers the referral to the right cell.
Finally, we also talked about going a step further by automatically enriching requests with data from other repositories, such as the application concerned by the request, or HR information on the requester.
To achieve this, we saw that we could rely on native Jira Service Management Data Center functionalities, but that for certain operations it was still necessary to use a scripting plugin such as Script Runner.
In the next article, we'll look at how to escalate a request to level 2 teams.
Cover illustration by pch.vector on Freepik
