9. Creating a project with REST

Goal

This section shows instructions for creating a Jira project with REST using a Gaia template.

Pre-requisites

This tutorial was written considering that :

you have a Jira instance installed and running on your server.
you have administrator rights on that Jira instance.
you have Gaia for Jira correctly installed (see Installing Gaia).
you have an Application Link with a Confluence instance.

URI Structure

To use a REST API, your application will make an HTTP request and parse the response. The Gaia REST API uses JSON as its communication format, and the standard HTTP methods like GET, PUT, POST and DELETE (see API descriptions below for which methods are available). URIs for Gaia REST API resource have the following structure:

http://${JIRA BASE URL}/plugins/servlet/gaia/rest/project

Get all Gaia templates

Request method : GET

Return all configured Gaia templates.

Responses

STATUS 200 - application/json

Returns a list of Gaia templates.

Example

[
  {
    "isDistributedPackage": false,
    "agileBoard": "",
    "components": "",
    "issueTypeSchemeName": "",
    "projectCategories": "",
    "projectType": "",
    "workflowSchemeName": "",
    "issueTypeScheme": "10000",
    "issueSecurityScheme": "-1",
    "issueTypeScreenSchemeName": "",
    "permissionSchemeName": "",
    "projectDefaultAssignee": "",
    "fieldConfigurationSchemeName": "",
    "issueSecuritySchemeName": "",
    "fieldConfigurationScheme": "-1",
    "confluenceSpaceDescription": "",
    "dashboard": "Checklistdashboard",
    "jiraFile": "checklist-jira-1307134068.xml",
    "notificationScheme": "10000",
    "confluenceFile": "",
    "lastModifiedDate": "null",
    "createFilters": false,
    "version": "",
    "workflowScheme": "10000",
    "notificationSchemeName": "",
    "isDefault": true,
    "templateName": "Checklist for Product Owner",
    "importComments": false,
    "versions": "",
    "templateDescription": "An example checklist for product owners made by Lare Lekman and revised in November 2013. productownerchecklist.org",
    "isEnabled": true,
    "projectDescription": "An example checklist for product owners made by Lare Lekman and revised in November 2013. productownerchecklist.org",
    "issueTypeScreenScheme": "1",
    "permissionScheme": "0"
  },
  {
    "isDistributedPackage": false,
    "agileBoard": "",
    "components": "",
    "issueTypeSchemeName": "",
    "projectCategories": "",
    "projectType": "",
    "workflowSchemeName": "",
    "issueTypeScheme": "10000",
    "issueSecurityScheme": "-1",
    "issueTypeScreenSchemeName": "",
    "permissionSchemeName": "",
    "projectDefaultAssignee": "",
    "fieldConfigurationSchemeName": "",
    "issueSecuritySchemeName": "",
    "fieldConfigurationScheme": "-1",
    "confluenceSpaceDescription": "",
    "dashboard": "Softwaredevelopmentdashboard",
    "jiraFile": "starter-jira-352114808.xml",
    "notificationScheme": "10000",
    "confluenceFile": "starter-confluence-352114808.zip",
    "lastModifiedDate": "null",
    "createFilters": false,
    "version": "",
    "workflowScheme": "10000",
    "notificationSchemeName": "",
    "isDefault": true,
    "templateName": "Starter process",
    "importComments": false,
    "versions": "",
    "templateDescription": "A simplified, but complete, software/system lifecycle process that covers project management and technical development activities. To use this template, you need to have a running instance of Confluence AND an application link connecting Jira with that Confluence instance.",
    "isEnabled": true,
    "projectDescription": "",
    "issueTypeScreenScheme": "1",
    "permissionScheme": "0"
  }
]

Create a project

Request method : POST

Create a new project with the assosiated issues and configuration from a Gaia template.

The project type is required only if it is not already configured in the Gaia template.

The Confluence link in required only if there is a confluence file in the Gaia template.

If you specify a Confluence link, you will also need to send the Confluence credentials (username and password).

Example

 {
    "templateName": "Starter process",
    "newProjectName":"A new project",
    "newProjectKey":"ANP",
    "projectLead":"JohnS",
    "confluenceLink":"Confluence",
    "username":"admin",
    "password":"admin",
    "projectType":"software"
}

Schema

{
    "templateName": {
        "type": "string",
        "required":true
    },
    "newProjectName": {
        "type": "string",
        "required":true
    },
    "newProjectKey": {
        "type": "string",
        "required":true
    },
    "projectLead": {
        "type": "string",
        "required":true
    },
\t"confluenceLink": {
        "type": "string",
        "required":false
    },
    "username": {
        "type": "string",
        "required":false
    },
    "password": {
        "type": "string",
        "required":false
    },
    "projectType": {
        "type": "string",
        "required":false
    },
\t"copySchemes": {
\t\t"type": "boolean",
\t\t"required",false
\t},
\t"createProjectLink": {
\t\t"type": "boolean",
\t\t"required",false
\t}
}

Responses

STATUS 200 - application/json

Returns the ID and key of the created project. If there is an problem when creating the project or importing the issues, all errors will be in the Jira log file.

Example

{
  "id": 10000,
  "key": "ANP"
}

STATUS 400 - application/json

Returned if the input is invalid (e.g. missing required fields, invalid field values, and so forth).

Example

{
  "errors": {
    "password": "The password is required.",
    "templateName": "'badTemplate' is not a valid template name.",
    "username": "The username is required."
  }
}

Knowledge level	HIGH
Access level required	Administrator

Table of contents

1 Goal
2 Pre-requisites
3 URI Structure
4 Get all Gaia templates
- 4.1 Request method : GET
5 Create a project
- 5.1 Request method : POST