.. _rules: ##### Rules ##### .. _createrule: ***************** Create a new rule ***************** To create a new rule, change to tab "Rules" and click the link "Create new rule". You will get to the form for creating a new rule. .. image:: _static/link-create.jpg :height: 92px :width: 352px :scale: 100% :alt: Create new rule In the following all form fields will be explained. .. _formfields: The form fields ~~~~~~~~~~~~~~~ Name and post type ================== A rule always requires a **Rule name**. This name will only be used for internal purposes of administration. The name will appear in the list table of all rules. .. image:: _static/form1.jpg :height: 145px :width: 732px :scale: 100% :alt: Name and type You can decide if the rule should refer to all **Post types** or just to a special one. Choose "all types" or select an individual type. **The plugin supports all custom post type of your blog.** Category filter =============== If you select a post type which has categories, you will see the category filter boxes, like in this example for post type "Job Listings" which comes with the plugin "WP Job Manager". .. image:: _static/form1b.jpg :height: 152px :width: 731px :scale: 100% :alt: Category filter .. note:: Select no category if you want all categories (including future categories) to be considered. If you want to send notification emails only if the post has one or more certain categories attached, select those categories in the **"Include categories"** box on the left. To select multiple categories hold down the control button (ctrl) on Windows or command button (cmd) on a Mac. If you want to send notification emails for all categories except one or few categories, select those to exclude in the **"Exclude categories"** box on the right. Remember that the **exclude filter is dominant**. This means if you select a category in both the include and exclude box, it will be excluded. .. note:: The "Exclude categories" filter is dominant! If you do not select any category, the category filter will have no effect. Notications will be sent no matter which categories the post has attached. Post status =========== The main focus of a rule is on **Status before** and **Status after**. .. image:: _static/form2.jpg :height: 527px :width: 438px :scale: 100% :alt: Status before and Status after With these two settings you decide on which status transition a rule will match and the notification process be executed. If for example an email should be sent on publication of a post, select **"Not published"** for Status before and **"Published"** for Status after. **"Not published"** is a special status PSN provides to match all statuses but **"Published"**. The same applies to **"Not pending"** which matches all statuses but **"Pending"** and **"Not private"** which will match all statuses but **"Private"**. Another special status is **"anything"**. It applies to every status. If you set both fields to **"anything"**, the rule will match every status transition of a post. This combination may be good for monitoring every status transition of your content. PSN also supports custom post statuses registered by plugins. They will be appended to the Status before / Status ater select list with the internal abbreviation of the plugin in brackets, like **"Expired (job_manager)"** in the screenshot above. Subject and Text ================ The field **Subject** is for the subject text of your notification. You may fill in a maximum of 200 characters. All placeholders are supported (see :ref:`placeholders`). Their purpose is to stand in for data that will be automatically inserted into the email notification. For a list of all placeholders, click the link "List of all placeholders" right to the form. .. image:: _static/form3.jpg :height: 369px :width: 720px :scale: 100% :alt: Subject and text In the field **Text** you can write the text for the notification. Again all **placeholders are supported**. If you want to use **conditions** in your notification texts, check the chapter :ref:`conditional_templates`. Mail template ============= If you have prepared a mail template in the section "Mail templates" (see :ref:`mail_templates`) then you can select it in the "Mail template" drop down. The text of the selected mail template will be used for generating the email text. If you have configured the mail template to use **HTML format**, the notification email will be sent as HTML mail. .. image:: _static/form_html_mail.jpg :height: 84px :width: 630px :scale: 100% :alt: Mail template .. _one_email_per_to: One email per TO recipient ========================== .. image:: _static/form_one_email_per_to.jpg :height: 58px :width: 762px :scale: 100% :alt: One email per TO recipient If you do not want that a recipient can see the email addresses of the other recipients, this feature is your choice. If activated, Post Status Notifier will split the list of TO recipients and send **one single email per TO recipient** disregarding the CC and BCC settings. So in the final emails there will be only one TO recipient. .. note:: If the "One email per TO recipient" feature is activated, CC and BCC settings will be ignored! **Use this feature with care!** It may produce server load depending on the amount of recipients. If you run into a timeout, you can adjust the maximum execution time for this feature in the options (see :ref:`option_one_email_per_to`). This feature is still in Beta status. Recipient ========= For **Recipient** you can select who should get the notification. PSN supports multiple recipient options. .. image:: _static/form4.jpg :height: 327px :width: 763px :scale: 100% :alt: Recipient For **"Blog admin"** the email address of the general blog settings will be used. For **"Post author"** the post author's email address will be used. If you want to use a custom e-mail address, enter the recipient's e-mail address in the text field "Custom recipient". For multiple custom recipient addresses, separate them by comma. This even supports placeholders, so you could define the recipient of a notification by a custom field and use for example a placeholder **[post_custom_field-notification-recipient]** as individual e-mail. If you want to send notifications to all members of a certain role, you may select this role's entry like **"All members of role: Subscriber"** in the screenshot. You can even send notifications to all users of your WordPress installation by selecting **"All users"**. Recipient supports multiple selections. To select multiple recipients hold down the control button (ctrl) on Windows or command button (cmd) on Mac. Cc, Bcc ======= According to the same principle as selecting the recipient, you can choose multiple Cc and / or Bcc recipients. For custom Cc / Bcc addresses select "Custom recipient" in the according select box and insert the address in the text boxes below. Multiple addresses must be separated by comma. .. image:: _static/form5.jpg :height: 736px :width: 774px :scale: 100% :alt: Cc and Bcc emails Exclude recipients ================== Use this option if you want to exclude specific users from the list of recipients. Enter a comma separated list of WP user IDs or email addresses which should not be notified by this rule, e.g. "1, 2, author@mysite.com, 3, 4". .. image:: _static/form_exclude_recipients.png :height: 93px :width: 778px :scale: 100% :alt: Exclude recipients Exclude current user ==================== Use this option if you do not want the current user who saves / updates the post to receive a notification. PSN will match the current user's email address with all recipients and remove it. .. image:: _static/rule_exclude_current_user.png :height: 59px :width: 735px :scale: 100% :alt: Exclude current user Editor restriction ================== If you select one or more roles in the select box "Editor restriction", a notification will only be generated, if the editor of the post is a member of one of the selected roles. Leave blank for no editor restriction. To select multiple roles hold down the control button (ctrl) on Windows or command button (cmd) on Mac. .. image:: _static/form_editor_restriction.jpg :height: 217px :width: 720px :scale: 100% :alt: Editor restriction FROM ==== You can define a custom "**From**" address per rule. This will get used as sender. .. image:: _static/form_from.jpg :height: 70px :width: 761px :scale: 100% :alt: From Post whitelist ============== Here you can enter a comma separated list of post IDs to add to the whitelist. If one or more IDs are entered, this rule will ONLY trigger on those posts. Leave blank to let this rule work with all posts. .. image:: _static/form_post_whitelist.png :height: 88px :width: 760px :scale: 100% :alt: Post whitelist Post blacklist ============== Here you can enter a comma separated list of post IDs to add to the blacklist. If one or more IDs are entered, this rule will NOT trigger on those posts. Leave blank to let this rule work with all posts. .. image:: _static/form_post_blacklist.png :height: 88px :width: 759px :scale: 100% :alt: Post blacklist Options ======= Only active rules will be considered on status transitions. If you want to deactivate a rule, remove the check mark on the **"Active"** checkbox. With the option **Email** you can determine, if this rule should send emails or not. This is handy, if you just want to log status transitions. .. image:: _static/form6.jpg :height: 165px :width: 707px :scale: 100% :alt: Options If you want to create log entries, set the check mark on **Log**. Log entries will be written when a rule matches and when emails got sent. Save ==== When you have set all your options, click the button **"Add rule"**, to save the rule. .. image:: _static/form-add.jpg :height: 56px :width: 103px :scale: 100% :alt: Add rule button ******************* Rule administration ******************* Edit, Copy, Delete ~~~~~~~~~~~~~~~~~~ After saving a rule, it will appear in the rule table (tab "Rules"). .. image:: _static/rules-list.jpg :height: 349px :width: 901px :scale: 100% :alt: List of all rules From here you can manage your rules. When your cursor hovers a table row, you will see the links **"Edit"**, **"Copy"**, **"Export"** and **"Delete"**. If you click **"Edit"** the rule will be loaded in the above explained form (see :ref:`formfields`). Then you can change the rule settings and confirm by clicking the button **"Update"**. If you click the **"Copy"** link, the rule will get duplicated. If you click the **"Export"** link, the rule will get exported to a XML file which can be used for import. Bulk actions ~~~~~~~~~~~~ To edit multiple rules at the same time, you can mark the check boxes of the respective table rows and select an action of the **Bulk Actions**. Available actions are **"Delete"** (delete all marked rules), **"Activate"** and **"Deactivate"** (activate / deactivate the marked rules) and **Export** (exports all selected rules to a XML file). .. image:: _static/rules-list-bulk.jpg :height: 238px :width: 513px :scale: 100% :alt: Bulk actions of rules list Importing rules ~~~~~~~~~~~~~~~ .. image:: _static/rules-import.jpg :height: 366px :width: 613px :scale: 100% :alt: Import rules When you use the above mentioned ways to export rules, you can use the generated XML file to import those rules, e.g. on another WordPress installation. Click the link "**Import rules**". The import form will appear. Select the XML export file of your choice as "**Import file**". You may insert an "**Import prefix**". This text will be prepended to the imported rules names. This way you can identify the imported rules if there are already rules with the same name. If you do not want the imported rules to be active after import, check the option "**Deactivate imported rules**". .. _debug_rule: ********** Debug rule ********** If you do not know how to setup a notification rule for your custom use case, it is always a good choice to have a debug rule. The only task of that debug rule is to **capture** the post status transition of your custom use case. .. note:: You can **download the debug rule export file** on `PSN's resources page `_. Setting up a debug rule is very easy. Set **"Post type"** to **"all types"** as you want to capture all changes and you maybe do not know the exact Post Type of your use case. **"Status before"** and **"Status after"** should be set to **"anything"** as you want to be aware of every status transition. At the end of the form **do not check "Email", just "Active" and "Log"** as you do not want to receive emails for any change, you just want to analyse the log entries. The rest is optional. .. image:: _static/debug_rule_settings.jpg :height: 532px :width: 515px :scale: 100% :alt: Debug rule settings You can also click the button "Debug rule" in the right sidebar of the rule creation form which will set all options at once. .. image:: _static/rule_debug_button.png :height: 61px :width: 178px :scale: 100% :alt: Debug rule button Finally be sure to check the option **"Log rule matches"** in PSN's option page. This will create a special log entry containing all the information about the post status transition. .. image:: _static/options_log_rule_matches.jpg :height: 189px :width: 735px :scale: 100% :alt: Log rule matches Now you can create a demo content of your use case and check the PSN logs: .. image:: _static/debug_rule_log_entry.jpg :height: 184px :width: 719px :scale: 100% :alt: Debug rule log entry By clicking on the **"Show details"** link, you will see exactly what happened e.g. what was status before, status after and what placeholders were available. With that knowledge you now can setup a notificaton rule perfectly adjusted to your use case. .. image:: _static/debug_rule_log_details.jpg :height: 837px :width: 518px :scale: 100% :alt: Debug rule log details You can **download the debug rule export file** on `PSN's resources page `_.