The “Subject” and “Body” parts of an email Notification support placeholders:
|Syntax||Example on a Ticket notification|
||$this->ref$ is replaced by the Ticket reference|
||$this->caller_id->email$ is replaced by the email of the caller of the Ticket|
||$this->html(log)$ is replaced by the public log in html format|
||$APP_URL$ is replaced by the URL of the iTop application|
||$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.
|Function||Description||Supported types of attributes|
||The plain text representation of the value of the attribute||any|
||The id of the current object (there is no such attribute at that time)|
||the person who did the change which activated the trigger|
$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.
friendlynameis not accurate if one of its underlying field is modified.
The workaround is to rebuild the friendlyname within the notification itself.
The extended syntax provides a quick means to retrieve data from related objects, like in the following examples:
Every built-in functions and attribute representations are
available after the last
->, 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!
|Function||Description||Supported types of attributes|
||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
Can even be used on a Text attribute which could contain HTML tags which we want to preserve as is.
||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)|
||Plain text of the latest entry in the case log||AttributeCaseLog|
||HTML formatted representation of
the latest entry, whereas
|New in iTop 2.4:
||SQL formatted representation of the date(time),
||URL of the iTop application.|
||Root URL of the modules (e.g.
Built-in function placeholders
||The name of the current object|
||The hyperlink to access the current object in iTop console|
||The hyperlink to access the current object in the iTop portal|
||To open the current object in iTop portal in read-only mode|
||To open the current object in iTop portal in modification mode|
||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
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
Question: Why my placeholder is not replaced by the real
value in the sent email?
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 organizationslimited 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_emailwas 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
codein the example).
Question: Can I add automatically a team signature to
UserRequest email notification?
Teamclass by adding an
signaturefield, of type
AttributeTemplateHTMLif you want to make it nice with logo for eg.
$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
Question: If I have created multiple portals, can I send
a hyperlink to a specific portal?
Answer: you can point to any portal replacing
id of your new portal.