ÃÛ¶¹ÊÓƵ

DocumentationWorkfrontWorkfront Guide

Event subscription versioning

Last update: Wed Mar 19 2025 00:00:00 GMT+0000 (Coordinated Universal Time)

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
Parameter values
For any object created from a template that included a custom form, a CREATE event was sent, then an UPDATE was sent with the parameter values (including calculated fields and their values).
Only a CREATE event is sent, which contains parameter values including calculated fields.
If you have a filter on UPDATE events with parameter values (including calculated custom fields) and are expecting to receive it after an object CREATE event that includes parameter values, you no longer receive that UPDATE event. If you want to see 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
5f00cc6b-2202-40d6-bcd0-3ee0c2316b43