ProjectData - Project 2013 OData service reference
Updated: February 19, 2013
The Open Data Protocol (OData) reference for Project Server 2013 documents the entity data model (EDM) for the ProjectData service and shows how to use LINQ queries and REST queries to get report data.
Applies to: Project Server 2013
ProjectData is a WCF Data Service, also known as an OData service. The ProjectData service is implemented with the OData V3 libraries.
When Project Server 2013 or Project Online is in Project permission mode, you can explicitly grant or deny access to the OData feed for specified Project Web App users. For example, on the Edit User page in Project Web App, expand the Global Permissions section, and then in the General section, select the Access Project Server Reporting Service check box in the Allow column.
When Project Server is in the default SharePoint permission mode, the Security Categories section and Global Permissions section are not available on the Edit User page.
In the default SharePoint permission mode, not all Project Web App users have access to the OData feed. Only users in the following groups have access: Portfolio Viewers, Portfolio Managers, and Administrators. Access cannot be managed for individual entities in the OData feed; that is, if a user has access to the OData service, she can get reporting data that is published for all of the projects, resources, tasks, and other entities. For more information about the permission modes, see Plan user access in Project Server 2013.
You can access the ProjectData service through a Project Web App URL. The XML structure of the EDM is available through http://ServerName/ProjectServerName/_api/ProjectData/$metadata. To view a feed that contains the collection of projects, for example, you can use the following REST query in a browser: http://ServerName/ProjectServerName/_api/ProjectData/Projects. When you view the webpage source in the browser, you see the XML data for each project, with properties of the Project entity type that the ProjectData service exposes.
The EDM of the ProjectData service is an XML document that conforms to the OData specification. The EDM shows the entities that are available in the reporting data and the associations between entities. The EDM includes the following two Schema elements:
The Schema element for the ReportingData namespace defines EntityType elements and Association elements:
EntityType elements: Each entity type, such as Project and Task, specifies the set of properties, including navigation properties, that are available for that entity. For example, task properties include the task name, task GUID, and project name for that task. Navigation properties define how a query for an entity such as Project is able to navigate to other entities or collections, such as Tasks within a project. Navigation properties define the start role and end role, where roles are defined in an Association element.
Association elements: An association relates one entity to another by endpoints. For example, in the Project_Tasks_Task_Project association, Project_Tasks is one endpoint that relates a Project entity to the tasks within that project. Task_Project is the other endpoint, which relates a Task entity to the project in which the task resides.
The Schema element for the Microsoft.Office.Project.Server namespace includes just one EntityContainer element, which contains the child elements for entity sets and association sets. The EntitySet element for Projects represents all of the projects in a Project Web App instance; a query of Projects can get the collection of projects that satisfy a filter or other options in a query.
An AssociationSet element is a collection of associations that define the primary keys and foreign keys for relationships between entity collections. Although the ~/ProjectData/$metadata query results include the AssociationSet elements, they are used internally by the OData implementation for the ProjectData service, and are not documented.
There are limits to the number of entities that can be returned in one query of the ProjectData service. The default maximum page size is 100, but some entities have an override for a larger value. For example, the Projects entity set and the Tasks entity set each have a default limit of 100 entities per query, and the Issues entity set has a default limit of 200.
The entity set reference topics, such as EntitySet element: Projects, show the default query limit. You can also use the Get-SPProjectOdataConfiguration command in Windows PowerShell to get information about the query limits for entities in the ProjectData service. For example, on the Project Server computer, run SharePoint 2013 Management Shell as an administrator, and then run the following command. Results are shown below the command.
(Get-SPProjectOdataConfiguration).EntitySetsWithMaxPAgeSizeOverride Key Value --- ----- AssignmentBaselineTimephasedDataSet 200 ProjectBaselines 200 ResourceTimephasedDataSet 200 TaskBaselineTimephasedDataSet 200 BusinessDrivers 200 BusinessDriverDepartments 200 Prioritizations 200 PrioritizationDrivers 200 PrioritizationDriverRelations 200 PortfolioAnalyses 200 PortfolioAnalysisProjects 200 CostConstraintScenarios 200 ResourceConstraintScenarios 200 CostScenarioProjects 200 ResourceScenarioProjects 200 Issues 200 Risks 200 Deliverables 200 TimeSet 200 ProjectWorkflowStageDataSet 200 TimesheetClasses 200 TimesheetPeriods 200
For a Project Web App instance that contains a large number of entities, such as projects, assignments, or tasks, you should limit the data returned in at least one of the following ways. If you don't limit the data returned, the query can exceed the default limits and affect server performance.
Use a $filter URL option, or use $select to limit the data. For example, the following query filters by project start date and returns only four fields, in order of the project name (the query is all on one line):
Get an entity collection by using an association. For example, the following query internally uses the Project_Assignments_Assignment_Project association to get all of the assignments in a specific project (all on one line):
Do multiple queries to return data one page at a time, by using the $top operator and the $skip operator in a loop. For example, the following query gets issues 11 through 20 for all projects, in order of the resource who is assigned to the issue (all on one line):
For more information, see OData System Query Options Using the REST Endpoint. You can also use the Set-SPProjectOdataConfiguration command in Windows PowerShell to override the default query page size for any specified entity set, or override the default page size for all of the 33 entity sets. For example, run the SharePoint 2013 Management Shell as an administrator, and then run the following command:
For more information about query string options such as $filter, $orderby, $skip, and $top, see also OData: URI conventions.
The ProjectData service does not implement the $links query option or the $expand query option. Excel 2013 internally uses the Association elements and the AssociationSet elements in the entity data model to help create associations between entities, for pivot tables and other constructs.
Querying OData feeds for Project Server 2013 reporting data shows several ways to query the ProjectData service.
ReportingData elements includes the list of EntityType elements and Association elements.
Microsoft.Office.Project.Server elements includes the EntityContainer element, which contains the EntitySet element and the AssociationSet element.