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

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.

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.

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.

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.

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.

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