Developing Project Essential 2012 Applications – Updating Actual Values

Code Samples, Project Essentials, SDK

Most project lifecycles have a Manage phase (execution) which involves the ongoing monitoring of the selected projects. Quality delivery of projects is typically measured by the project’s performance to delivering in scope, within budget and on schedule. Project Essentials enables team members to update their projects with actual quantities for the current period to help manage and evaluate project performance from one reporting period to the next. Actuals (effective) are controlled using an approval workflow; after a period is submitted, designated approvers can review/reject the submitted actual quantities.

Reporting period lengths are controlled by the granularity that you have set for the stage in the workflow that is marked as an execution. In Project Essentials 2012 the execution granularity cannot be changed from one stage to another. This functionality was added starting with Project Essentials 2010 CU7.

Actuals values can be added for each Enterprise Financial Type, as long their lifecycle is configured as “Budget, Actuals and Forecast”.

EFT lifecycle

Once a project enters execution, the first granular period will be automatically opened.

In the user interface, actuals can be set from the Actuals Cost web part. After filling the values, the reporting period can be submitted for approval or it can be directly approved. Submitting or approving a period opens the next one for edit (according to the settings). A period can be reopened manually or automatically if it is rejected. All this actions are available in the Period Actions tab from ribbon.

Actuals Ribon

An approved or submitted period can also be “Open for Edit”. This operation can be performed only by a user that has “Edit Project Actual Values for Approved or Submitted Periods” permission. The user will be able to edit values for submitted or approved periods, without changing the status of the period.

From the API point-of-view you can accomplish the same functionality using UpdateProjectFinancialValues(Values valuesDataSet, Guid eftUid) method from ProjectValuesService web service:

  • valuesDataSet – a dataset containing the values to update
  • eftUid – the unique identifier of the Enterprise Financial Type

For each submitted period tasks are added in the Workflow Approvals page in Project Server.

Actual task in WA page

Designated approvers can review/reject the submitted actual quantities by going to the Actuals Approval page.

Approve-reject task

When a period is submitted or approved the next Reporting period is opened. From the API perspective this can be achieved using the SetActualPeriodStatus(Guid projectUid, Guid enterpriseFinancialTypeUid, Guid financialDimensionUid, DateTime startDate, DateTime endDate, UMT.CostModule.Library.Core.PeriodStatus status) method from the GranularityService web service:

  • projectUid – used to identify the project Server project instance
  • enterpriseFinancialTypeUid – used to identify the Enterprise Financial Type
  • financialDimensionUid – used to identify the Financial Dimension
  • startDate – represents the start date of the reporting period
  • endDate – represents the end date of the reporting period
  • status – used to set the status of the reporting period

PeriodStatus is an enum defined in UMT.SDKSamples.Services.CMSI.Granularity namespace with the next oprions:

  • Any – default value
  • Opened – will open the reporting period
  • Submitted – will submit the reporting period for approval
  • Approved – will approve the reporting period and opens the next period

If the project is not in execution or the start date does not correspond to a reporting period start date you will get a NoReportingPeriods error.

What do you think?