Tempo Planning REST API is for developers who want to integrate with Tempo add-ons. The REST API is a standard interface for interacting with the Tempo Planning API module. Use the REST API browser built into JIRA to browse the services provided by the Planning REST API. The examples in this tutorial use curl and are meant to give an idea of how to use the REST API for common use cases.

For more detailed information on REST see JIRA REST APIs documentation.

Page Status: IN PROGRESS

First available in	Tempo Planning API 2.0
Last updated in

Warning!

The REST API is a work in progress and is subject to changes. Product updates may cause significant changes in function without advance warning.

Index

Data Types

The Planning API resource has several different types of parameters that are documented below.

User doc versus REST API terminology:

User doc uses the term Plan Item and REST API uses the term Allocation.
User doc uses the term Work Item and REST API uses the term Plan Item.

Assignee Type

This data type is used when posting and updating Plan Items. Assignee type tells you who or what the Plan Item is meant to be for.

Parameter name: {assigneeType}

Possible type values:

team - The assignee is of type team. The Plan Item is planned on team level and is reflected on everyone in that team.
user - The assignee is of type user. The Plan Item is planned on a certain user.

Scope Type

This data type is used when posting and updating Plan Items. Scope type tells you where you are making plans. It could be done for example in teams planning or project planning.

Parameter name: {scopeType}

Possible type values:

team - The scope where this Plan Item is planned via team.
project - The scope where this Plan Item is planned via project.

Work Item Type

This data type is used when posting and updating Plan Items. Work Item type tells us what kind of plan has been made. You can plan on many types of things, from project plans to more precise issue planning.

Parameter name: {planItemType}

Possible type values:

COMPONENT
EPIC
ISSUE
PROJECT
SPRINT
BOARD
VERSION

Reflective and Recurring Planning

User doc versus REST API terminology:

User doc uses the term Plan Item and REST API uses the term Allocation.
User doc uses the term Work Item and REST API uses the term Plan Item.

Tempo Planner has two ways of extending Plan Items to users from one Plan Item.

Reflective Planning

When a team Plan Item is created, reflective Plan Items are also created that are expanded to all members in that team. Those Plan Items get same attributes as the parent Plan Item.

The reflective plans take in account memberships for each user they are reflected upon. So if a team member is only active in the team for some period of time then he only gets a reflection of the plan for the period where he is active.

Recurring Planning

Plan Items that need to be repeated for a period of time can get recurring rules as attributes. Recurring parent Plan Item has a "recurrence" entity attached to itself which contains "rule", "endDate" and "recurCount".

recurrence: rule: Recurring Plan Items can have the following rules:
- NEVER
- WEEKLY
- BI-WEEKLY
- MONTHLY
recurrence: endDate: a chosen end date for the recurrence of the Plan Item.
recurrence: recurCount: Integer showing the number of recurrences.

Querying Existing Plan Item Data

User doc versus REST API terminology:

User doc uses the term Plan Item and REST API uses the term Allocation.
User doc uses the term Work Item and REST API uses the term Plan Item.

Get all Plan Items for a given Query

All parameters are optional.

Possible filter parameters:

assigneeKeys: List of assigneeKeys, can be either user names or team ids.
assigneeType: Type of assignee, either USER or TEAM.
planItemId: Id of a certain work item.
planItemType: Type of work item to search for.
startDate: Start of the search period in ANSI format.
- If startDate is not defined but endDate is defined then startDate will be one month back in time from endDate.
endDate: End of the search period in ANSI format.
- If endDate is not defined but startDate is defined then endDate will be one month ahead of time from startDate.
expandReflections: If true then all user plans that are reflected from a team plan are also included.
- Default = true.

If neither endDate and startDate are defined then the search period will be one month from the current date (today).

For this example we get all Plan Items that are planned for assignees "admin" and "jessie", setting them as assigneeKeys, which assignee type is "user", and we want to check for period from 10/11/2014 until 20/11/2014 which we represent as an ANSI formatted string.

Request

curl -D- -u fred:fred -X GET -H "Content-Type: application/json"  
http://localhost:2990/jira/rest/tempo-planning/1/allocation?assigneeKeys=jessie&assigneeKeys=admin&assigneeType=user&startDate=2014-11-10&endDate=2014-11-20

Response

The response we get has all the basic information about Plan Items that are planned for those users for that given period.

Get all Plan Items for an Assignee in a given Period - Response

[
  {
    "id": 1,
    "assignee": {
      "key": "admin",
      "type": "user"
    },
    "planItem": {
      "key": "TO",
      "id": 10130,
      "type": "PROJECT",
      "name": "Tango OnDemand",
      "description": "",
      "projectKey": "TO",
      "avatarUrls": {
        "16x16": "/jira/secure/projectavatar?size=xsmall&pid=10130&avatarId=10011",
        "24x24": "/jira/secure/projectavatar?size=small&pid=10130&avatarId=10011",
        "32x32": "/jira/secure/projectavatar?size=medium&pid=10130&avatarId=10011",
        "48x48": "/jira/secure/projectavatar?pid=10130&avatarId=10011"
      },
      "planItemUrl": "browse/TO"
    },
    "scope": {
      "id": 5,
      "type": "team"
    },
    "commitment": 100,
    "start": "2014-11-10",
    "end": "2014-11-14",
    "seconds": 144000,
    "created": "2014-11-10",
    "createdBy": "john",
    "updated": "2014-11-10",
    "updatedBy": "john",
    "recurrence": {
      "endDate": "2014-11-10",
      "rule": "NEVER"
    }
  },
  {
    "id": 2,
    "assignee": {
      "key": "Jessie",
      "type": "user"
    },
    "planItem": {
      "key": "TO",
      "id": 10130,
      "type": "PROJECT",
      "name": "Tango OnDemand",
      "description": "",
      "projectKey": "TO",
      "avatarUrls": {
        "16x16": "/jira/secure/projectavatar?size=xsmall&pid=10130&avatarId=10011",
        "24x24": "/jira/secure/projectavatar?size=small&pid=10130&avatarId=10011",
        "32x32": "/jira/secure/projectavatar?size=medium&pid=10130&avatarId=10011",
        "48x48": "/jira/secure/projectavatar?pid=10130&avatarId=10011"
      },
      "planItemUrl": "browse/TO"
    },
    "scope": {
      "id": 5,
      "type": "team"
    },
    "commitment": 100,
    "start": "2014-11-17",
    "end": "2014-11-21",
    "seconds": 144000,
    "created": "2014-11-10",
    "createdBy": "john",
    "updated": "2014-11-10",
    "updatedBy": "john",
    "recurrence": {
      "endDate": "2014-11-10",
      "rule": "NEVER"
    }
  }
]

Get a specific Plan Item from an Allocation ID

It is possible to add optional expand=children parameter to get also the recurring and reflected allocation for that allocation.

Required parameters:

allocationId: Id of the plan item.

Optional parameters:

expand: If set to "children" then all reflected and recurring allocations for the allocation are also fetched.
startDate: Start date of the period of desired recurring allocations. Only needed if expand=children is set.
endDate: End date of the period of desired recurring allocatoins. Only needed if expand=childern is set.

In this example we are getting the allocation with id 3. Disregarding the optional parameters, only getting the Plan item with id we search for.

Request

curl -D- -u fred:fred -X GET -H "Content-Type: application/json" http://localhost:2990/jira/rest/tempo-planning/1/allocation/3

Response

Get a specific Plan Item from an Allocation ID

{
  "id": 3,
  "assignee": {
    "key": "bob",
    "type": "user"
  },
  "planItem": {
    "key": "WIKK",
    "id": 10023,
    "type": "PROJECT",
    "name": "Wikkkieea Cloud",
    "description": "",
    "projectKey": "WIKK",
    "avatarUrls": {
      "16x16": "/jira/secure/projectavatar?size=xsmall&pid=10023&avatarId=10001",
      "24x24": "/jira/secure/projectavatar?size=small&pid=10023&avatarId=10001",
      "32x32": "/jira/secure/projectavatar?size=medium&pid=10023&avatarId=10001",
      "48x48": "/jira/secure/projectavatar?pid=10023&avatarId=10001"
    },
    "planItemUrl": "browse/WIKK"
  },
  "scope": {
    "id": 3,
    "type": "team"
  },
  "commitment": 100,
  "start": "2014-11-10",
  "end": "2014-11-11",
  "seconds": 57600,
  "created": "2014-11-10",
  "createdBy": "john",
  "updated": "2014-11-10",
  "updatedBy": "john",
  "recurrence": {
    "endDate": "2014-11-27",
    "rule": "WEEKLY"
  }
}

Get all child Plan Items for a parent Plan Item

This applies either to an Plan Item that has reflective planning or an Plan Item that is recurring.

In this example we use AllocationId = 3, to get the children we have to make the expand=children and we have a period from 10/11/2014 to 20/11/2014 which we represent as an ANSI formatted string.

All reflected/recurring allocation appear as a list attribute ("children") on the allocation.

Request

curl -D- -u fred:fred -X GET -H "Content-Type: application/json"  http://localhost:2990/jira/rest/tempo-planning/1/allocation/3?expand=children&startDate=2014-11-10&endDate=2014-11-20

Response

Get all child Plan Items for a parent Plan Item - Response

{
  "id": 3,
  "assignee": {
    "key": "bob",
    "type": "user"
  },
  "planItem": {
    "key": "WIKK",
    "id": 10023,
    "type": "PROJECT",
    "name": "Wikkkieea Cloud",
    "description": "",
    "projectKey": "WIKK",
    "avatarUrls": {
      "16x16": "/jira/secure/projectavatar?size=xsmall&pid=10023&avatarId=10001",
      "24x24": "/jira/secure/projectavatar?size=small&pid=10023&avatarId=10001",
      "32x32": "/jira/secure/projectavatar?size=medium&pid=10023&avatarId=10001",
      "48x48": "/jira/secure/projectavatar?pid=10023&avatarId=10001"
    },
    "planItemUrl": "browse/WIKK"
  },
  "scope": {
    "id": 3,
    "type": "team"
  },
  "commitment": 100,
  "start": "2014-11-10",
  "end": "2014-11-11",
  "seconds": 57600,
  "created": "2014-11-10",
  "createdBy": "john",
  "updated": "2014-11-10",
  "updatedBy": "john",
  "recurrence": {
    "endDate": "2014-11-27",
    "rule": "WEEKLY"
  },
  "children": [
    {
      "id": 0,
      "assignee": {
        "key": "bob",
        "type": "user"
      },
      "planItem": {
        "key": "WIKK",
        "id": 10023,
        "type": "PROJECT",
        "name": "Wikkkieea Cloud",
        "description": "",
        "projectKey": "WIKK",
        "avatarUrls": {
          "16x16": "/jira/secure/projectavatar?size=xsmall&pid=10023&avatarId=10001",
          "24x24": "/jira/secure/projectavatar?size=small&pid=10023&avatarId=10001",
          "32x32": "/jira/secure/projectavatar?size=medium&pid=10023&avatarId=10001",
          "48x48": "/jira/secure/projectavatar?pid=10023&avatarId=10001"
        },
        "planItemUrl": "browse/WIKK"
      },
      "scope": {
        "id": 3,
        "type": "team"
      },
      "commitment": 100,
      "start": "2014-11-17",
      "end": "2014-11-18",
      "seconds": 57600,
      "created": "2014-11-10",
      "createdBy": "john",
      "updated": "2014-11-10",
      "updatedBy": "john",
      "recurrence": {
        "parent": {
          "id": 3,
          "type": "user"
        },
        "endDate": "2014-11-19",
        "rule": "NEVER"
      }
    }
  ]
}

Creating Plan Items

See documentation about Tempo Planning REST API#Data types.

User doc versus REST API terminology:

User doc uses the term Plan Item and REST API uses the term Allocation.
User doc uses the term Work Item and REST API uses the term Plan Item.

Create a basic Plan Item

See data below for more information on what is necessary to create Plan Items.

The commitment data attribute is an integer from 0-100 and represents how committed the assignee is to this plan. In Tempo Planner this is presented as percentages.

Request

curl -D- -u fred:fred -X POST --data '{see below}' -H "Content-Type: application/json"  http://localhost:2990/jira/rest/tempo-planning/1/allocation

Data

Create a basic Plan Item - Data

{
  "planItem": {
    "id": 10023,
    "type": "PROJECT"
  },
  "scope": {
    "id": 5,
    "type": "team"
  },
  "assignee": {
    "key": "admin",
    "type": "user"
  },
  "commitment": 100,
  "start": "2014-08-27",
  "end": "2014-08-31",
    "recurrence": {
    "rule": "NEVER"
  }
}

Response

Create a basic Plan Item - Response

{
  "id": 9,
  "assignee": {
    "key": "admin",
    "type": "user"
  },
  "planItem": {
    "key": "WIKK",
    "id": 10023,
    "type": "PROJECT",
    "name": "Wikkkieea Cloud",
    "description": "",
    "projectKey": "WIKK",
    "avatarUrls": {
      "16x16": "/jira/secure/projectavatar?size=xsmall&pid=10023&avatarId=10001",
      "24x24": "/jira/secure/projectavatar?size=small&pid=10023&avatarId=10001",
      "32x32": "/jira/secure/projectavatar?size=medium&pid=10023&avatarId=10001",
      "48x48": "/jira/secure/projectavatar?pid=10023&avatarId=10001"
    },
    "planItemUrl": "browse/WIKK"
  },
  "scope": {
    "id": 5,
    "type": "team"
  },
  "commitment": 100,
  "start": "2014-08-27",
  "end": "2014-08-31",
  "seconds": 86400,
  "created": "2014-11-10",
  "createdBy": "john",
  "updated": "2014-11-10",
  "updatedBy": "john",
  "recurrence": {
    "endDate": "2014-11-10",
    "rule": "NEVER"
  }
}

Create Plan Item with Reflective Planning

See data below for more information on what is necessary to create Plan Items with reflective planning. When the assignee is of the type team, then the plan will reflect on all the users that are available on that time in the team.

The commitment data attribute is an integer from 0-100 and represents how committed the assignee is to this plan. In Tempo Planner this is presented as percentages.

Request

curl -D- -u fred:fred -X POST --data '{see below}' -H "Content-Type: application/json"  http://localhost:2990/jira/rest/tempo-planning/1/allocation

Data

Create Plan Item with Reflective Planning - Data

{
  "planItem": {
    "id": 10023,
    "type": "PROJECT"
  },
  "scope": {
    "id": 5,
    "type": "team"
  },
  "assignee": {
    "key": "5",
    "type": "team"
  },
  "commitment": 100,
  "start": "2014-08-27",
  "end": "2014-08-31",
    "recurrence": {
    "rule": "NEVER"
  }
}

Response

Create Plan Item with Reflective Planning - Response

{
  "id": 10,
  "assignee": {
    "key": "5",
    "type": "team"
  },
  "planItem": {
    "key": "WIKK",
    "id": 10023,
    "type": "PROJECT",
    "name": "Wikkkieea Cloud",
    "description": "",
    "projectKey": "WIKK",
    "avatarUrls": {
      "16x16": "/jira/secure/projectavatar?size=xsmall&pid=10023&avatarId=10001",
      "24x24": "/jira/secure/projectavatar?size=small&pid=10023&avatarId=10001",
      "32x32": "/jira/secure/projectavatar?size=medium&pid=10023&avatarId=10001",
      "48x48": "/jira/secure/projectavatar?pid=10023&avatarId=10001"
    },
    "planItemUrl": "browse/WIKK"
  },
  "scope": {
    "id": 5,
    "type": "team"
  },
  "commitment": 100,
  "start": "2014-08-27",
  "end": "2014-08-31",
  "seconds": 0,
  "created": "2014-11-10",
  "createdBy": "john",
  "updated": "2014-11-10",
  "updatedBy": "john",
  "recurrence": {
    "endDate": "2014-11-10",
    "rule": "NEVER"
  }
}

Updating Plan Items

User doc versus REST API terminology:

User doc uses the term Plan Item and REST API uses the term Allocation.
User doc uses the term Work Item and REST API uses the term Plan Item.

Update a basic Plan Item

In this case we change the commitment of a Plan Item from 100 to 50. The id of the Plan Item that is about to be changed has to be in the Url.

Request

curl -D- -u fred:fred -X PUT --data {see below} -H "Content-Type: application/json"  http://localhost:2990/jira/rest/tempo-planning/1/allocation/3

Data

Update a basic Plan Item - Data

{
  "planItem": {
    "id": 10023,
    "type": "PROJECT"
  },
  "scope": {
    "id": 5,
    "type": "team"
  },
  "assignee": {
    "key": "5",
    "type": "team"
  },
  "commitment": 50,
  "start": "2014-08-27",
  "end": "2014-08-31",
    "recurrence": {
    "rule": "NEVER"
  }
}

Response

Update a basic Plan Item - Response

{
  "id": 3,
  "assignee": {
    "key": "5",
    "type": "team"
  },
  "planItem": {
    "key": "WIKK",
    "id": 10023,
    "type": "PROJECT",
    "name": "Wikkkieea Cloud",
    "description": "",
    "projectKey": "WIKK",
    "avatarUrls": {
      "16x16": "/jira/secure/projectavatar?size=xsmall&pid=10023&avatarId=10001",
      "24x24": "/jira/secure/projectavatar?size=small&pid=10023&avatarId=10001",
      "32x32": "/jira/secure/projectavatar?size=medium&pid=10023&avatarId=10001",
      "48x48": "/jira/secure/projectavatar?pid=10023&avatarId=10001"
    },
    "planItemUrl": "browse/WIKK"
  },
  "scope": {
    "id": 5,
    "type": "team"
  },
  "commitment": 50,
  "start": "2014-08-27",
  "end": "2014-08-31",
  "seconds": 0,
  "created": "2014-11-10",
  "createdBy": "john",
  "updated": "2014-11-10",
  "updatedBy": "john",
  "recurrence": {
    "endDate": "2014-11-10",
    "rule": "NEVER"
  }
}

Update an Plan Item with Recurring Children

Only two attributes are needed to make an Plan Item recurring. Basic information in the Plan Item plus recurrenceEndDate and Rule.

RecurrenceEndDate: -a chosen date for the recurrence to end. Presented as a ANSI formatted String. ex. 2014-03-26
Rule: -A chosen rule for the recurring event.WEEKLY, BI-WEEKLY, MONTHLY and NEVER.

Request

curl -D- -u fred:fred -X PUT --data {see below} -H "Content-Type: application/json"  http://localhost:2990/jira/rest/tempo-planning/1/allocation/3

Data

Update a Plan Item with Recurring Children - Data

{
  "planItem": {
    "id": 10023,
    "type": "PROJECT"
  },
  "scope": {
    "id": 5,
    "type": "team"
  },
  "assignee": {
    "key": "5",
    "type": "team"
  },
  "commitment": 50,
  "start": "2014-08-27",
  "end": "2014-08-31",
  "recurrence": {
    "endDate": "2014-12-06",
    "rule": "WEEKLY"
   }
}

Response

Update a Plan Item with Recurring Children - Response

{
  "id": 3,
  "assignee": {
    "key": "5",
    "type": "team"
  },
  "planItem": {
    "key": "WIKK",
    "id": 10023,
    "type": "PROJECT",
    "name": "Wikkkieea Cloud",
    "description": "",
    "projectKey": "WIKK",
    "avatarUrls": {
      "16x16": "/jira/secure/projectavatar?size=xsmall&pid=10023&avatarId=10001",
      "24x24": "/jira/secure/projectavatar?size=small&pid=10023&avatarId=10001",
      "32x32": "/jira/secure/projectavatar?size=medium&pid=10023&avatarId=10001",
      "48x48": "/jira/secure/projectavatar?pid=10023&avatarId=10001"
    },
    "planItemUrl": "browse/WIKK"
  },
  "scope": {
    "id": 5,
    "type": "team"
  },
  "commitment": 50,
  "start": "2014-08-27",
  "end": "2014-08-31",
  "seconds": 0,
  "created": "2014-11-10",
  "createdBy": "john",
  "updated": "2014-11-10",
  "updatedBy": "john",
  "recurrence": {
    "endDate": "2014-12-06",
    "rule": "WEEKLY"
  }
}

Deleting Plan Items

User doc versus REST API terminology:

User doc uses the term Plan Item and REST API uses the term Allocation.
User doc uses the term Work Item and REST API uses the term Plan Item.

Delete Plan Item that is planned for user. In this example we choose to delete a Plan Item with Allocation Id = 3

Request

curl -D- -u fred:fred -X DELETE -H "Content-Type: application/json"  http://localhost:2990/jira/rest/tempo-planning/1/allocation/3

Response

null