In Project Essentials, values can be entered for a project just for the time frame defined by the cost start and cost end dates (similar for benefits). The end-user can define the start and end dates by means of the Financial Timeline web part.
From an API perspective, the same functionality can be achieved by using the UpdateInstanceCostTimeline(Guid projectUid, DateTime startDate, DateTime endDate, TranslationType valuesTranslationType) method from the ProjectPhases web service:
- projectUid – the indentifier of the project for which you want to update the timeline (this must be a valid GUID, for a project that has a financial instance, otherwise a NoPermissions exception will be thrown)
- startDate – the new start date for the timeline
- endDate – the new end date for the timeline
- valuesTranslationType – this will determine how the values will be handled for the timeline change; this corresponds to the option that the user would select in the Cost Adjustment Type drop-down list in the Financial Timeline ribbon tab when using the web part to modify the timeline
TranslationType in an enum defined in the UMT.CostModule.Library.Data namespace, with the following options:
- Crop – will cut cost data to only the newly created timeline for all over-lapping periods
- Extend – will not affect existing values, newly created periods will be added as a result of timeline changes with no values
- Move – will translate the data from the old timeline to the new timeline, given that the new timeframe has the same or more time periods and working days compared to the previous
- Redistribute – redistributes the cost data while keeping the same total cost for the project
The method is fairly straight forward to use, however some aspects should be considered:
- the governance process can enforce that the cost start and end dates must correspond to the project start and end dates otherwise you will get an InvalidSettingsForInstance error; to check this you should verify that the AllowDifferentCostTimeline property for the CostInfo.cmInstances row corresponding to the current project is set to false (you can get this by using the ReadProjectInstance method in the ProjectIntegration service); to get the project start and end dates, you should consider the PROJ_INFO_START_DATE and the PROJ_INFO_FINISH_DATE properties on the ProjectDateSet.Project row, or, if these are null, check the TASK_START_DATE and TASK_FINISH_DATE properties for the ProjectDateSet.Task row of the project summary task (use the PSI Project service ReadProjectEntities method to get the project information)
- once the project reaches execution and you have at least one actuals period, you are unable to make changes that would affect the budget values for the project; in this regard, you can only move the cost end date into the future, for the valuesTranslationType use Extend only
- if the project does not correspond to one of the situations above, there are several rules to determine which values are acceptable for the values translation type
|
TranslationType |
Comment |
|
NONE |
To be used when timeline does not exist and is created. |
|
REDISTRIBUTE |
Always available if the original timeline exists. |
|
EXTEND |
The new dates extent the current timeline: · newStartDate == originalStartDate && newEndDate > originalEndDate · newStartDate < originalStartDate && newEndDate == originalEndDate · newStartDate < originalStartDate && newEndDate > originalEndDate |
|
MOVE |
The new time line must have different start date and different end date (newStartDate > originalStartDate && newEndDate > originalEndDate), the new timeline length must be greater or equal than the old one and the number of periods in the new timeline must be greater or equal than the number of periods in the old timeline. |
|
CROP |
The new timeline is shorter than the old one and both ends of the new interval must fall inside of the old timeline (one of them can be at the edge, but not both at the same time): · newStartDate > originalStartDate && newEndDate == originalEndDate · newStartDate ==originalStartDate && newEndDate < originalEndDate · newStartDate > originalStartDate && newEndDate < originalEndDate |
The sample application provided with the previous article has been updated to also include functionality for timeline changes.
What do you think?
Iulian
This post is very helpful but I have a question. For the new PE 2012 wasn’t the Financial Timeline PDP removed from the release? (not sure)….
In that case would the API still work as you have mentioned?
Thanks!