--- title: "set-message macro" canonical: "https://support.appfire.com/space/CDML/650153597/set-message%20macro" format: markdown --- > Macro (aura-html) ## Overview > Macro (excerpt) > > Add/remove a page message Use the **set-message** macro to display an on-screen message. ![image](media://54d2e5c0-fdac-4708-859f-cf70fbd395ed) > ✅ It's great for keeping the user informed during the content production process when a workflow event or change occurs. - messages are shown between the page title and body content whilst viewing content (it's hidden from the edit screen) - messages can be configured as different panel displays - info - error - warning - success - if triggered by `stateexpired` or `taskexpired` [events](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649759655), the message is not shown until the page is refreshed The set-message macro can be **filtered** to display the message only to a specific user(s). ![image](media://91ca622d-ecc9-40de-a288-fd48b4c84ddb) A message filtered to display to a specific user includes an option for the user to remove it. > 📝 Messages filtered for users are removed after the user has viewed the message. > ℹ️ Messages can also be filtered using the `view` parameter to display a message on the workflow draft content URL or the workflow published content URL when the applied workflow has a final state. The message is removed and replaced when a new trigger event occurs that includes a new `set-message` action macro (if the message is for the same audience). The message is cleared if the `set-message` macro in the trigger is empty. ## Where to use it? Optional. One or more `set-message` macros can be added as action macros in a **[trigger](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649859133)**[ macro](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649859133). ``` {trigger:statechanged|state=Rejected} {set-message} The page content has been rejected. The content must be triaged. {set-message} {trigger} ``` A filter can be added to display the message to specific audiences - for example to one or more users, one or groups ``` {trigger:statechanged|state=Draft} {set-message:user=@user@} The page content has been moved to the Draft state. The content must be triaged before submitting for approval. {set-message} {trigger} ``` If more than one `set-message` macro is added to a trigger - only one message will be displayed on the page if all the messages are for everyone (unfiltered) - more than one `set-message` macro in the trigger will be displayed on the page if at least one of them is filtered to be displayed to a user(s), group(s) or the draft/published content ## Parameters | Parameter | Required | Default | Notes | Ver | | --- | --- | --- | --- | --- | | *unnamed first parameter* | | | [Deprecated] Use the `user` parameter instead. | Deprecated v5.2 | | *macro body* | | | The message to display:
- Plain text, or [Confluence Wiki Markup](https://confluence.atlassian.com/display/DOC/Confluence+Wiki+Markup) - Supports [Value References](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649694302) | | | Replaces an existing message to the same audience; if the macro body is empty, the message panel is removed *for that audience.*
``` {set-message}{set-message} ```
A message that included `view=draft` requires the empty macro to be configured with the same parameter to remove the displayed message.
``` {set-message:view=draft}{set-message} ``` | | > 📝 When using the `set-message` macro in a trigger initiated by an expiration event, **page** or **space reference links** (when the page title is set between [ ] to generate a link from it) are not supported. > 📝 > 📝 However regular links as wiki markup**, **for example, [google|https://google.com] do work. | | `duration` | | :info: | How long should the message be displayed from the point at which it is set?
- **ISO 8601 duration code** – see: [Expiry Dates](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649890606)
> Macro (contentbylabel) | | | :info: Default behavior depends on message audience:
- unfiltered messages are shown indefinitely - if a `group` and/or `user` is specified, the message for an individual user expires once viewed by that user
In both cases, specifying a `duration` will override the default behavior. | | `group` | | *unfiltered* | Only show to users in specific user group(s)?
- Comma separated list of user groups - Supports [Value References](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649694302)
> 📝 The message for an individual user expires once viewed by that user. It is not displayed for subsequent views of the page or if a transition has occurred before viewing.
The on-screen display of a message filtered to a specific group(s) can be removed from the screen for that member of the group using an **X** option displayed in the message panel.
The option to remove the message is not displayed if a `duration` parameter value is added to the macro.
> Macro (contentbylabel) | 5.2 | | `style` | | `info` | Message style: `info`, `error`, `warning`, `success`
o> Macro (inline-media-image)
o> Macro (inline-media-image)
o> Macro (inline-media-image)
o> Macro (inline-media-image)
if no `style` is added the default message display is `info`.
> Macro (contentbylabel) | 4.1 | | [Obsolete] The `tip` and `hint` styles are no longer supported (since v4.1) – use `success` and `info`, respectively, instead. | | `user` | | *unfiltered* | Only show to specific user(s)?
- Comma-separated list of usernames - Supports [Value References](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649694302)
> 📝 The message for an individual user expires once viewed by that user. It is not displayed for subsequent views of the page or if a transition has occurred before viewing.
The on-screen display of a message filtered to a specific user(s) can be removed from the screen for that user by using an **X** option displayed in the message panel.
The option to remove the message is not displayed if a `duration` parameter value is added to the macro.
> Macro (contentbylabel) | | | `view` | | `both` | Which types of content URL should the message be shown on?
Default - no inclusion of the parameter or value. The undisplayed parameter default value is `both`.
- `draft` – the normal URL - `published` – the `/public` URL - `both` – both normal and public URLs
When `view=draft` or `view=published` is included the `set-message` macro the message is considered as a filtered message and can be used in the same trigger as an unfiltered `set-message` macro (the `view` parameter is default value of `both`)
> Macro (contentbylabel) | 5.2 | | This parameter determine which URL the message is shown when using [same-space publishing](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649794062):
- view-only users see the `/public` URL by default - content producers still see the normal URL by default, but can [Switch between draft and published](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649858126) URLs
If you're not using same-space publishing, all users see the normal URL by default. | | For example,
If `view=draft`, the message is displayed when viewing the content in any state in the workflow
- `myconfluence.com/display/MSRM/Our+Page`
But this message is not displayed when viewing the last approved version for a page with an applied workflow that includes a final state. The viewer sees this content URL with the `/public` pathway
- `myconfluence.com/public/MSRM/Our+Page`
> 📝 The filtered message `view=draft` is displayed on content in the final workflow state. The content in the final state has the normal URL and not the `/public `URL | | :info:** **The `user` and `group` parameters can be used together:
- groups are treated as if you listed their users via the `user` parameter - there can be only one message for a given user per `view` type
Unfiltered messages, those which do not specify user or group, are treated separately:
- they are shown in addition to user or group messages | ## Removing a message An empty `set-message` macro body in a trigger can be used to remove a previously set message. ``` {set-message} {set-message} ``` > 📝 You need to use the same parameters that are in the message you want to remove, for example, if the `set-message` macro contained *view=draft*, then, your empty set-message macro must have the very same *view=draft* parameter. For example, adding the following message on a state transition ``` {trigger:statechanged|state=Test} {set-message:style=success} You transitioned to the "Test" state {set-message} {trigger} ``` This can be removed in a subsequent transition using an empty `set-message` macro in the trigger. ``` {trigger:statechanged|state=Ready} {set-message} {set-message} {trigger} ``` Although the `set-message` macro included a parameter to define the style of the message, both this `set-message` macro and the empty `set-message` macro are unfiltered - they are displayed to the same audience - and the message is removed. > 📝 The unfiltered `set-message` macro display is persistent until either removed using an empty `set-message` macro or will be replaced if another trigger actions a message using an unfiltered `set-message `macro. If you have the following two messages displayed - one filtered using `view=draft` and one unfiltered - they are considered as being for different audiences. ![image](media://852e7797-d163-49d1-abc6-2415689d56d5) ``` {trigger:statechanged|state=Draft} {set-message:view=draft|style=info} This is draft content, an approved version has been published{set-message} {set-message:style=warning} This content must be triaged and reviewed{set-message} {trigger} ``` Using the following in a trigger will only remove the unfiltered warning message. ``` {set-message} {set-message} ``` To remove both messages the trigger will need to include an empty `set-message` macro for each different audience. ``` {trigger:statechanged|state=Published} {set-message}{set-message} {set-message:view=draft}{set-message} {trigger} ``` ## Removing a workflow If an applied workflow is removed from content - any displayed `set-message` macro messages are removed from the document. If the workflow is removed without clearing the document activity - previous on-screen messages will be displayed on reapplying the workflow (if the state has not been initialized) ## Examples ### Adding a filtered `set-message` macro and an unfiltered `set-message` macro to the same trigger ```plaintext {workflow:set message test workflow} {state:Test} {state} {state:Ready} {state} {trigger:statechanged|state=Test} {set-message} This message shown to everyone {set-message} {set-message:user=@user@} You transitioned to the "Test" state {set-message} {trigger} {trigger:statechanged|state=Ready} {set-message}{set-message} {trigger} {workflow} ``` A transition to the **Test** state adds two on-screen notifications to the page. ![image](media://e1500a8a-8bb8-48b4-aefa-eb0b3b22942b) The message from each `set-message` macro are both displayed as they are considered to be for different audiences - at least one of the macros is filtered using an added user parameter value or group parameter value - unfiltered messages are shown in addition to any messages filtered to users The second message is specific to the user who actioned the transition and is only displayed to this user. This message can be removed by the user using the **X** option in the message. ### Adding one or more unfiltered `set-message` macros to the same trigger If a trigger has two or more `set-message` macros with no filter (no `user`, `group` or `view` parameter added to any of the macros). ``` {trigger:statechanged|state=Test} {set-message} Hey, this page needs some triage work! {set-message} {set-message:style=success} You transitioned to the "Test" state {set-message} {trigger} ``` - only the last `set-message` macro content before the closing trigger will be the message displayed on the page on the transition ![image](media://4e4047bb-6e0c-4be6-8a5f-7c4eee5f12e8) The first `set-message` macro action in the trigger is superseded by the second `set-message` macro. > 📝 In this example the `set-message` macro is a success panel as the parameter `style=success` has been added to the macro. > ℹ️ Only the last `set-message` macro before the closing trigger will be displayed if you add two or more filtered `set-message` macros with the same `user` or `group` filter to the same trigger, ## All examples > Macro (contentbylabel) ## See also [Workflow Authoring Guide](https://appfire.atlassian.net/wiki/spaces/CDML/pages/648611901): - [Notifications](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649957056) - [Expiry Dates](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649890606) - [Events](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649759655) - [Triggers](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649563178) - [Actions](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649858941)