Notification placeholders

The “Subject” and “Body” parts of an email Notification support placeholders:

Syntax	Example on a Ticket notification
$this->attribute$	$this->ref$ is replaced by the Ticket reference
$this->external_key->attribute$	$this->caller_id->email$ is replaced by the email of the caller of the Ticket
$this->representation(attribute)$	$this->html(log)$ is replaced by the public log in html format
$CONSTANT$	$APP_URL$ is replaced by the URL of the iTop application
$this->function()$	$this->hyperlink(portal)$ is replaced by the url to the Ticket on the iTop portal

Those 5 cases are detailed below:

Additional placeholders can be added by Extensions, such as Approval… Check Extension documentation for more details.

Attribute placeholders

Function	Description	Supported types of attributes
$this->attribute$	The plain text representation of the value of the attribute	any
$this->id$	The id of the current object (there is no such attribute at that time)
$current_contact->attribute$	the person who did the change which activated the trigger

LinkedSet attributes: the very standard syntax $this->attribute$ returns a list of names separated by a new line character which are replaced by blank in HTML, so use instead $this->html(functionalcis_list)$ to display the bullet list of CIs linked to a User Request.

Known limitation: Calculated attribute friendlyname is not accurate if one of its underlying field is modified.
The workaround is to rebuild the friendlyname within the notification itself.

Extended syntax

The extended syntax provides a quick means to retrieve data from related objects, like in the following examples:

$this->approver_id->phone$
$this->approver_id->org_id->code$
$this->approver_id->org_id->hyperlink()$
$this->parent_request_id->hyperlink(portal)$

Every built-in functions and attribute representations are available after the last ->).

Attribute code before the arrow ->, must be an ExternalKey for the built-in functions to be recognized.
It does not work with an ExternalField (field from a foreign class), which must be replaced with the full path!

Attribute representations

Function	Description	Supported types of attributes
$this->html(attribute)$	The source HTML of the value of the attribute, HTML tags are escaped. To use in email body only (HTML part), so it is displayed nicely. Can even be used on a Text attribute which could contain HTML tags which we want to preserve as is.	any
$this->label(attribute)$	The localized representation of the value of the attribute. The language is the language of the user currently logged in.	any (only make sense for AttributeEnum)
$this->head(log)$	Plain text of the latest entry in the case log	AttributeCaseLog
$this->head_html(log)$	HTML formatted representation of the latest entry, whereas $this->html(attribute)$ returns an HTML formatted representation of the whole case log (you can apply your own CSS styling to make it beautiful).	AttributeCaseLog
New in iTop 2.4: $this->raw(attribute)$	SQL formatted representation of the date(time), whereas $this->(attribute)$ returns the value formatted regarding the configuration parameter.	AttributeDatetime

Fixed placeholders

Placeholder	Meaning
$APP_URL$	URL of the iTop application.
$MODULES_URL$	Root URL of the modules (e.g. `$APP_URL$/env-production`).

Built-in function placeholders

Placeholder	Meaning
$this->name()$	The name of the current object
$this->hyperlink()$	The hyperlink to access the current object in iTop console
$this->hyperlink(portal)$	The hyperlink to access the current object in the iTop portal
$this->hyperlink(itop-portal-view)$	To open the current object in iTop portal in read-only mode
$this->hyperlink(itop-portal-edit)$	To open the current object in iTop portal in modification mode
$this->url()$	The url to access the current object in iTop console

Warning, for custom portals you'll need to have created an URLMaker class : see urlmaker

Example: UserRequest

Assuming that a notification is triggered when assigning a User Request, the body of the message could be:

Dear $this->html(agent_id),
The ticket $this->ref$ has been assigned to you.

More information about this ticket
Title: $this->title$

Description:
$this->description$

Public log:
$this->head_html(public_log)$

Impacted CIs:
$this->html(functionalcis_list)$

Click here to display the details of the ticket: $this->hyperlink()$ (authentication required)

Questions & Answers

Troubleshooting

Question: Why my placeholder is not replaced by the real value in the sent email?
Answers:

You have made a typo of the field code or that code does not exist on the class which has trigger that notification
Check the source code of your notification body (CKEditor propose a <source> button), if an html tag is inside the placeholder, this breaks the matching mechanism and the text is not replaced by the value.

Question: My placeholder get translated or not, depending on who trigger the event, why?
Answer: The placeholders are translated if and only if the user who triggered the notification is allowed to see the object, which field value must be put in the notification.

Let's take the example of a notification triggered by the caller through the User Portal, and we will assume that

the portal user has Allowed organizations limited to his own organization
the ticket agent belongs to another organization than the caller one
The data model was modified and a new External Field agent_email was defined on the UserRequest class returning the agent (Person) email field

In this situation:

$this->agent_email$ will be replaced by its value, because the portal user is requesting to see a UserRequest field of a UserRequest which he can see.
$this->agent_id->email$ will not be replaced, because the portal user is requesting a Person field of a Person which he cannot see.
$this->html(functionalcis_list)$ will be replaced by the FunctionalCIs belonging to his own organization only, which may be less than all the FunctionalCIs linked to the Ticket.

This behavior is related to iTop design:

When you can see an object, you can see all its fields.
The access rights are controlled by object, when you cannot see an object A (eg Organization), you see none of its fields
The exception are when a field of A (Organization.code) is mirrored on another object B (Person) by the mean of a ExternalKey (org_id) and ExternalField (org_id_code). If you can see the object B (Person), then you see as well the fields of the object A which have been mirrored (The Organization code in the example).

Customization

Question: Can I add automatically a team signature to UserRequest email notification?
Answer:

customize the Team class by adding an signature field, of type AttributeTemplateHTML if you want to make it nice with logo for eg.
then add $this->team_id->signature$ at the end of the body

Question: Can I send in my notification the id of the current object?
Answer: Though there is no 'id' attribute', the placeholder $this->id$ is available to represent the iTop internal identifier.

Question: If I have created multiple portals, can I send a hyperlink to a specific portal?
Answer: you can point to any portal replacing portal by the id of your new portal.
Example $this->hyperlink(partner-portal)$

Question: Can I send an hyperlink to a transition in a portal? For example, to close a ticket.
Answer: you can add an hyperlink in your notification $APP_URL$pages/exec.php/object/apply-stimulus/ev_close/UserRequest/$this->id$?exec_module=itop-portal-base&exec_page=index.php&portal_id=itop-portal

Replace ev_close by the stimulus that you want to apply
You can also replace portal_id=itop-portal by the code of your own portal

Sidebar