Event subscription versioning

Last update: April 22, 2025

Topics:
Workfront API

CREATED FOR:

Developer

Workfront has two versions of event subscriptions. This article describes the differences between them.

The new version is not a change to the Workfront API, but rather a change to the event subscription functionality.

The ability to upgrade or downgrade event subscriptions ensures that when changes are made to the structure of events, existing subscriptions do not break, allowing you to test and upgrade to the new version without a gap in your event subscription.

When you upgrade or downgrade your event subscription to another version, you receive duplicate events for every event delivery for a five minute window after the version change. The duplicates include one each of event subscription version 1 and version 2. This ensures that you do not miss any events due to changing the event subscription version.

For information on the endpoints used for upgrading or downgrading event subscriptions, see Event subscription versioning in the article Event subscription API.

IMPORTANT

The following releases will affect event subscription versioning:

25.2 Release (April 10, 2025): All new subscriptions created after the 25.2 release are created as Version 2.
25.3 Release (July 17, 2025): Subscriptions can no longer be downgraded to Version 1 after the 25.3 release.
September 1, 2025: All remaining Version 1 subscriptions are migrated to Version 2.

Changes between Version 1 and Version 2

The following changes have been made for event subscriptions Version 2:

General changes

Affected fields Version 1 (Previous behavior) Version 2 (Change) Remediation action

Calculated parameter values Any object created from a template that included a custom form with calculated parameter values, a CREATE event would be sent, and then an UPDATE would be sent with the parameter values (including calculated fields and their values). When an object is created from a template that includes a custom form with calculated parameter values, only a CREATE event will be sent and will contain parameter values including calculated fields. If you have a subscription for UPDATE events and are expecting to receive an UPDATE event after an object is created with calculated parameter values, you will no longer receive that UPDATE event. If you wish to see calculated parameter values on object creation, you must create an additional CREATE subscription.

Multi-Select type fields

Affected fields	Version 1 (Previous behavior)	Version 2 (Change)	Remediation action
Calculated parameter values	Any object created from a template that included a custom form with calculated parameter values, a `CREATE` event would be sent, and then an `UPDATE` would be sent with the parameter values (including calculated fields and their values).	When an object is created from a template that includes a custom form with calculated parameter values, only a `CREATE` event will be sent and will contain parameter values including calculated fields.	If you have a subscription for `UPDATE` events and are expecting to receive an `UPDATE` event after an object is created with calculated parameter values, you will no longer receive that `UPDATE` event. If you wish to see calculated parameter values on object creation, you must create an additional `CREATE` subscription.
Multi-Select type fields	For any type of event that contains a change on a multi-select type field, if the field only contained one value it would be converted to and sent as a string. Otherwise it would be sent as an array. Examples: `myMultiSelectField: ["oneValue"]` is converted and sent as `myMultiSelectField: "oneValue"`. `myMultiSelectField: ["first", "second"]` is sent as `myMultiSelectField: ["first", "second"]`.	Regardless of how many values are in the array, it will be sent as an array. Examples: `myMultiSelectField: ["oneValue"]` is sent as `myMultiSelectField: ["oneValue"]`. `myMultiSelectField: ["first", "second"]` is sent as `myMultiSelectField: ["first", "second"]`.	If you have a subscription with a filter on a multi-select field, and the value as a string, you must create a new subscription with the same filter that has the value as an array.

For any type of event that contains a change on a multi-select type field, if the field only contained one value it would be converted to and sent as a string. Otherwise it would be sent as an array.

Examples:

myMultiSelectField: ["oneValue"] is converted and sent as myMultiSelectField: "oneValue".
myMultiSelectField: ["first", "second"] is sent as myMultiSelectField: ["first", "second"].

Regardless of how many values are in the array, it will be sent as an array.

Examples:

myMultiSelectField: ["oneValue"] is sent as myMultiSelectField: ["oneValue"].
myMultiSelectField: ["first", "second"] is sent as myMultiSelectField: ["first", "second"].

If you have a subscription with a filter on a multi-select field, and the value as a string, you must create a new subscription with the same filter that has the value as an array.

Object specific changes

Object code	Affected fields	Version 1 (Previous behavior)	Version 2 (Change)	Remediation action
ASSGN	`projectID` `taskID` `opTaskID` `customerID`	When this object was updated, the `UPDATE` event sometimes incorrectly showed the affected fields change from `null` to `ID value`.	All `UPDATE` events show the correct value for the affected fields.	None. If you have a filter on the affected fields, you receive an `UPDATE` event only if these fields have actually changed, not if any other value has changed.
DOCU	`referenceObjID`	When any parameter value was updated on this object, the `UPDATE` event incorrectly showed the affected field change from `null` to `object id`.	All `UPDATE` events show the correct value for the affected fields.	None. If you have a filter on the affected fields, you receive an `UPDATE` event only if these fields have actually changed, not if any other value has changed.
DOCU	`groups`	When a document was deleted, the `DELETE` event incorrectly showed the affected field as an empty array in the before state.	The `DELETE` event correctly shows the affected field in the before state.	None. The `DELETE` event will still be sent but now show correct data for the affected field.
DOCV	`proofDecision` `proofName` `proofProgress`	When this object was updated, two `UPDATE` events would be sent. The first one did not include the affected fields while the second event did.	All field updates including the affected fields are present in only one `UPDATE` event, and a second unnecessary event is not sent.	None. If you have a filter on the affected fields, the events are delivered in the first event.
EXPNS	`topReferenceObjCode` `referenceObjectName`	When any parameter value was updated on an Expense, the `UPDATE` event incorrectly showed topReferenceObjCode change from `EXPNS` to `PROJ`, and `referenceObjectName` change from `null` to `string value of project name`.	All `UPDATE` events show the correct value for the affected fields.	None. If you have a filter on the affected fields, you receive an `UPDATE` event only if these fields have actually changed, not if any other value has changed.
EXPNS	`topReferenceObjCode` `referenceObjectName`	When an Expense object was deleted, an `UPDATE` event was sent changing the affected fields to null before the `DELETE` event was sent.	The extra `UPDATE` event is not sent. The `DELETE` event has correct values for the affected fields in the before state.	If you have a filter for the affected fields on `UPDATE` events and are expecting to receive it when the object is deleted, you no longer receive that `UPDATE` event. If you wish to see these fields when the object is deleted, you must create an additional `DELETE` subscription.
HOUR	`projectID` `taskID` `roleID` `timesheetID` `hourTypeID` `projectOverheadID` `referenceObjID` `referenceObjCode` `securityRootID`	When this object was deleted, the `DELETE` event incorrectly showed the affected fields as `null` in the before state.	The `DELETE` event correctly shows the affected fields in the before state.	None. The `DELETE` event is still sent, but now shows correct data for the affected fields.
OPTASK	`rootGroupID`	When any parameter value was updated on this object, the `UPDATE` event incorrectly showed the affected field change from `null` to `ID value`.	All `UPDATE` events show the correct value for the affected field.	None. If you have a filter on the affected field, you receive an `UPDATE` event only if that field has actually changed, not if any other parameter value has changed.
OPTASK	`resolveProjectID` `resolveTaskID` `resolvingObjID`	When this object was updated, the `UPDATE` event sometimes incorrectly showed the affected fields change from `null` to `ID value`.	All `UPDATE` events will show the correct value for the affected fields.
PROJ	`rootGroupID`	When any parameter value was updated on this object, the `UPDATE` event incorrectly showed the affected field change from `null` to `ID value`.	All `UPDATE` events show the correct value for the affected field.	None. If you have a filter on the affected field, you receive an `UPDATE` event only if that field has actually changed, not if any other parameter value has changed.
PROJ	`convertedOpTaskID`	When this object was updated, the `UPDATE` event sometimes incorrectly showed the affected fields change from `null` to `ID value`.	All `UPDATE` events show the correct value for the affected field.	None. If you have a filter on the affected field, you receive an `UPDATE` event only if that field has actually changed, not if any other parameter value has changed.
TASK	`rootGroupID`	When any parameter value was updated on this object, the `UPDATE` event incorrectly showed the affected field change from `null` to `ID value`.	All `UPDATE` events show the correct value for the affected field.	None. If you have a filter on the affected field, you receive an `UPDATE` event only if that field has actually changed, not if any other parameter value has changed.
TASK	`convertedOpTaskID`	When this object was updated, the `UPDATE` event sometimes incorrectly showed the affected fields change from `null` to `ID value`.	All `UPDATE` events show the correct value for the affected field.	None. If you have a filter on the affected field, you receive an `UPDATE` event only if that field has actually changed, not if any other parameter value has changed.

Update event subscription version in a Workfront Fusion scenario

Workfront Fusion uses event subscriptions to watch for changes in Workfront to trigger scenarios. You can update the event susbcription version that Fusion uses directly in a scenario, using the Workfront > Update Events Payload Version module.

For instructions on using this module, see Workfront modules In the Workfront Fusion documentation.

recommendation-more-help