Event references

Overview

Event references are only available during workflow events.

Many of them are context-sensitive, and some are limited to specific events.

Where can they be used?

You can use predefined references in the following situations:

Limitations apply to custom newevent events – see Availability section below.

References

Reference

Type

Event(s)

Description

Ver

Reference

Type

Event(s)

Description

Ver

Attachments

These references are available in events arising from changes to page or blog post attachments.

See also: @type@ in Content section.

@comment@

Text

attachmentschanged

attachmentadded

attachmentremoved

attachmentversionremoved

attachmentupdated

Comment associated with the attachment.

  • Can be set when uploading attachment via web form

  • Can be edited from the attachment properties screen



@name@
or @filename@

Text

attachmentschanged

attachmentadded

attachmentremoved

attachmentversionremoved

attachmentupdated

The filename of the attachment, including extension.



@size@

Number

attachmentschanged

attachmentadded

attachmentremoved

attachmentversionremoved

attachmentupdated

The file size, in bytes.



Content

These references are available in all events, and relate to the content associated with the workflow event.

@author@
or @creator@

Username

all events

The username of the person who created the page or blog post.

Specifically, it returns the username of the person who clicked the Publish button when the page or blog post was first created.



@page@

Link

all events

A link (looks like: <content title>) to the page or blog post. Will include workflow state status indicator circle.

See also: Publishing, State Status Indicator Circles



@pageid@

Number

all events

The ID of the page or blog post

See also: How to get a Page ID (Atlassian)



@pagelatest@

Link

all events

A link (looks like: <content title>) to the latest version of a page or blog post, irrespective of workflow state.

See also: Page history (Atlassian)



@pagetitle@

Text

all events

The title (looks like: <content title>) of the page (or blog post?)

4.9.4

AWP-3193 Unavailable in pagecreated event from v4.17.4 → v5.0.8 (fixed in v5.1)

@snapshoturl@

Text

Comala Publishing snapshot publishing events only

The snapshot document url for a snapshot created using the snapshot-page macro in a workflow trigger.

See also: Snapshot document publishing

Requires Comala Publishing v3.0+ and Comala Document Management v6.17.6+

6.17.6+

@type@

Text

all events

The content type, either:

  • page – wiki pages

  • news – blog posts

  • attachment – file attachment (only in attachment-related events)



@version@

Number

all events

The version number of the page or blog post

See also: Page history (Atlassian)

5.1

Content Reviews

These references are only available in events arising from Approving or Rejecting content during Reviews.

See also: Attribute References

@approval@
or @approvalname@

Text

pageapproved

pagerejected

newsapproved

newsrejected

approvalassigned

approvalunassigned

The name of the the content review (as specified in the associated approval macro) which the event relates to.





@approvalassignees@

username

One or more in a list

pageapproved

pagerejected

newsapproved

newsrejected

approvalassigned

approvalunassigned

List of one or more usernames assigned to the content review that the event relates to.



@approvalcomment@

Text

pageapproved

pagerejected

newsapproved

newsrejected

The note that was added whilst Approving or Rejecting during a content review (event name determines which situation occurred).

See also: comment and taskcomment references



@approvaldate@

Text

pageapproved

pagerejected

newsapproved

newsrejected

The date and time on which the page or blog post was Approved or Rejected (event name determines which situation occurred).

Format of the date is defined by the Date Format setting in Confluence General Configuration.



@approvaluser@

Username

pageapproved

pagerejected

newsapproved

newsrejected

The username of the person who Approved or Rejected, resulting in the event being sent.



If using partial=true on the trigger macro, it will be the username of the current user who triggered the event. Otherwise it will be the user who gave the deciding vote.

@comment@

Text

approvalassigned

approvalunassigned

A note made during a content review while assigning a reviewer, or unassigning a reviewer (event name determines which situation occurred).



@selectedapprover@

Username



Deprecated Use @approvalassignees@ instead.

Username of assigned reviewer.

Deprecated
from 3.2

@selectedapprovers@

username

One or more in a list



Deprecated Use @approvalassignees@ instead.

List of one or more assigned reviewer usernames.

Deprecated
from 3.2

Event

These references relate specifically to the event itself.

@date@

Text

all events

Date on which the event occurred

Format of the date is defined by the Date Format setting in Confluence General Configuration.

4.4

@datetime@

Text

all events

Date and time on which the event occurred

Format of the date is defined by the Date Time Format setting in Confluence General Configuration.

4.4

@errormessage@

Text

all events

If an action fails, in a trigger that defines a newevent, this reference will contain the error message in triggers that handle the new event.



@user@

Username

user-initiated events

The username of the person responsible for initiating the event.



@userfullname@

Text

user-initiated events

The full name of the person responsible for initiating the event.



Labels

These references are only available in events arising from adding or removing Labels.

@addedlabel@

Text

labeladded

Name of the label which was added



@removedlabel@

Text

labelremoved

Name of the label which was removed



@label@

Text

labeladded

labelremoved

Name of the label which was added or removed (as applicable to the event)



PDF Export

These references relate to events arising from PDF export with the K15t Scroll PDF Exporter app

@attachmentURL@

Text

pdf-export-success

The URL of the newly exported PDF that has been attached to the page

6.14

@errormessage@

Text

pdf-export-error

Details of the error returned by the K15t Scroll PDF Exporter app if the export action fails

6.14

States

These references relate to the current workflow state.

@comment@

Text

statechanged

pagestatechanged

newsstatechanged

If specified, the note that was added whilst selecting a state to transition to.



@duedate@
or @expirydate@

Text

statechanged

pagestatechanged

newsstatechanged



The due date for the current workflow state, if defined.

Format of the date is defined by the Date Format setting in Confluence General Configuration.



For task-related events, the @duedate@ reference denotes the due date for the task, not the state.

@state@ or @awpState@

Text

all events

The name of the current workflow state, as defined by the state macro.

 

Tasks

These references are available in events arising from Tasks.

@duedate@

Text

any task event

The due date for the task, if defined.

Format of the date is defined by the Date Format setting in Confluence General Configuration.



@task@
or @taskname@

Text

any task event

The name of the task.



@taskassignee@

Username

taskassigned

The username of the person who is currently assigned to the task.



@taskassigner@

Username

taskassigned

The username of the person who assigned the task.



@taskcompleter@

Username

taskcompleted

The username of the person who completed the task.



@taskcreator@

Username

any task event

The username of the person who created the task.



@taskcomment@

Text

taskassigned

taskcompleted

The note associated with a task:

  • assignment note, if event is taskassigned

  • completion note, if event is taskcompleted



Workflow

These references relate to the workflow associated with the content.

@pageactivity@

Link

all events

A link (looks like: <page activity>) to the Activity Report for the page or blog post.



App configuration settings may prevent view-only users from accessing the Document Activity Report - Content.

@pageworkflowname@

Text

all events

The name of the workflow, as defined by the name parameter of the workflow macro

 

Availability in custom event triggers

Custom events are created with the newevent parameter on the trigger macro (see: Triggers for details).

Reference availability

Use in custom events?

Reference availability

Use in custom events?

all events

specific event(s)

In cases where a reference will not be available, use the set-metadata macro in the original event trigger to store the value as metadata.

This value is then retrieved in the custom event trigger using Metadata references. Alternatively, you could use another type of value reference, such as Attribute References or Supplier References, to retrieve the data by other means.

The possibility of an event occurring again is a particularly important consideration when using queued trigger actions.

If there is a risk of this happening, you need to take measures to prevent the original event from happening until after the custom event trigger has been processed.

For example,

  • use the set-state macro in the original event trigger to transition to a temporary state with no transitions

  • then use it again as the last action in the custom event trigger to transition back to the normal workflow

All examples

See also