Getting Started

Introduction

The API allows to extract data from TimePerformance. The typical usages of extracted data are:

  • Building custom reports
  • Importing data into other applications such as ERP, HR, CRM...
  • Archives and backups

For any question about the API, please contact Time Performance Support.

Technology

TimePerformance API relies on plain web requests in HTTPS. It returns data in common, textual formats (mostly JSON).

The API can be called from programs written in any language, from command tools (e.g. curl) and even from a web browser by typing the url in the address bar. All API urls start with https://pma.timeperformance.com/api/v2/...

An example of an API client in JAVA is published on GitHub: TimePerformance/apiclient

Authentication

Credentials must be provided with every request as an HTTP Basic Authentication

Note: API Credentials are different from crendentials used in the login form. They can be retrieved from the settings panel in the web application.

Usage Limits

To protect our servers, the following per-user usage limits apply

  • 1 query at a time
  • 1 query every 2 seconds

Data type format

Below are formats for data types (date, number etc.) to be used for query parameters and used in JSON responses.

Type Format Examples
Boolean true , 1 , false , 0
Date YYYY-MM-DD 2014-12-31
Date and Time ISO 8601 2016-06-17T08:43:12.447+0000
Number 3 , 3.6 , -5468.123

Response format

The response format is determined by the extension in the URL: .json or .txt.

url extension Format Description
.json JSON JSON is the standard format for web applications to exchange structured data in plain text over http/s protocol.
.txt Plain text This format is used to return an id or a comma separated list of ids as it is straightforward to parse.

Errors

Error are returned as a response code. Detailed message in plain text are available in the response body.

Code Error Category Possibles causes
400 BAD REQUEST Missing required parameter, Invalid parameter value. Check returned message to get more details.
401 UNAUTHORIZED Access to the data (eg: project..) or functionnality denied to authentified user, Invalid action in regard to business rules. Check returned message to get more details.
404 NOT FOUND Entity (eg: project, user...) not found, Bad URL (API not defined)
500 INTERNAL SERVER ERROR Request failed due to unexpected conditions. Support Team is notified. Data stay safe as any transaction has been rolled back.

Portfolio API /portfolios...

This API provides information related to project portfolios.

:id in URLs are placeholders for the id of the portfolio.

List of Portfolios /portfolios.json

Returns the list of infos about all portfolios accessible by the authentified user.

Example: https://pma.timeperformance.com/api/v2/portfolios.json?archived=1

Parameter Type Description Required Default
archived boolean If set to true, archived portfolios will be included. no false

Response sample

[ {
  "id" : 1951,
  "name" : "My Portfolio",
  "type" : "portfolio",
  "archived" : false,
  "description": " ... ",
  "owner" : {
    "id" : 39,
    "externalId" : "USR-39",
    "name" : "Pierre Durand",
    "type" : "user",
    "firstname" : "Pierre", ... 
   },
  "projects" : [ {
    "id" : 185,
    "externalId" : "",
    "name" : "Demo",
    "type" : "project"
  }, ... ]
}, ... ]

Get Portfolio Id /portfolios/getIdFromName.txt

Returns a comma separated list of ids of portfolios matching the provided name.

Most APIs requires portfolio ids which are not displayed in the web interface. This API provides a simple way to retrieve the id from the portfolio's name. As portfolios names are not unique in the application, the call may return a list of ids.

Example: https://pma.timeperformance.com/api/v2/portfolios/getIdFromName.txt

Parameter Type Description Required Default
name string Name of the portfolio to search (case insensitive). yes

Response sample

-- one portfolio --
32

-- several portfolios --
32,945

Portfolio Progress Report /portfolios/:id/progressReport.json

Returns the progress report of the project portfolio.

The returned data are the same as what is displayed in the web application.

Example: https://pma.timeperformance.com/api/v2/portfolios/32/progressReport.json

Response sample

{
 // Portfolio progress report
 "element" : {
    "id" : 1970,
    "name" : "My Portfolio",
    "type" : "portfolio",
    "archived" : false
  },
  "progress" : 0.43,
  "budgetedCost" : 365640.0,
  "actualCost" : 264782.12,
  "expenseBudget" : 41000.0,
  "expenseCost" : 33000.0,
  "incurredExpense" : 33000.0,
  "plannedEffort" : 771.0,
  "actualEffort" : 396.3,
  "remainingEffort" : 407.08,
  "plannedStart" : "2018-10-01",
  "actualStart" : "2018-08-20",
  "plannedEnd" : "2019-05-17",
  "costPercentage" : 0.72,
  "costRAG" : "KO",
  "effortPercentage" : 0.51,
  "effortRAG" : "WARN",
  "costVariance" : -103968.45,
  "earnedValue" : 160814.0,
  "estimateAtCompletion" : 573779.7013,
  "costUnit" : {
    "id" : 1974,
    "name" : "Euro",
    "type" : "COST",
    "symbol" : "€"
  },
  "effortUnit" : {
    "name" : "Jour Homme",
    "type" : "EFFORT",
    "symbol" : "jh"
  }
  // sub-reports per project
  "children" : [ {
    "element" : {
      "id" : 188,
      "externalId" : "",
      "name" : "Demo",
      "type" : "project",
      ...
      "state" : {
        "val" : 18,
        "str" : "In Progress"
      },
      "appraisal" : {
        "rating" : 5,
        "comments" : "...",
        "lastUpdate" : "2018-11-15T20:31:32.588+0000"
      }
    },
    "progress" : 0.4521,
    "budgetedCost" : 212140.0,
    "actualCost" : 178065.69,
    "expenseBudget" : 34000.0,
    "expenseCost" : 12000.0,
    "incurredExpense" : 12000.0,
    "plannedEffort" : 404.0,
    ...
     // earned value indicators
    "earnedValue" : 95915.0,
    "bcws" : 20361.391,
    "bcwp" : 95915.0,
    "sv" : 75553.60,
    "cpi" : 0.538,
    "spi" : 4.71,
    "cpiToComplete" : 3.410,
    "scheduleVarianceAtCompletion" : 23,
    "estimateAtCompletion" : 393836.79  
  }, ...]
  
}

Project API /projects...

This API provides information related to a project.

:id in URL are placeholders for the actual id of the project.

List of Projects /projects.json

Returns the list of infos about all projects accessible by the authentified user.

Example: https://pma.timeperformance.com/api/v2/projects.json?archived=1

Parameter Type Description Required Default
archived boolean If set to true, archived projects will be included. no false

Response sample

[
	{
	  "id" : 1551,
	  "externalId" : "XX-6360",
	  "name" : "Demo Scrum",
	  "type" : "project",
	  "description" : "Ce projet est structuré selon la méthode Scrum avec des sprints de 2 semaines.\nLe projet consiste dans le développement d'un site web de réservation d'hotel en ligne.",
	  "priority" : 1,
	  "template" : false,
	  "projectType" : "INTERNAL", // PROJECT, INTERNAL, RECURRING
	  "archived" : false,
	  "folder" : "",           // folder = section or category
	  "sponsor" : "CustomerX", // sponsor = client
	  "state" : {
	    "val" : 21,
	    "str" : "in_progress"
	  }
	},
	...
]

Get project Id /projects/getIdFromName.txt

Returns a comma separated list of ids of projects matching the provided name.

Most project APIs requires project ids which are not displayed in the web interface. This API provides a simple way to retrieve the id from the project name. As project names are not unique in the application, the call may return a list of ids.

Example: https://pma.timeperformance.com/api/v2/projects/getIdFromName.txt

Parameter Type Description Required Default
name string Name of the project to search (case insensitive). yes

Response sample

-- one project --
32

-- several projects --
32,945

Project Assignments /projects/:id/assignments.json

Returns all half-day assignments to the project.

Example: https://pma.timeperformance.com/api/v2/projects/12/assignments.json

Response sample

[ 
// assignment of Alice to project Demo on 09/25/2017 AM
{
  "day" : "2017-09-25",
  "dayPart" : "AM",
  "user" : {
    "id" : 40,
    "externalId" : "USR-40",
    "name" : "Alice Jung",
    "type" : "user"
  },
  "to" : {
    "id" : 190,
    "name" : "Demo",
    "type" : "project"
  }
},
... ]

Project Baseline Report /projects/:id/baselineReport.json

Returns the main metrics of project baselines, current plan and forecast.

The returned data are the same as what is displayed in the page Plan vs Baseline in the web application.

Example: https://pma.timeperformance.com/api/v2/projects/32/baselineReport.json

Response sample

{
  "project" : {
    "id" : 188,
    "name" : "Demo",
    ...
  },
  "baselines" : [ {
    "name" : "Initial baseline",
    "timestamp" : "2017-06-25T20:51:39.218+0000",
    "plannedStart" : {
      "value" : "2017-07-03"
    },
    "plannedEnd" : {
      "value" : "2018-01-03"
    },
    "workload" : {
      "value" : {
        "val" : 419.0,
        "str" : "419.0 md",
        "unit" : "md"
      }
    },
    "cost" : {
      "value" : {
        "val" : 185240.0,
        "str" : "$185,240",
        "unit" : "$"
      }
    }
  } ],
  "currentPlan" : {
    "name" : "Current plan",
    "timestamp" : "2017-09-26T14:30:13.507+0000",
    "plannedStart" : {
      "value" : "2017-07-05",
      "variance" : {
        "val" : 2,
        "str" : "+2 d.",
        "unit" : "Day"
      }
    },
    "plannedEnd" : {
      "value" : "2018-01-28",
      "variance" : {
        "val" : 25,
        "str" : "+25 d.",
        "unit" : "Day"
      }
    },
    "workload" : {
      "value" : {
        "val" : 441.0,
        "str" : "441.0 md",
        "unit" : "md"
      },
      "variance" : {
        "val" : 0.05250596658711217,
        "str" : "+5%",
        "unit" : "%"
      }
    },
    "cost" : {
      "value" : {
        "val" : 195320.0,
        "str" : "$195,320",
        "unit" : "$"
      },
      "variance" : {
        "val" : 0.05441589289570287,
        "str" : "+5%",
        "unit" : "%"
      }
    }
  },
  "forecast" : {
    "name" : "Forecast",
    "plannedStart" : { },
    "plannedEnd" : {
      "value" : "2017-12-21",
      "variance" : {
        "val" : -13,
        "str" : "-13 d.",
        "unit" : "Day"
      }
    },
    "workload" : {
      "value" : {
        "val" : 456.963125,
        "str" : "457.0 md",
        "unit" : "md"
      },
      "variance" : {
        "val" : 0.09060411694510738,
        "str" : "+9%",
        "unit" : "%"
      }
    },
    "cost" : {
      "value" : {
        "val" : 281812.82158780616,
        "str" : "$281,813",
        "unit" : "$"
      },
      "variance" : {
        "val" : 0.5213389202537582,
        "str" : "+52%",
        "unit" : "%"
      }
    }
  }
}

Project Expenses /projects/:id/expenses.json

Returns the expenses on the project.

Example: https://pma.timeperformance.com/api/v2/projects/12/expenses.json

Response sample

[ 
	{
	  "id" : 468,
	  "type" : "expense",
	  "description" : "...",
	  "settled" : false,
	  "smoothed" : true,
	  "date" : "2018-09-16",
	  "amount" : {
	    "val" : 4000.0,
	    "str" : "€ 4000",
	    "unit" : "€"
	  },
	  "phase" : {
	    "id" : 221,
	    "type" : "phase",
	    ...
	  },
	  "stage" : {
	    "id" : 222,
	    "type" : "iteration",
	    ...
	  },
	  "deliverable" : {
	    "id" : 207,
	    "type" : "goal",
	    ...
	  }
	},
...
]

Project Progress Report /projects/:id/progressReport.json

Returns the progress report of the project.

The returned data are the same as what is displayed in the web application.

Example: https://pma.timeperformance.com/api/v2/projects/32/progressReport.json?withDeliverables=true

Parameter Type Description Required Default
withDeliverables boolean Request progress data about the planned deliverables.
Note: This parameter has been introduced to turn off by default the new capability in order to not impact current codes of API clients. It may be removed in the future as it will become the default behaviour.
no false

Response sample

{
 // total for the project
 "element" : {
    "id" : 188,
    "externalId" : "",
    "name" : "Demo",
    "type" : "project",
    "priority" : 1,
    "template" : false,
  ...
  },
  "progress" : 0.45, // means 45%
  "progressMode" : "WEIGHTED_SUM", // see note below
  "budgetedCost" : 212140.0,
  "actualCost" : 178065.69,
  "expenseBudget" : 34000.0,
  "expenseCost" : 12000.0,
  "incurredExpense" : 12000.0,
  "plannedEffort" : 404.0,
  "actualEffort" : 235.25,
  "remainingEffort" : 203.26,
  "plannedStart" : "2018-11-14",
  "actualStart" : "2018-08-20",
  "plannedEnd" : "2019-05-17",
  "costPercentage" : 0.839,
  "costRAG" : "KO",
  "effortPercentage" : 0.5823, // means 58%
  "effortRAG" : "KO",
  "scheduleVariance" : 57, // in days
  "costVariance" : -82150.64,
  "scheduleRAG" : "OK",
   // earned value indicators
  "earnedValue" : 95915.0,
  "bcws" : 20361.3,
  "bcwp" : 95915.0,
  "sv" : 75553.608,
  "cpi" : 0.53,
  "spi" : 4.710,
  "cpiToComplete" : 3.410,
  "scheduleVarianceAtCompletion" : 23, // in days
  "estimateAtCompletion" : 393836.7,
  "costUnit" : {
    "id" : 219,
    "name" : "Euro",
    "type" : "COST",
    "symbol" : "€"
  },
  "effortUnit" : {
    "id" : 218,
    "name" : "jour homme",
    "type" : "EFFORT",
    "symbol" : "jh"
  },
  // sub-reports for phases
  "children" : [ {
    "element" : {
        "id" : 281,
        "name" : "Design",
        "type" : "phase",
        ...
     },
    "progress" : 1.0,
    "budgetedCost" : 59040.0,
    "actualCost" : 136620.0,
    "plannedEffort" : 131.0,
    "actualEffort" : 189.0,
    ...,
    // sub-reports for stages
    "children" : [ {
      ...,
      // sub-reports for deliverables
      "children" : [ {
        ...
      }, ...]
    }, ...]
  },
    ...]
}

Note: progressMode attribute explains how the progress is calculated. The possible values are: MANUAL, TASK_RTD, TASK_COUNT, WORKLOAD, SCHEDULE and WEIGHTED_SUM.

Project Roadmap /projects/:id/roadmap.json

Returns the roadmap of the project as a hierarchical tree (project → phases → stages → deliverables → tasks)

Example: https://pma.timeperformance.com/api/v2/projects/32/roadmap.json?tasks=1&formatting=1

Parameter Type Description Required Default
tasks boolean Includes tasks for each deliverable. no false
legacy boolean If true, the deprecated format of the roadmap is returned. This format will be removed in a future release. no true
formatting boolean Activates the formatting of cost, effort, percentage and dates values according to project settings and user's locale. For instance, $3200.50 if formatting is true, 3200.5 otherwise. (legacy format only) no false

Response sample

{
"id" : 190,
"externalId" : "PROJ-190",
"name" : "Demo",
"type" : "project",
"description" : "...",
"path" : "",
"closed" : false,
"state" : "open",
"depth" : 0,
"stateText" : "En cours",
"scopeUnit" : {
  "id" : 218,
  "name" : "jour homme",
  "type" : "EFFORT",
  "symbol" : "jh"
},
"effortUnit" : {
  "id" : 218,
  "name" : "jour homme",
  "type" : "EFFORT",
  "symbol" : "jh"
},
"costUnit" : {
  "id" : 219,
  "name" : "Euro",
  "type" : "COST",
  "symbol" : "€"
},
"children" : [ {
	"id" : 220,
	"externalId" : "XX-6240",
	"name" : "Etude",
	"type" : "phase",
	"description" : "",
	"path" : "Etude",
	"closed" : true,
	"state" : "closed",
	"depth" : 1,
	"stateText" : "Terminé",
	"children" : [ {
		"id" : 221,
		"externalId" : "XX-6239",
		"name" : "Analyse",
		"type" : "iteration",
		"description" : "",
		"path" : "Etude » Analyse",
		"closed" : true,
		"state" : "closed",
		"depth" : 2,
		"stateText" : "Terminé",
		"children" : [ {
			"id" : 193,
			"externalId" : "XX-6301",
			"name" : "Plan Projet",
			"type" : "goal",
			"description" : "...",
			"path" : "Management » Plan Projet",
			"closed" : true,
			"state" : "closed",
			"depth" : 2,
			"stateText" : "Terminé",
			// Metrics are available on entities with type project, phase, iteration or goal
			"metrics" : {
				"effort" : 8.0,
				"cost" : 4160.0,      
				"missingEstimates" : false
			},
			// Effort estimates by profile in person-days available on entities with type project, phase, iteration or goal
			"effortByProfile" : [ {
				"effort" : 8.0,
				"profile" : {
					"id" : 22,
					"name" : "Chef de projet",
					...
				}
			} ],
			"tasks" : [ {
				"id" : 379,
				"name" : "Comité pilotage",
				"type" : "task",
				"description" : "",
				"performer" : {
					"id" : 32,
					"login" : "axel",
					"name" : "Axel Martin",
					...
				},
				"state" : "completed",
				"closed" : true,
				"effort" : 12.2
			},
			... ]
	 },
...
					

Project Summary /projects/:id/summary.json

Returns the full description of the project with all extra details as provided in the project summary page.

Extra details include: the team, observers, businessCase, related projects info...

Example: https://pma.timeperformance.com/api/v2/projects/32/summary.json

Response sample

{
  "id" : 190,
  "externalId" : "PRJ-01234",
  "name" : "Demo",
  "type" : "project",
  "description" : "Cet exemple montre l'utilisation de TimePerformance pour un projet suivant un cycle en cascade. fdsf",
  "priority" : 1,
  "template" : false,
  "projectType" : "INTERNAL", // PROJECT, INTERNAL, RECURRING
  "archived" : false,
  "folder" : "categ",
  "sponsor" : "Marketing Dpt",
  "creationDate" : "2015-11-14",
  "state" : {
    "val" : 21,
    "str" : "in_progress"
  },
  // Project health appraisal
  "appraisal" : {
    "rating" : 3, // 1 (= in danger) to 5 (= doing great).
    "comments" : "...",
    "lastUpdate" : "2016-06-17T08:43:12.447+0000"
  },
  "stakeholders" : "popo csdqdsfs",
  "businessCase" : "...",
  "outOfScope" : "...",
  "communicationPlan" : "...",
  "relatedProjects" : "...",
  "observers" : [ {
    "id" : 30,
    "login" : "alice",
    "name" : "Alice Jung",
    "firstname" : "Alice",
    "lastname" : "Jung",
    "email" : "alice@acme.test",
    "externalId" : "USR-30"
  } ],
  "projectManagers" : [ {
    "id" : 28,
    "login" : "pierre",
    "name" : "Pierre Durand",
    "firstname" : "Pierre",
    "lastname" : "Durand",
    "email" : "pierre@acme.test",
    "externalId" : "USR-28"
  } ],
  "teamMembers" : [ {
    "id" : 30,
    "login" : "alice",
    "name" : "Alice Jung",
    "firstname" : "Alice",
    "lastname" : "Jung",
    "email" : "alice@acme.test",
    "externalId" : "USR-30"
  }... ]
}

Project Tasks /projects/:id/tasks.json

Returns the tasks that are part of the project.

Example: https://pma.timeperformance.com/api/v2/projects/12/tasks.json?notClosed=1

Parameter Type Description Required Default
notClosed boolean If true, the list will only contain tasks that are not completed or cancelled. no false
periodStart Date periodStart and periodEnd paremeters allows to filter out tasks based on actual work during the period. Note that actual efforts of tasks are computed over the defined period.
The period may be defined with only one parameter as from periodStart or until periodEnd.
no
periodEnd Date See above no

Response sample

[ 

// first task
{
  "id" : 241,
  "type" : "task",
  
  "name" : "Tester l'impression",
  "description" : "",
  
  "performer" : {
    "id" : 36,
    "login" : "philippe",
    "name" : "Philippe Martin",
    "firstname" : "Philippe",
    "lastname" : "Martin",
    "email" : "philippe@acme.test"
  },
  
  "project" : {
    "id" : 190,
    "externalId" : "XX-6358",
    "name" : "Demo",
    "type" : "project"
  },
  
  // if phase level is activated
  "phase" : {
    "id" : 223,
    "externalId" : "XX-6370",
    "name" : "Lot 1",
    "type" : "phase"
  },
  
  // iteration = stage
  "iteration" : {
    "id" : 224,
    "externalId" : "XX-6371",
    "name" : "Réalisation lot 1",
    "type" : "iteration"
  },
  
  // goal = deliverable
  "goal" : {
    "id" : 205,
    "externalId" : "XX-6441",
    "name" : "Module 1",
    "type" : "goal"
  },
  
  // taskType = task template from the method (optional)
  "taskType" : {
    "id" : 83,
    "externalId" : "XX-6421",
    "name" : "Design the Solution",
    "type" : "taskdefinition"
  },
  
  // taskCategory = category in the method (optional)
  "taskCategory" : {
    "id" : 80,
    "externalId" : "TC-45",
    "name" : "Development",
    "type" : "taskcategory"
  },
  
  "state" : "ready",
  "closed" : false,
  "dueDate": "2015-02-23",
  "start" : "2015-02-19", // actual start
  "end" : "2015-02-23", // actual end
  "effort" : 13.7, // actual work in hours
  "stateText" : "A faire",
  
  // if there is a checklist for the task
  "steps" : [ {
	    "name" : "Write Code",
	    "done" : true
	  }, {
	    "name" : "Write Test",
	    "done" : false
	  }]

},

... (next tasks)

]

Project Team /projects/:id/team.json

Returns the list of project team members with profiles and cost rates.

Example: https://pma.timeperformance.com/api/v2/projects/32/team.json

Response sample

[ {
  "user" : {
    "id" : 37,
    "externalId" : "USR-37",
    "name" : "Alice Jung",
    "type" : "user",
    "login" : "alice",
    "firstname" : "Alice",
    "lastname" : "Jung",
    "email" : "alice-test@timeperformance.com",
    "extern" : false,
    "obsName" : "IT",
    "obsPath" : "ACME » IT",
    "profile": {
    	"id": 45678,
    	"name": "Analyst"
    }
  },
  // user's profile for the project can be different from user's general profile
  "profile" : {
    "id" : 20,
    "externalId" : "XX-6463",
    "name" : "Developper",
    "type" : "resourceprofile"
  },
  "cost" : {
    "val" : 460.0,
    "str" : "460 $",
    "unit" : "$"
  },
  "rate" : {
    "val" : "HOURLY",
    "str" : "per hour"
  },
  // rights can be PROJECT_MANAGER, MEMBER or null (= no access to the project)
  "rights" : {
    "val" : "MEMBER",
    "str" : "Team member"
  }
},
... ]

Project Time Series /projects/:id/actualsTimeseries.json

Returns the following timeseries: actual cost, actual progress and budgeted cost.

Note: if a value is not provided for a specific date, it can be easily calculated by interpolation.

Example: https://pma.timeperformance.com/api/v2/projects/32/actualsTimeseries.json

Response sample

{
  "currency" : {
    "name" : "Euro",
    "symbol" : "€",
    ...
  },
  "actualCosts" : [ {
    "date" : "2018-03-04",
    "value" : 0.0
  }, {
    "date" : "2018-03-05",
    "value" : 1450.0
  } ... ],
  "budgetedCosts" : [ {
    "date" : "2018-04-01",
    "value" : 0.0
  }, {
    "date" : "2018-04-06",
    "value" : 3066.6666666666665
  } ... ],
  "actualProgress" : [ ... {
    "date" : "2018-06-12",
    "value" : 0.38328476821192053 // means 38.3%
  }, {
    "date" : "2018-06-14",
    "value" : 0.38328476821192053
  } ... ]
}

Project Workload Plan /projects/:id/workloadplan.json

Returns planned workloads for each resource profile.

The returned data are a set of data series, one series per profile. Each series contains weekly values expressed in FTE unit (full-time employee).

Example: https://pma.timeperformance.com/api/v2/projects/32/workloadplan.json

Parameter Type Description Required Default
no parameters

Response sample

[ 
    {
        // ressource profile 
        "profile" : {
            "id" : 16,
            "externalId" : "XX-6596",
            "name" : "Analyste",
            "type" : "resourceprofile"
          },
          
        "workloadWeeklySeries" : [ {
            "date" : "2015-12-28",  // first day of the week
            "value" : 1.2           // value smoothed over the week
          }, {
            "date" : "2016-01-04",
            "value" : 1.2
          }, {
            "date" : "2016-01-11",
            "value" : 1.2
          } ... ]
    }, ...
]

User API /users...

This API provides information related to a user. The provided information currently are: Time Tracking Report and Assignement Schedule.

:id in URL are placeholders for the actual id of the user.

List of Users /users.json

Returns the list of users.

Example: https://pma.timeperformance.com/api/v2/users.json

Response sample

[
	{
  		"id" : 22,
		"login" : "pierre",
		"name" : "Pierre Durand",
		"firstname" : "Pierre",
		"lastname" : "Durand",
		"email" : "pierre@acme.com",
		"obsName" : "R&D",       // Department's name
		"obsPath" : "IT » R&D",  // Department's hierarchical name
		"profile" : {
			"id": 4567,
			"name": "Project Manager"
		}
	},
	...
]

Assignment Schedule /users/:id/assignments.json

Returns a user's assignement schedule.

Example: https://pma.timeperformance.com/api/v2/users/165/assignments.json?firstDay=2015-01-01&lastDay=2015-03-31

Parameter Type Description Required Default
firstDay Date First day of the time period yes
lastDay Date Last day of the time period yes

Response sample

[ {
  "day" : "2018-09-03",
  "dayPart" : "AM",
  "user" : {
    "id" : 38,
    "externalId" : "USR-38",
    "name" : "Peter Pan",
    "type" : "user"
  },
  "to" : {
    "id" : 184,
    "externalId" : "...",
    "name" : "Neverland",
    "type" : "project"
  }
},
...

Tasks /users/:id/tasks.json

Returns a filtered list of tasks assigned to the person.

Access is restricted to the person or a manager of the person.

Example: https://pma.timeperformance.com/api/v2/users/32/tasks.json?periodStart=2015-01-01&periodEnd=2015-01-31

Parameter Type Description Required Default
notClosed boolean If true, the list will only contain tasks that are not completed or cancelled. no false
periodStart Date periodStart and periodEnd paremeters allows to filter out tasks based on actual work during the period. Note that actual efforts of tasks are computed over the defined period.
The period may be defined with only one parameter as from periodStart or until periodEnd.
no
periodEnd Date See above no

Response sample

[ 

// first task
{
  "id" : 241,
  "type" : "task",
  
  "name" : "Tester l'impression",
  "description" : "",
  
  "performer" : {
    "id" : 36,
    "login" : "philippe",
    "name" : "Philippe Martin",
    "firstname" : "Philippe",
    "lastname" : "Martin",
    "email" : "philippe@acme.test"
  },
  
  "project" : {
    "id" : 190,
    "externalId" : "XX-6358",
    "name" : "Demo",
    "type" : "project"
  },
  
  // if phase level is activated
  "phase" : {
    "id" : 223,
    "externalId" : "XX-6370",
    "name" : "Lot 1",
    "type" : "phase"
  },
  
  // iteration = stage
  "iteration" : {
    "id" : 224,
    "externalId" : "XX-6371",
    "name" : "Réalisation lot 1",
    "type" : "iteration"
  },
  
  // goal = deliverable
  "goal" : {
    "id" : 205,
    "externalId" : "XX-6441",
    "name" : "Module 1",
    "type" : "goal"
  },
  
  // taskType = task template from the method (optional)
  "taskType" : {
    "id" : 83,
    "externalId" : "XX-6421",
    "name" : "Design the Solution",
    "type" : "taskdefinition"
  },
  
  // taskCategory = category in the method (optional)
  "taskCategory" : {
    "id" : 80,
    "externalId" : "TC-45",
    "name" : "Development",
    "type" : "taskcategory"
  },
  
  "state" : "ready",
  "closed" : false,
  "dueDate": "2015-02-23",
  "start" : "2015-02-19", // actual start
  "end" : "2015-02-23", // actual end
  "effort" : 13.7, // actual work in hours
  "stateText" : "A faire",
  
  // if there is a checklist for the task
  "steps" : [ {
	    "name" : "Write Code",
	    "done" : true
	  }, {
	    "name" : "Write Test",
	    "done" : false
	  }]

},

... (next tasks)

]

Time Report /users/:id/timeReport.json

Returns time spent on projects or activities day by day.

Data found in time reports are the same as those provided in user's monthly activity report, except that covered time period is free.

The typical usage is for importing time entered in TimePerformance into an ERP or HR system. For such usage, time report may be equalized. For instance, it can be requested that the total number of worked hours per day is always 8 hours, 4 hours (half day) or 0 hour.

Example: https://pma.timeperformance.com/api/v2/users/192/timeReport.json?firstDay=2015-01-01&lastDay=2015-03-31

Parameter Type Description Required Default
firstDay Date First day of the time period yes
lastDay Date Last day of the time period yes
hoursPerDay float If provided, time report will be equalized so that the number of worked hours per day is constant. no
halfDayThreshold float Used in conjonction with parameter hoursPerDay.
Set the numbers of worked hours under which time spent for a day will be equalized to half a work day, so to speak half of hoursPerDay.
no 1/2 hoursPerDay

Response sample

{
  "user" : {
    "id" : 192,
    "login" : "peter",
    "name" : "Peter Black",
    "firstname" : "Peter",
    "lastname" : "Black",
    "email" : "peter@acme.com"
  },
  "firstDay" : "2014-10-26",
  "lastDay" : "2014-11-01",
  "timeByProjects" : [ {
    "activity" : {
      "id" : 249,
      "externalId" : "XX-6358",
      "name" : "Demo",
      "type" : "project"
    },
    "entries" : [ {
      "day" : "2014-10-27",
      "hours" : 4.0
    }, {
      "day" : "2014-10-28",
      "hours" : 8.0
    }, {
      "day" : "2014-10-29",
      "hours" : 8.0
    } ]
  }, {
    "activity" : {
      "id" : 1172,
      "externalId" : "XX-777",
      "name" : "Web Site",
      "type" : "project"
    },
    "entries" : [ {
      "day" : "2014-10-26",
      "hours" : 7.2833333
    }, {
      "day" : "2014-10-27",
      "hours" : 3.25
    } ]
  } ],
  
  "timeByNonProjectActivities" : [ {
    "activity" : {
      "id" : 7,
      "externalId" : "XX-6534",
      "name" : "Congés",
      "type" : "npactivity"
    },
    "entries" : [ {
      "day" : "2014-10-30",
      "hours" : 7.5
    } ]
  }... 
  ],
  
  "total" : [ {
    "day" : "2014-10-26",
    "hours" : 7.2833333
  }, {
    "day" : "2014-10-27",
    "hours" : 7.25
  }, {
    "day" : "2014-10-28",
    "hours" : 8.0
  }, {
    "day" : "2014-10-29",
    "hours" : 8.0
  }, {
    "day" : "2014-10-30",
    "hours" : 7.5
  }, {
    "day" : "2014-10-31",
    "hours" : 7.5
  } ]
}

Timesheet /users/:id/timesheet.json

Returns time spent on project tasks or activities day by day.

Timesheet API is the most detailed time report. It provides times at task level, whereas the time report above provides times at project level.

As for time report, it may be equalized. For instance, it can be requested that the total number of worked hours per day is always 8 hours, 4 hours (half day) or 0 hour.

Example: https://pma.timeperformance.com/api/v2/users/192/timesheet.json?firstDay=2015-01-01&lastDay=2015-03-31

Parameter Type Description Required Default
firstDay Date First day of the time period yes
lastDay Date Last day of the time period yes
hoursPerDay float If provided, time report will be equalized so that the number of worked hours per day is constant. no
halfDayThreshold float Used in conjonction with parameter hoursPerDay.
Set the numbers of worked hours under which time spent for a day will be equalized to half a work day, so to speak half of hoursPerDay.
no 1/2 hoursPerDay

Response sample

{
  "user" : {
    "id" : 30,
    "login" : "alice",
    "name" : "Alice Jung",
    "firstname" : "Alice",
    "lastname" : "Jung",
    "email" : "alice@acme.test"
  },
  "firstDay" : "2016-02-01",
  "lastDay" : "2016-02-29",
  "timeByProjects" : [ {
    "project" : {
      "id" : 190,
      "externalId" : "XX-6358",
      "name" : "Demo",
      "type" : "project"
    },
    "timeByTasks" : [ {
      "activity" : {
        "id" : 411,
        "name" : "Estimer la charge",
        "type" : "task",
        "description" : "",
        "performer" : {
          "id" : 30,
          "login" : "alice",
          "name" : "Alice Jung",
          "firstname" : "Alice",
          "lastname" : "Jung",
          "email" : "alice@acme.test"
        },
        "state" : "completed",
        "closed" : true,
        "project" : {
          "id" : 190,
          "externalId" : "XX-6358",
          "name" : "Demo",
          "type" : "project"
        },
        "phase" : {
          "id" : 220,
          "externalId" : "XX-6368",
          "name" : "Etude",
          "type" : "phase"
        },
        "iteration" : {
          "id" : 221,
          "externalId" : "XX-6367",
          "name" : "Analyse",
          "type" : "iteration"
        },
        "goal" : {
          "id" : 193,
          "externalId" : "XX-6432",
          "name" : "Plan Projet",
          "type" : "goal"
        },
        "start" : "2015-12-28",
        "end" : "2016-02-01",
        "stateText" : "Terminée"
      },
      "entries" : [ {
        "day" : "2016-02-01",
        "hours" : 1.75
      } ... ]
    } ... ]
  } ],
  "timeByNonProjectActivities" : [ {
    "activity" : {
      "id" : 7,
      "externalId" : "XX-6534",
      "name" : "Congés",
      "type" : "npactivity"
    },
    "entries" : [ {
      "day" : "2016-02-26",
      "hours" : 7.0
    } ]
  } ],
  "total" : [ {
    "day" : "2016-02-01",
    "hours" : 7.0
  }, {
    "day" : "2016-02-02",
    "hours" : 7.0
  }, {
    "day" : "2016-02-03",
    "hours" : 7.0
  }... ]
}

To-do List /users/:id/todolist.json

Returns the to-do list of the person.

The to-do list is the list of tasks assigned to the person and related to open deliverables.

Access is restricted to the person or a manager. Project managers can also access to team members' to-do lists for their projects (project parameter required).

Example: https://pma.timeperformance.com/api/v2/users/32/todolist.json

Parameter Type Description Required Default
project integer Id of a project. If set, the returned list only contains tasks related to the project. no

Response sample

[ 

// first task
{
  "id" : 241,
  "type" : "task",
  
  "name" : "Tester l'impression",
  "description" : "",
  
  "performer" : {
    "id" : 36,
    "login" : "philippe",
    "name" : "Philippe Martin",
    "firstname" : "Philippe",
    "lastname" : "Martin",
    "email" : "philippe@acme.test"
  },
  
  "project" : {
    "id" : 190,
    "externalId" : "XX-6358",
    "name" : "Demo",
    "type" : "project"
  },
  
  // if phase level is activated
  "phase" : {
    "id" : 223,
    "externalId" : "XX-6370",
    "name" : "Lot 1",
    "type" : "phase"
  },
  
  // iteration = stage
  "iteration" : {
    "id" : 224,
    "externalId" : "XX-6371",
    "name" : "Réalisation lot 1",
    "type" : "iteration"
  },
  
  // goal = deliverable
  "goal" : {
    "id" : 205,
    "externalId" : "XX-6441",
    "name" : "Module 1",
    "type" : "goal"
  },
  
  // taskType = task template from the method (optional)
  "taskType" : {
    "id" : 83,
    "externalId" : "XX-6421",
    "name" : "Design the Solution",
    "type" : "taskdefinition"
  },
  
  // taskCategory = category in the method (optional)
  "taskCategory" : {
    "id" : 80,
    "externalId" : "TC-45",
    "name" : "Development",
    "type" : "taskcategory"
  },
  
  "state" : "ready",
  "closed" : false,
  "dueDate": "2015-02-23",
  "start" : "2015-02-19", // actual start
  "end" : "2015-02-23", // actual end
  "effort" : 13.7, // actual work in hours
  "stateText" : "A faire",
  
  // if there is a checklist for the task
  "steps" : [ {
	    "name" : "Write Code",
	    "done" : true
	  }, {
	    "name" : "Write Test",
	    "done" : false
	  }]

},

... (next tasks)

]