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.

title.png

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.

1.png

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.

b2.png

b3.png

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.

b4.png

We use the following workflow:

b5.png

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

rule1.jpg

  1. The rule is triggered as a result of creating a new issue.
  2. Then using the Issue field condition, we check if the request type indicates that the user has requested a new project in Jira
  3. Then, we validate provided project name using Send web request action component. For this purpose, we use the "Get valid project name" endpoint.

7.png


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.

 


  1. 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.
    8.png
  2. 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.
    9.png

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.

10.png

  1. The second automation is triggered by the approval of the issue and its transition from Waiting for approval to the In Progress status.
  2. Then, the rule verifies whether the request type is correct and the "Internal business project" template has been selected.
  3. 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.

    11.png
  4. 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"
    }

    12.png
  5. 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.
    13.png
  6. 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
    14.png

Summary

As a result of this setup, the process of creating a project is very convenient and much shorter:

  1. The user completes the form
  2. The Template Owner accepts a request using the button on the portal or in the e-mail
  3. 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.

37 comments

Kalin U
Rising Star
Rising Star
Rising Stars are recognized for providing high-quality answers to other users. Rising Stars receive a certificate of achievement and are on the path to becoming Community Leaders.
July 11, 2022

@Piotr Zadrożny _Eyzee_ , thanks so much for the detailed and illustrated guide. This is such a huge step into providing custom Jira project templates. It does require some setup but once done, everything looks like a breeze.

Like # people like this
Leo Diaz _ DEISER
Community Leader
Community Leader
Community Leaders are connectors, ambassadors, and mentors. On the online community, they serve as thought leaders, product experts, and moderators.
July 11, 2022

Very useful! As a complement, we have documented how to add information to Projectrak to newly created projects:

https://deiser-apps.atlassian.net/wiki/spaces/PROJECTRAKCLOUD/pages/1640792/Projectrak+as+action+-+Create+a+project+and+fill+Projectrak+with+issue+data+after+issue+transition 

 

Screenshot 2023-03-24 at 23.25.46.png

Like # people like this
Dan Tombs
Rising Star
Rising Star
Rising Stars are recognized for providing high-quality answers to other users. Rising Stars receive a certificate of achievement and are on the path to becoming Community Leaders.
July 11, 2022

This is a really good article @Piotr Zadrożny _Eyzee_

 

We were actually getting ready to do this ourselves anyway. Some slight changes obviously but its incredibly detailed and can definitely help firm up some of our thoughts on how to do this.

Thanks,
Dan

Piotr Zadrożny _Eyzee_
Community Leader
Community Leader
Community Leaders are connectors, ambassadors, and mentors. On the online community, they serve as thought leaders, product experts, and moderators.
July 11, 2022

I'm glad you found this article useful. The coolest thing is that such automation is very expandable. There are endpoints for board cloning, adding users to project roles, or even adding new context and options to used custom fields. As you can see in @Leo Diaz _ DEISER's comment you can also integrate it with other apps.

Like Leo Diaz _ DEISER likes this
Italo _Modus Create_ July 24, 2022

This is great article!

I'm still waiting for this feature to use external API that requires authentication. Please vote and watch to make cloud environment even more secure!

https://jira.atlassian.com/browse/JRACLOUD-77612

Maximilian Floß January 17, 2023

@Piotr Zadrożny _Eyzee_ 

Very useful article!

How can i automate that during the project creation also four releases are created in the new project? 

Piotr Zadrożny _Eyzee_
Community Leader
Community Leader
Community Leaders are connectors, ambassadors, and mentors. On the online community, they serve as thought leaders, product experts, and moderators.
January 17, 2023

Hi @Maximilian Floß 

Thanks for your feedback.

Regarding your request, you can surely do that in several ways:

  1. You have a dedicated Create version action in Jira Automation. Unfortunately, it only lets you provide a specific project and does not allow you to provide a custom project in which such a version should be created. You would need to add an additional rule that will create new versions after any project creation (you will have to limit it to, for example, projects with specific descriptions or names). Additionally, it will require global automation which may not be possible in your case.

    a1.png

  2. A much better option would be to add a new block to the current automation that will call another web request which will add a new version:

    a2.pngWe are using this endpoint: https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-project-versions/#api-rest-api-3-version-post

    The only required body parameters are name and projectId but you can provide more info like in my example

    v1.png

    Worth noting that versions require Jira Software and I am not sure if they work the same way in Team Managed projects or Work Management ones.

    This action block needs to be put after the project creation like here:

    b1.png

    As you can see in the screenshot I also added further action "Create variable":

    c1.png

    It's needed because, after a new web request, the webResponse smart value will provide a response from that new request and we need previous information like the project key in the comment message. If you create a variable I suggested you can then use it in the comment:

    cc1.png

Hope everything is clear.

Cheers

Like Laurie Sciutti likes this
Maximilian Floß January 19, 2023

@Piotr Zadrożny _Eyzee_ 

Thank you very much for the detailed instructions. 

I will test your option 2. If I would like to create four versions (not only one) should I add 4 web requests in the automation or can I define 4 version names in the web requests? 

Thank you very much in advance.  

Piotr Zadrożny _Eyzee_
Community Leader
Community Leader
Community Leaders are connectors, ambassadors, and mentors. On the online community, they serve as thought leaders, product experts, and moderators.
January 19, 2023

@Maximilian Floß you should add 4 web requests.

Maximilian Floß February 1, 2023

@Piotr Zadrożny _Eyzee_ 

What should I do if I do not need the creation of version in my new project, but the creation of three Epics? 

Markus Kroemer March 8, 2023

@Piotr Zadrożny _Eyzee_ Thank you very much for this post. Very helpful so far.

Is there a follow-up post where you explain the "Whats next?" Especially, the automatically creating, components, boards, granting project permissions and set up releases relative to a given date.

If not, do you know a good article or documentation where I can start?

Danny
Rising Star
Rising Star
Rising Stars are recognized for providing high-quality answers to other users. Rising Stars receive a certificate of achievement and are on the path to becoming Community Leaders.
March 23, 2023

This is great, thanks @Piotr Zadrożny _Eyzee_ 

James Carn June 12, 2023

This is great, I have used this and it works perfectly, the only thing we did was add the requestor as the project administrator at the end of the request.

Samuel Smiles P June 13, 2023

How to get dynamic project key's? What should be the smart value for the project key?

Piotr Zadrożny _Eyzee_
Community Leader
Community Leader
Community Leaders are connectors, ambassadors, and mentors. On the online community, they serve as thought leaders, product experts, and moderators.
June 13, 2023

Hi @Samuel Smiles P 

You can use Rest: /rest/api/3/projectvalidate/validProjectKey This REST endpoint validates a project key and, if the key is invalid or in use, generates a valid random string for the project key.

Here you can find more info: https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-project-key-and-name-validation/#api-rest-api-3-projectvalidate-validprojectkey-get

 

The project key must be unique and by default must be between 2 and 10 characters (this can be changed in settings) and as far as I remember consists only of uppercase letters. 

Samuel Smiles P June 14, 2023
Rhys Richards July 5, 2023

hi

So ive done this and changed where needed and i keep getting a 400 error. not sure what im doing wrong Screenshot 2023-07-05 140847.pngScreenshot 2023-07-05 141101.pngScreenshot 2023-07-05 141229.png

can someone pls help or advice me here 

Gerben Heinen July 13, 2023

i have used this method to create projects in JIRA cloud, and I have encountered the following issue: [JWMCLOUD-522] Creating a Business project through the REST API do not configure Category Field context correctly - Create and track feature requests for Atlassian products. 

So when creating a project through the api and setting all the schemes manually, instead of using the templates, results in that you won't be able to add a category to an issue. You have to contact Atlassian support to fix this issue, until R&D has created an API fix.

Gerben Heinen July 13, 2023

@Rhys Richards 

the first automation: your url is wrong, your missing ?key= 

atlassian.net/rest/api/3/projectvalidate/validProjectKey?key={{projectKey}}

2nd automation: your json is malformed, perhaps remove the empty line after the first '{' ?

Alex Ziegltrum August 3, 2023

Hey @Piotr Zadrożny _Eyzee_ 👋,

thanks for sharing this amazing automation rule. We have adapted it successfully and want to enhance it by adding people to the new project.

The users I want to add are part of my organization, no externals, so no invitation process is involved.

In the API documentation, I found how to add user or group to the default members of a role, but not to a role of a specific project.

Is there a chance to do that?

Cheers, Alex

Alex Ziegltrum August 3, 2023

@Italo _Modus Create_  thanks, this is the spot that I already looked over.

Maybe I'm still getting it wrong, with that endpoint, we can manipulate the default system project role actors, but not for project "ABC123" and role "User", right?

 

EDIT: it's a bit more up there, isn't it? "Add actors to project role" that could do it.

/rest/api/3/project/{projectIdOrKey}/role/{id}

I'll try this out. Thanks! 😊

Like # people like this
joel.outry September 13, 2023

Has anyone figured out a way to create a team-managed jira work management project using the API? We want to provide more control to the users using the team managed projects. Anyone have a hint? 

Kristóf Lauber September 25, 2023

I keep getting the following error from the POST call: 

Received response: {errorMessages=[], errors={projectKey=Project keys must start with an uppercase letter, followed by one or more uppercase alphanumeric characters.}}

 

REQ link: /rest/api/3/projectvalidate/validProjectKey?key={{issue.summary.split(" ").left(1).toUpperCase().replaceAll("[^a-zA-Z0-9]","").join("").left(10)}}

 

Any ideas?

Gerben Heinen September 25, 2023

It tells you the issue: Project keys must start with an uppercase letter, followed by one or more uppercase alphanumeric characters

Comment

Log in or Sign up to comment
TAGS
AUG Leaders

Atlassian Community Events