Let's automate project creation using Jira Automation!
One of the coolest tools integrated with Jira Cloud is the Jira Automation. More and more users create all kinds of automation rules, but most do not realize how powerful and functional these rules can be.
In this article, I will introduce you to some features you may not be aware of.
Use case scenario
Let's automate one of the common Jira administrator tasks - Project creation.
Solution benefits:
- enable the creation of projects by users without granting them unnecessary administrative privileges
- offload the Jira administration team and allow them to focus on other tasks
- ensure the standardization of the Jira project configuration
- minimalize the possibility of human error.
Let's imagine that we have a Jira site with some projects and we need to maintain some level of standardization across all of them. We have two project templates that are used to create most of the new projects on our site. In this example, I created separate templates for Software development projects and Internal business projects.
By template, I mean a common, shared schemes configuration setup on a project such as a workflow scheme, issue type screen scheme, permission scheme, and so on.
So far, if we wanted to create a new project, we need to ask the Jira administrator, who will use the shared configuration option, to create the project for us. We will fully automate this process using the solution based on Jira automation rules.
Solution description
Let's create a new administrative project: “Automatic Jira Support”. I used Jira Service Management, but the same functionality can be achieved on any flavor of Jira Cloud. In the project, create a request type "Request for new Jira project". I placed only 3, all of them required, fields on the create request form:
- Summary (Portal field name: “Enter the name of the project”) - a field built into Jira
- The owner (Portal field name: “Who is the new project lead? ") - User Picker (single user) custom field
- Template (Portal field name: “Choose one of the available templates”) – Select List (single choice) custom field with options representing project templates, i.e. Software development project and Internal business project.
We use the following workflow:
After creating a new ticket on the portal, the first automation will be launched. Automation will check if the name of the project given by the user is not already in use. If a project of that name already exists, it will reject the ticket with the appropriate comment. Otherwise, the user who is the template's owner will be filled in the Approvers field (each template has its owner responsible for the approval of every template-related user request), and then will transfer the ticket for approval. Approval is implemented using functionality built into Jira Service Management, as a result of which the request will transition to one status: Rejected (in case of rejection) or In progress (in case of acceptance). Jira Service Management approval is configured in Workflow and requires all users in the Approvers field to approve requests. After the ticket is approved, the second automation will launch, generating a new project key and making sure it's available for use. Then it will create a project using the configuration of schemes associated with the selected Template and data entered by the user during request creation, such as name or project lead. If the project creation is successful, the request will transition to the Done status with an appropriate comment added. Otherwise, the ticket will change status to Manual support, it will be assigned to the available Jira administrator with comments intended to help the administrator to solve the problem and create the project manually.
Jira Automation configuration details
First automation
- The rule is triggered as a result of creating a new issue.
- Then using the Issue field condition, we check if the request type indicates that the user has requested a new project in Jira
- Then, we validate provided project name using Send web request action component. For this purpose, we use the "Get valid project name" endpoint.
Send web requests quick tutorial
This action is used to communicate between systems to retrieve information or make some changes. In our case, we communicate between Jira automation and Jira itself. You can find Jira Cloud REST API documentation here: Jira Cloud REST API
Configuration options:
- Web request URL: provide REST API endpoint, which is a combination of the site URL (https://something.atlassian.net) and the endpoint URI provided in Jira Cloud REST API documentation. Sometimes, as in this case, certain request query parameters need to be provided in the URL itself ( ?name={name} ). For this endpoint, we need to enter the project name provided by the user.
- Headers are used to store information relevant for establish connections:
- Content-Type indicates in which format the data is sent, or returned. In most cases, we will use application/json
- Authorization defines the credentials of the user whose permission will be used to execute the action in the request. The value here consists of 2 parts: word 'Basic' and encoded (using Base64) combination of user e-mail and user API Token. The best solution here is to create a dedicated admin user to execute all automatic administrative operations. Then, after logging into this user account, generate his API token on the website: https://id.atlassian.com/manage/api-tokens (Make sure you copy created API token as it will be displayed to you only once). Then encode this admin user credentials in format $EMAIL_ADDRESS:$API_TOKEN with Base64 using online tools like https://www.base64encode.org or encode it on terminal using command similar to the following:
echo -n "jira-autoadmin@gmail.com:NCduZ9PpqQhOKylIMx4b6152" | base64
Your Authorization value should be: Basic $ENCODED_CREDENTIALS - Atlassian Cloud REST API are protected from Cross Site Request Forgery (XSRF/CSRF) attacks for security reasons. To call protected APIs from external systems we need to add the X-Atlassian-Token header, setting the value to no-check. This bypasses the server-side XSRF check and allows the request to be fulfilled.
- The HTTP method determines the action we would like to perform on the provided endpoint. In short, GET is used to retrieve information about the resource, POST to create a new one, PUT to update an existing resource, and DEL to delete one.
- Web request body is used to convey additional information.
- Wait for response options are self-explanatory and determine how the automation rule should behave while waiting for or receiving a response for this web request.
- This endpoint checks if the provided project name isn't already in use. If the name isn't in use, the endpoint returns it. If it is in use, the endpoint will attempt to generate a valid project name based on the one supplied, usually by adding a sequence number. We are not interested in changing the name provided by the user, so if the returned name ( {{webResponse.body}} ) is different from the name given by the user ( {{issue.summary}} ), the request will be automatically rejected with the appropriate comment.
- If the project name is correct, the rule will assign the Template owner (each template has its Template owner hardcoded inside the rule) to the Approvers field. So, depending on the selected template, different people are assigned to that field. In our case, Agnieszka is the person responsible for approving issues related to Software Development projects, and Piotr is the person responsible for the approval of Internal business project requests. After updating the Approvers field, the rule transits issue to the Waiting for Approval status.
Second automation
After obtaining approval, the issue changes status to In Progress, and the second Jira automation rule is launched. I've set up two automation here (one for each Template). They are almost identical - they differ mainly in the configuration of the Web request body. I will discuss the configuration of the rule using the example automation configured for the Internal business project template.
- The second automation is triggered by the approval of the issue and its transition from Waiting for approval to the In Progress status.
- Then, the rule verifies whether the request type is correct and the "Internal business project" template has been selected.
- Automation then generates the initial project key and makes a web request to an endpoint that validates the key - "Get valid project key". This endpoint and its configuration are similar to the one we used in the previous automation rule that verified the correctness of the project name. The key for validation is provided in the URL - we use this formula to generate it:
{{issue.summary.split(" ").left(1).toUpperCase().replaceAll("[^a-zA-Z0-9]","").join("").left(10)}}
This smart value breaks the project name (summary) into single words, extracts the first letter of each, converts to Uppercase, removes all resulting non-alphanumeric or numeric characters, and then concatenates them into a single key. Finally, it limits the key length to 10 characters. For example, the key of a project called "Customer & Contractors support project" will look like this: CCSP. Finally, the request URL used in this query is:
https://sampleorg.atlassian.net/rest/api/3/projectvalidate/validProjectKey?key={{issue.summary.split(" ").left(1).toUpperCase().replaceAll("[^a-zA-Z0-9]","").join("").left(10)}}
The endpoint will return this initial key, or a new generated one if the initial key was already in use. We use the returned result in the next endpoint which is responsible for creating the project itself. - This endpoint (Create project) uses the POST method and requires a request body, in which we provide the parameters of the project we want to create. Each project template has its configuration and uses different schemes. In the request body, you may notice a list of schemas that make up the whole template. Schema identifiers shown there can be found in the URL of every one of those schemas. All available options in the body of this REST API are well documented.
Used request body:{
"key": "{{webResponse.body}}",
"name": "{{issue.summary}}",
"leadAccountId": "{{issue.Owner.accountId}}",
"assigneeType": "PROJECT_LEAD",
"permissionScheme": "0",
"notificationScheme": "10000",
"projectTypeKey": "business",
"workflowScheme": "10005",
"issueTypeScreenScheme": "10004",
"issueTypeScheme": "10146"
} - After executing the endpoint, we check the status returned by it. If the request was successful (response code equals 201 meaning that the project has been created), we transfer the request to the Done status and add a comment to it with a link to the newly created project.
- If the request fails (different response code like 400 if the request is not valid, or 401 if the authentication credentials are incorrect, etc.) the request is moved to the "Manual support" status, it’s assigned to a specialist selected using Balanced workload method, and 2 comments are added to the issue:
- internal comment with the details of project creation failure returned by the endpoint
- public comment informing the reporter of the need for manual attendance
Summary
As a result of this setup, the process of creating a project is very convenient and much shorter:
- The user completes the form
- The Template Owner accepts a request using the button on the portal or in the e-mail
- The project is automatically created
No human errors, no waiting for the administrator's availability, keeping standardization among projects. Fast, easy, and fun!
What's next?
This setup can be extended by automatically creating also components, versions, boards, granting project permissions to selected users, etc.
The project can also include other administrative requests, such as creating filters, listing project permissions, or creating spaces in Confluence. The sky is the limit!
If you have any questions about this setup, let me know in the comments.
Was this helpful?
Thanks!
Piotr Zadrożny _Eyzee_
About this author
Atlassian Consultant & Developer
Eyzee S.A.
Poland
65 accepted answers
42 comments