User Tools

Site Tools

:: Latest version ::

latest:admin:notifications

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
latest:admin:notifications [2017/11/23 16:59]
vdumas [Attribute placeholders]
latest:admin:notifications [2019/04/23 17:23] (current)
Line 13: Line 13:
 Use the link “Notifications” in the “Admin tools” menu to manage triggers and actions: Use the link “Notifications” in the “Admin tools” menu to manage triggers and actions:
    
-{{:2_3_0:​admin:​notifications.png?​500|}}+{{:2_6_0:​admin:​notifications.png?​500|}}
  
   * The “Triggers” tab displays all created triggers.   * The “Triggers” tab displays all created triggers.
Line 25: Line 25:
 To create a new action, go to the "​Actions"​ tab and click on "​New..."​. The following wizard appears: To create a new action, go to the "​Actions"​ tab and click on "​New..."​. The following wizard appears:
  
-{{:2_3_0:​admin:​new-action.jpg|New Action}}+{{:2_6_0:​admin:​new-action.jpg|New Action}}
  
 The mandatory fields for an email action are: The mandatory fields for an email action are:
Line 34: Line 34:
 ===== Defining recipients ===== ===== Defining recipients =====
  
-The contacts to be notified in the “To”, “Cc”, and “Bcc” are defined by an OQL query. This allows to specify multiple recipients for the notification,​ like “all the contacts attached to a ticket” or “all the contacts on the impacted site”. (Refer to [[2_3_0:​oql:​start|Object Query Language Reference]] for more information about writing OQL queries)+The contacts to be notified in the “To”, “Cc”, and “Bcc” are defined by an OQL query. This allows to specify multiple recipients for the notification,​ like “all the contacts attached to a ticket” or “all the contacts on the impacted site”. (Refer to [[2_6_0:​oql:​start|Object Query Language Reference]] for more information about writing OQL queries) 
  
 This OQL query must return a list of objects containing an email attribute, namely: This OQL query must return a list of objects containing an email attribute, namely:
Line 42: Line 43:
  
 For instance, to notify all persons whose name starts with John, the **To** field can contain: For instance, to notify all persons whose name starts with John, the **To** field can contain:
-<​code>​ +    ​SELECT Person WHERE name LIKE '​John%'​
-SELECT Person WHERE name LIKE '​John%'​ +
-</​code>​+
  
 The query can contain placeholders that refer to the current object for which the notification is being sent. The syntax is ''<​nowiki>:​this->​attribute</​nowiki>''​. The query can contain placeholders that refer to the current object for which the notification is being sent. The syntax is ''<​nowiki>:​this->​attribute</​nowiki>''​.
  
 For example, to send a notification to the person who is the "​caller"​ of a ticket, the **To** field will contain: For example, to send a notification to the person who is the "​caller"​ of a ticket, the **To** field will contain:
- +    ​SELECT Person WHERE id= :​this->​caller_id
-<​code>​ +
-SELECT Person WHERE id= :​this->​caller_id +
-</​code>​+
  
 The query can contain placeholders that refer to the current contact which has done the action at the origin of the event (might be an issue if the user is not linked to a contact). The syntax is ''<​nowiki>:​current_contact->​attribute</​nowiki>''​. The query can contain placeholders that refer to the current contact which has done the action at the origin of the event (might be an issue if the user is not linked to a contact). The syntax is ''<​nowiki>:​current_contact->​attribute</​nowiki>''​.
Line 68: Line 64:
 If the list returned by the query is empty no email will be sent. If the list returned by the query is empty no email will be sent.
  
-<note tip>To notify all the Persons attached to the Ticket (i.e. all the Persons in the "​Contacts"​ tab) the OQL query to be used as recipients (either **To**, **CC** or **Bcc**) is the following: ​''<​nowiki>​SELECT Person JOIN lnkContactToTicket AS L ON L.contact_id = Person.id WHERE L.ticket_id = :​this->​id</​nowiki>''​</​note>​+<note tip>To notify all the Persons attached to the Ticket (i.e. all the Persons in the "​Contacts"​ tab) the OQL query to be used as recipients (either **To**, **CC** or **Bcc**) is the following:\\ 
 +    ​SELECT Person ​ 
 +    ​JOIN lnkContactToTicket AS L ON L.contact_id = Person.id ​ 
 +    ​WHERE L.ticket_id = :​this->​id 
 +</note> 
 + 
 + 
 +<note tip>To notify all the Persons attached to CIs attached to the Ticket, uses: \\ 
 +    SELECT Person AS P  
 +    JOIN lnkContactToFunctionalCI AS L1 ON L1.contact_id = P.id  
 +    JOIN FunctionalCI AS CI ON L1.functionalci_id = CI.id  
 +    JOIN lnkFunctionalCIToTicket AS L2 ON L2.functionalci_id = CI.id  
 +    WHERE L2.ticket_id = :​this->​id 
 +</​note>​
  
 ===== Message contents and placeholders ===== ===== Message contents and placeholders =====
  
-Starting with iTop 2.3.0, the message body is now edited using a [[2_3_0:​admin:​rich_text_limitations|WYSIWYG HTML Editor]].+Starting with iTop 2.3.0, the message body is now edited using a [[2_6_0:​admin:​rich_text_limitations|WYSIWYG HTML Editor]].
  
 The "​Subject"​ and "​Body"​ parts can be build dynamically by using placeholders. The syntax to be used for such placeholders is ''​$xxxx$''​. The "​Subject"​ and "​Body"​ parts can be build dynamically by using placeholders. The syntax to be used for such placeholders is ''​$xxxx$''​.
Line 85: Line 94:
   * ''​$this<​nowiki>​-></​nowiki>​function()$''​ refers to a built-in //​function//​ executed within the context of the object that triggered the action.   * ''​$this<​nowiki>​-></​nowiki>​function()$''​ refers to a built-in //​function//​ executed within the context of the object that triggered the action.
   * ''​$this<​nowiki>​-></​nowiki>​attribute$''​ refers to the field //​attribute//​ of the object that triggered the action.   * ''​$this<​nowiki>​-></​nowiki>​attribute$''​ refers to the field //​attribute//​ of the object that triggered the action.
 +  * ''​$this<​nowiki>​-></​nowiki>​attribute_external_key<​nowiki>​-></​nowiki>​attribute$''​ refers to the field //​attribute//​ of the object pointed by //​attribute_external_key//​ it-self being a field of the object that triggered the action.
   * ''​$this<​nowiki>​-></​nowiki>​representation(attribute)$''​ refers to a built-in //​representation// ​ of the field //​attribute//​ of the object that triggered the action. Ex: ''​$this<​nowiki>​-></​nowiki>​html(name)$''​.   * ''​$this<​nowiki>​-></​nowiki>​representation(attribute)$''​ refers to a built-in //​representation// ​ of the field //​attribute//​ of the object that triggered the action. Ex: ''​$this<​nowiki>​-></​nowiki>​html(name)$''​.
  
-Those various types are described in details ​hereafter: +Check here the details ​of those various [[2_6_0:admin:​placeholders|types of placeholders]] 
-==== 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<​nowiki>​-></​nowiki>​name()$''​|The name of the current object| 
-|''​$this<​nowiki>​-></​nowiki>​hyperlink()$''​|The url to access the current object in iTop| 
-|''​$this<​nowiki>​-></​nowiki>​hyperlink(portal)$''​|The url to access the current object in the iTop portal| 
- 
-==== Attribute placeholders ==== 
- 
-^ Function ^ Description ^ Supported types of attributes ^ 
-|''​$this<​nowiki>​-></​nowiki>​attribute$''​|The plain text representation of the value of the attribute| any | 
-|''​$this<​nowiki>​-></​nowiki>​id$''​|The id of the current object (there is no such attribute at that time)| 
-|''​$current_contact<​nowiki>​-></​nowiki>​attribute$''​|the person who did the change which activated the trigger| 
- 
-<note tip>​Though there is no '​id'​ attribute',​ the placeholder ''​$this<​nowiki>​-></​nowiki>​id$''​ is available to represent the iTop internal identifier.</​note>​ 
- 
-<​note>​LinkedSet attributes: the very standard syntax ''​$this<​nowiki>​-></​nowiki>​attribute$''​ returns a list of names separated by a new line character. 
-//There is a bug on this feature in the iTop package 2.4.0 but a fix is available in svn//</​note>​ 
- 
-==== Attribute representations ==== 
- 
-^ Function ^ Description ^ Supported types of attributes ^ 
-|''​$this<​nowiki>​-></​nowiki>​html(attribute)$''​|The HTML representation of the value of the attribute| any | 
-|''​$this<​nowiki>​-></​nowiki>​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<​nowiki>​-></​nowiki>​head(attribute)$''​|Plain text of the latest entry in the case log| AttributeCaseLog | 
-|**New in iTop 2.0.3**: ''​$this<​nowiki>​-></​nowiki>​head_html(attribute)$''​|HTML formatted representation of the //latest// entry, whereas ''​$this<​nowiki>​-></​nowiki>​html(attribute)$''​ returns an HTML formatted representation of the //whole// case log (you can apply your own CSS styling to make it beautiful).| AttributeCaseLog | 
- 
- 
-==== Example: UserRequest ==== 
- 
-Assuming that a notification is triggered when assigning a User Request, the body of the message could be: 
- 
-<​code>​ 
- 
-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->​html(public_log)$ 
- 
-Click here to display the details of the ticket: $this->​hyperlink()$ (authentication required) 
- 
-</​code>​ 
-<note tip>​Adding automatically a team signature to UserRequest email notification:​ 
-  * 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 
-</​note>​ 
- 
-==== Extended syntax ==== 
- 
-The //extended syntax// provides a quick means to retrieve data from related objects, by following any of the external keys of the triggering object like in the following examples: 
- 
-  * ''​$<​nowiki>​this->​approver_id->​phone</​nowiki>​$''​ 
-  * ''​$<​nowiki>​this->​approver_id->​org_id->​code</​nowiki>​$''​ 
-  * ''​$<​nowiki>​this->​approver_id->​org_id->​hyperlink()</​nowiki>​$''​ 
-  * ''​$<​nowiki>​this->​parent_request_id->​hyperlink(portal)</​nowiki>​$''​ 
- 
-Every built-in functions and attribute representations are available (but only after the last ''<​nowiki>​-></​nowiki>''​). 
 ===== Testing notifications ===== ===== Testing notifications =====
  
Line 165: Line 106:
  
 ===== Creating a trigger ===== ===== Creating a trigger =====
- + 
-  * When a new object is created +
-  * When an object enters in a given state +
-  * When an object leaves a given state +
-  * When an object is updated from the iTop portal +
-  * When the given threshold for a Time-To-Resolve (TTR) or a Time-To-Own (TTO) is reached +
 To create a new trigger, click on “New” in action drop down list for the given category in “Trigger” tab. The following wizard appears: To create a new trigger, click on “New” in action drop down list for the given category in “Trigger” tab. The following wizard appears:
  
-{{:2_3_0:​admin:​new-trigger1.png?​400|}} ​+{{:2_6_0:​admin:​new-trigger1.png?​400|}} ​
  
 You have to select which type of trigger you want to create: You have to select which type of trigger you want to create:
-  * Trigger (on entering a state) +  * When a new object is created = Trigger (on object creation) 
-  * Trigger (on leaving a state) +  * When an object enters in a given state = Trigger (on entering a state) 
-  * Trigger (on object creation+  * When an object leaves a given state = Trigger (on leaving a state) 
-  * Trigger (on threshold) +  * When an object is updated from the iTop portal = Trigger (when updated from the portal
-  * Trigger (when updated from the portal)+  * When a given threshold for a Time-To-Resolve (TTR) or a Time-To-Own (TTO) is reached = Trigger (on threshold) 
 + 
 + 
 +More Trigger can be added by specific extensions such as: 
 +  * Trigger (when log is updated) //brought by extension **Email Reply**// 
 +  * Trigger (when updated by mail) //brought by extension **Ticket Creation ​from eMails**//​ 
 + 
 +<note tip>If you want to trigger a Notification '(on object creation)' limited to Ticket created by email, use origin='​mail'​ in the Trigger Filter.</​note>​
  
 Once you have selected the type of trigger you get the following form: Once you have selected the type of trigger you get the following form:
  
-{{:2_3_0:​admin:​new-trigger2.png?​400|}}+{{:2_6_0:​admin:​new-trigger2.png?​400|}}
  
 Any type of trigger requires you to specify three parameters: Any type of trigger requires you to specify three parameters:
   * //​Description//​ is left to you to further identify the purpose of this trigger.   * //​Description//​ is left to you to further identify the purpose of this trigger.
   * //Class// defines the class of object for which this trigger is applicable.   * //Class// defines the class of object for which this trigger is applicable.
-  * //Filter// restrict the objects to which the trigger applies. It is an [[2_3_0:​oql:​start|OQL query]] returning all the objects that would activate the trigger. Leaving it blank means: all the objects of the expected class.+  * //Filter// restrict the objects to which the trigger applies. It is an [[2_6_0:​oql:​start|OQL query]] returning all the objects that would activate the trigger. Leaving it blank means: all the objects of the expected class.
  
 Depending on the type of trigger, you will have to define additionnal parameters: Depending on the type of trigger, you will have to define additionnal parameters:
Line 200: Line 142:
 The "​Order"​ field determines in which order, for a given trigger, the actions are executed (actions are launched in ascending order). The "​Order"​ field determines in which order, for a given trigger, the actions are executed (actions are launched in ascending order).
  
-<note tip>We strongly encourage you to test triggers and actions before moving them to production, by using the "Being Tested"​ status on actions.</​note>​+===== Test your Trigger =====
  
-You can use the menu “Application log” where all notifications are tracked ​to check if an email was triggered. A detailed log of event describes what happened with a given notificationfor an easier troubleshooting.+<note tip>We strongly encourage you to test triggers and actions before moving them to productionby using the "Being Tested"​ status on actions.</​note>​
  
-You can as well see which notification had been sent for a given ticket (User Request, Incident, Change) using the tab “Notifications” in the details of the ticket.+You can see which notification had been sent for a given ticket (User Request, Incident, Change) using the tab “Notifications” in the details of the ticket.
  
-{{:2_3_0:​admin:​request-notifications.jpg|Notifications tab on ticket}}+{{:2_6_0:​admin:​request-notifications.jpg|Notifications tab on ticket}}
  
 <note tip> <note tip>
Line 233: Line 175:
 The test page performs a number of checks on the PHP configuration and allows you to send a plain-text email to the recipient of your choice. This is useful for validating that the PHP configuration of the server is indeed correct for sending emails. The test page performs a number of checks on the PHP configuration and allows you to send a plain-text email to the recipient of your choice. This is useful for validating that the PHP configuration of the server is indeed correct for sending emails.
  
-{{:2_3_0:​admin:​email-test.jpg|Email sending test page}}+{{:2_6_0:​admin:​email-test.jpg|Email sending test page}}
  
 ==== Email Configuration ==== ==== Email Configuration ====
Line 255: Line 197:
 ==== Notifications and application responsiveness ==== ==== Notifications and application responsiveness ====
  
-Sending emails is a relatively slow operation. Depending on your email server, sending one email may take several seconds (establishing the connexion to the server, sending the data, etc...). When a Ticket is created or updated in iTop, several emails may be emitted, depending on the notifications configured. This can take a few seconds to complete. To improve the responsiveness of the application,​ the notifications can be sent asynchronously by a process running in the background on the web server. To activate the asynchronous sending of notifications,​ set '''​email_asynchronous'​ => true,'' ​ in the configuration file and make sure that the [[2_3_0:​admin:​cron|background process]] is up and running.+Sending emails is a relatively slow operation. Depending on your email server, sending one email may take several seconds (establishing the connexion to the server, sending the data, etc...). When a Ticket is created or updated in iTop, several emails may be emitted, depending on the notifications configured. This can take a few seconds to complete. To improve the responsiveness of the application,​ the notifications can be sent asynchronously by a process running in the background on the web server. To activate the asynchronous sending of notifications,​ set '''​email_asynchronous'​ => true,'' ​ in the configuration file and make sure that the [[2_6_0:​admin:​cron|background process]] is up and running.
  
 <note tip>If you rely a lot on notifications,​ note that a direct SMTP connection using the ''​SMTP''​ transport is generally a bit faster than PHP's built-in mail function (''​PHPMail''​),​ so it may be worth the extra configuration effort.</​note>​ <note tip>If you rely a lot on notifications,​ note that a direct SMTP connection using the ''​SMTP''​ transport is generally a bit faster than PHP's built-in mail function (''​PHPMail''​),​ so it may be worth the extra configuration effort.</​note>​
latest/admin/notifications.txt · Last modified: 2019/04/23 17:23 (external edit)

";