Tempo Planning REST API
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.
[ { "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
{ "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
{ "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
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
{ "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
{ "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
{ "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
{ "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
{ "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
{ "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