Time-phased Assignments allow a resource's effort to be distributed across specific periods of time instead of being spread evenly across the entire duration of a task.

This feature is supported only for tasks within the Schedule. Time-phased assignments cannot be imported for other work item types such as Backlog Items, Risks, Issues, or Actions.

The Migration Tool imports time-phased assignments after the Plan and Work Plan have already been imported.

Migration Tool Configuration

The Migration Tool includes the following additions to support time-phased assignments:

• Tabular Data Field
  • WorkPlan Assignment Items Import File Name
• Field Mapping Table
  • WorkItemAssignmentsMigration - WorkItemAssignments
• Migration Strategy
  • ImportWorkPlanTimePhasedAssignments

The WorkPlan Assignment Items file must be provided as a CSV UTF-8 file.

Supported Field Mappings

The following fields can be  within the CSV file, WorkItemAssignmentsMigration → WorkItemAssignments table.

CSV Row Structure

Each row in the Time-phased Assignments CSV represents a single resource assigned to a single time-phased segment of a task.

A single CSV row supports only one value for each assignment-related field.

To import multiple resources or multiple time-phased segments for the same task, create a separate CSV row for each resource and segment combination.

A task has two assigned resources and two time periods. Each resource and time period combination must be represented as its own row.

Field Descriptions

Unique ID

The Unique ID identifies the task within the Schedule.

This value must reference an existing task in the Schedule. Time-phased assignments cannot create new tasks.

If the specified Unique ID cannot be found, the row is skipped and processing continues for the remaining records.

Example log message:

Task or Item not found in OnePlan.

Plan External ID

The Plan External ID identifies the destination plan.

This value must match the Plan External ID used during both the Plan import and the Work Plan import.

If the plan cannot be found, the import logs an error similar to:

[GetPlanByExternalId]: Plan External ID '{Plan External ID}' does not exist in OnePlan.

Assigned To

The Assigned To value should contain the resource's email address.

The resource must already exist in OnePlan.

Importing time-phased assignments updates the task assignment to the specified resource, even if a different resource was assigned during the original Work Plan import.

Important

When importing multiple time-phased segments for the same task, all segments must contain valid data before the task is updated.

For example, if one segment references a resource that does not exist in OnePlan, the entire task is skipped. None of the time-phased segments for that task are imported, even if the remaining segments contain valid data.

Before importing, verify that all referenced resources exist in OnePlan and that all rows associated with the same task contain valid values.

Start and Due

Each row represents a single time-phased segment and requires both a Start and Due date.

Include timestamps whenever possible

If only a date is provided, OnePlan assumes the time begins at 12:00 AM.

Because calendars, holidays, weekends, and working hours may vary, it is strongly recommended to include timestamps with every Start and Due value.

For example:

Tasks that start and finish on the same day

If the Start and Due dates are identical and no timestamps are supplied, the import fails because the task would begin and end at the exact same moment.

For single-day segments, timestamps are required.

Effort

The Effort value represents the amount of work assigned to the individual time-phased segment defined by that row in the CSV.

Each row specifies the effort for a single segment. The total effort for a task is determined by summing the effort from all imported segments across all assigned resources.

For accurate results, the combined effort of all segments should equal the task's total Effort value. If the imported segment effort does not match the task's overall effort, the values displayed for the task and its time-phased assignments may be inconsistent.

Example

A task has a total Effort of 40 hours and is assigned to one resource. The task could be imported as two (or more) time-phased segments:

The combined segment effort (24 + 16) equals the task's total Effort of 40 hours.

Units for Assignment

Units for Assignment represents the resource's overall allocation for the entire task and is displayed as a percentage in the OnePlan user interface.

Only one assignment value exists for each resource on a task.

If multiple rows for the same task contain different Units for Assignment values, the first value processed is used.

Units for Segment

Units for Segment represents the allocation percentage for an individual time-phased segment.

The value stored through the API matches the value supplied in the CSV.

However, the percentage displayed in the OnePlan interface may differ if the working calendar or daily working hours differ from the assumptions used during import.

If Units for Segment is not provided, OnePlan automatically calculates the value based on:

• Effort
• Duration
• Working hours per day

The calculation is:

Units (%) = (Effort ÷ (Duration × Hours Per Day)) × 100

Example:

• Effort = 40 hours
• Duration = 10 working days
• Hours per day = 8

Units = (40 ÷ 80) × 100 = 50%

Work Item Type

The Work Item Type field is optional.

Time-phased assignments currently apply only to Schedule tasks.

If this field is omitted, the Migration Tool assumes the referenced item is a Schedule task.

Import Behavior

The Migration Tool determines missing values using the following logic.