ProjectData - Project OData service reference

ProjectData is a WCF Data Service, also known as an OData service. The ProjectData service is implemented with the OData V3 libraries.

The ProjectData service enables REST queries and a variety of OData client libraries to make both online and on-premises queries of reporting data from a Project Web App instance. For example, you can directly use a REST query in web browsers, or use JavaScript to build web apps and client apps for mobile devices, tablets, PCs, and Mac computers. Client libraries are available for JavaScript, the Microsoft .NET Framework, Microsoft Silverlight, Windows Phone 8, and other languages and environments. In Project Server 2013, the ProjectData service is optimized to create pivot tables, pivot charts, and PowerView reports for business intelligence by using the Excel 2013 desktop client and Excel Services in SharePoint. For more information, see Use Excel 2013 to create a new Project Online report and Server Reporting in PWA.

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.

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 from the http://<pwa_site>/_api/ProjectData/$metadata endpoint (example: https://contoso.com/sites/pwa/\_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://<pwa_site>/_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 ~/_api/ProjectData/$metadata query results include the AssociationSet elements, they are used internally by the OData implementation for the ProjectData service, and are not documented.

Limits for ProjectData queries

There are limits to the number of entities that can be returned in one query of the ProjectData service. The following table shows the default per-query limits for on-premises and online instances.

For on-premises instances of Project Server, you can use the Get-SPProjectOdataConfiguration command in Windows PowerShell to get 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 on-premises instances of Project Server, 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 entity sets. For example, run the SharePoint 2013 Management Shell as an administrator, and then run the following command:

Set-SPProjectOdataConfiguration -EntitySetName Projects -PageSizeOverride 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):

  https://ServerName/ProjectServerName/_api/ProjectData/Projects?
      $filter=ProjectStartDate gt datetime'2012-01-01T00:00:00'&
      $orderby=ProjectName&
      $select=ProjectName,ProjectStartDate,ProjectFinishDate,ProjectCost
  

• 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):

  https://ServerName/ProjectServerName/_api/ProjectData
      /Projects(guid'263fc8d7-427c-e111-92fc-00155d3ba208')/Assignments
  

• 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):

  https://ServerName/ProjectServerName/_api/ProjectData
      /Issues?$skip=10&$top=10&$orderby=AssignedToResource
  

  For more information, see OData System Query Options Using the REST Endpoint.

For more information about query string options such as $filter, $orderby, $skip, and $top, see also OData URL conventions.

Reference

• Introducing OData

• OData protocol

• OData URL conventions

See also

Other resources

Plan user access in Project Server 2013

OData System Query Options Using the REST Endpoint

Set-SPProjectOdataConfiguration

Use Excel 2013 to create a new Project Online report

Server Reporting in PWA