Task History Definition
This article describes the definition of the task history record that is stored in Dataverse in the Project History table. A task history record represents a change to a task.
"Edit Type" defines the type of history record.
| Syntax | Description |
|---|---|
| TaskCreated | represents when the task is created |
| TaskEdited | represents when the task is edited |
| TaskDeleted | represents when the task is deleted |
| Undo | represents when a change has been undone |
| Redo | represents when a change has been redone |
| DependentEdit | represents when a task modified because of a change to another task |
History Records
All history records share a common set of fields include:
| Field | Description |
|---|---|
| Project | the project the history is related to |
| Project Task | the task the history is related to. It's blank if the task is deleted |
| XrmUserId | the Xrm User that made the change to the task |
| Timestamp | the date and time the change was generated |
| Edit Type | the type of history record |
| Details | containing the history data in a JSON format |
The following sections describe what the Details payload field contains depending on the type of history record and what was edited. For the descriptions of the columns within the Details, review Export Project Content Definition
TaskCreated details
The record is created when the task is created. The payload is empty.
TaskDeleted details
Contains a single property "name", which is the name of the task when it was deleted.
Example:
{"name":"Pour concrete"}
Undo/Redo details
A "revisions" property with an array value holding all the revision numbers that were undone or redone. The number corresponds to the suffix in the revision property of the history record.
Example:
{"revisions":[11,12]}
Which matches to the history record with revision record suffix (0000000011) in:
msxrm\_orgxxxyyyy.crm.dynamics.com\_ff69bc0e-3f66-41c3-b40c-aa3035517e38\_0000000011
TaskEdited details
TaskEdited represents direct property edits on a task and creates, deletes, and edits to any task child items, for example, checklist items, attachments, assignments, links, and so on.
Direct task field edits
The details have a "field" property with a JSON object value. That object has the changed property names as keys (there can be multiple task properties edited in a single user action), with an object as the value. That property object has a "previous" and "updated" keys with the values having the old and new values of the property.
Example:
{
"fields": {
"name": {
"previous": "Pour concrete",
"updated": "Eat donuts"
}
}
}
For large properties (for example notes assignment "totalWorkContour"), an empty JSON is emitted and not the previous/updated values.
Example:
{
"fields": {
"notes": {}
}
}
Task edits that complete a task
Any property edit that completes a task also adds a completed boolean property.
Example:
{
"fields": {
"percentComplete": {
"previous": 75,
"updated": 100
}
},
"completed": true
}
Task child element edits
Child elements are similar to field edits but the key is the navigation property name and value is an array. The items in the array can be creates (has a "created":true property), deletes ("deleted":true property), or edits (no created or deleted, but list of edited properties). Created or deleted child elements have a set of minimum properties needed to render the item with values directly set on the property. Edits have the same format as field edits on the task with the previous and updated values.
Example create:
{
"fields": {
"checklistItems": [
{
"id": "f4be3c03-bc04-ee11-83c4-e04f43e61e09",
"created": true,
"name": "checklistItem1"
}
]
}
}
Example edit:
{
"fields": {
"checklistItems": [
{
"id": "54219e93-bd04-ee11-83c4-e04f43e61e09",
"completed": {
"previous": false,
"updated": true
}
}
]
}
}
Included properties for creates and deletes
For simple task child elements (like check list Items, attachments) when being created and deleted, all properties required to render that item are included. Checklist items include the name and attachments include name, uri, and type.
Any child elements which are a relationship between other entities include the ID of the other entity. For example, assignments include the resourceId and links include the predecessorId.
DependentEdit details
Dependent edit records are generated for a task if a change to another task causes the current task to be modified. The history record includes the changes to the current task and a sourceEdit property indicating the changes to the source task that caused the current task to be modified.
Example: A link is added to another task (source) to the current task and the current task start date is moved out one day:
{
"fields": {
"start": {
"previous": "2015-11-17T08:00:00Z",
"updated": "2015-11-18T08:00:00Z"
}
},
"sourceEdit": {
"type": "TaskEdited",
"taskId": "a6f33356-cd04-ee11-83c4-e04f43e61e09",
"fields": {
"predecessors": [
{
"id": "abf33356-cd04-ee11-83c4-e04f43e61e09",
"created": true,
"predecessorId": "a4f33356-cd04-ee11-83c4-e04f43e61e09"
}
]
}
}
}
Multiple source edits
Bulk operations can change multiple tasks at once and can lead to multiple dependant changes. In that scenario, the tasks in the bulk operation are included in the sourceEdit with a CompoundEdit record type. Examples of these scenarios include deleting multiple tasks, linking multiple tasks, indenting multiple tasks. A CompoundEdit record includes the count of edits and the first three edits.
Example
{
"fields": {
"start": {
"previous": "2015-11-17T08:00:00Z",
"updated": "2015-11-16T08:00:00Z"
}
},
"sourceEdit": {
"type": "CompoundEdit",
"count": 2,
"edits": [
{
"type": "TaskDeleted",
"taskId": "f3233655-ce04-ee11-83c4-e04f43e61e09",
"name": "Task A"
},
{
"type": "TaskDeleted",
"taskId": "f1233655-ce04-ee11-83c4-e04f43e61e09",
"name": "Task B"
}
]
}
}
Edits to summary tasks
Certain operations, like deleting a task or indenting a task, can generate multiple records if the edited task is a summary task because those edits also apply to the task's children. All dependent records include the summary task as the sourceEdit.
Record size
Details field has a maximum size of 1000 characters. If the initial change record exceeds 1000 characters, the history record is trimmed down. All string changes are limited to 100 characters and the number of changed fields are limited to 6. A "truncated" property indicates how many direct fields weren't included. A "truncatedElements" property indicates the number of child elements that weren't written out.
If the size of the record with the above restrictions exceeds 1000 characters, the entire record is not generated.
Example
{
"fields": {
"start": {
"previous": "2015-11-17T08:00:00Z",
"updated": "2015-11-10T08:00:00Z"
}
},
"sourceEdit": {
"type": "CompoundEdit",
"count": 2,
"edits": [
{
"type": "TaskEdited",
"taskld": "225a7a3b-a916-ee11-a35f-480fcf4e7967",
"fields": {
"name": {
"previous": "Prepare Preliminary Project Scope Statement",
"updated": "Summarize Project Results and Lessons Learned"
},
"start": {
"previous": "2015-11-16T08:00:00Z",
"updated": "2017-11-16T08:00: 00Z"
},
"truncated": 5
}
},
{
"type": "TaskEdited",
"taskld": "245a7a3b-a916-ee11-a35f-480fcf4e7967",
"fields": {
"name": {
"previous": "Prepare Preliminary Project Scope Statement",
"updated": "Develop High Level Work Breakdown Structure"
},
"start": {
"previous": "2015-11-16T08:00:00Z",
"updated": "2017-11-16T08:00:00Z"
},
"truncated": 5
}
}
]
}
}