Bulkmail Job
Last Updated: 24 Jan 2019
bulkmail|asset|5.5.2.0
A Bulkmail Job is where you define the content being sent for your bulkmail, as well as the recipients, headers, and content generation type. If a Bulkmail Job has been created as a child asset of a Bulkmail Post Office in the Asset Map, it will inherit the values of the post office. If, however, the Bulkmail Job was not created as a child of a Bulkmail Post Office, it will inherit the values of the default post office in the Bulkmail Manager.
Bookmarks to the headings on this page:
Tip: A Bulkmail Job can only be linked under a single post office.
Once your Bulkmail Job is created, you can configure its settings on its associated asset screens. The majority of these screens are the same or similar to those for a Standard Page and are described in the Asset Screens manual. In this chapter, we will only describe the Details and Preview screens, which are different for a Bulkmail Job.
Details Screen
The Details screen for a Bulkmail Job allows you to set up the email. For more information about the Status, Future Status, and Details section of the screen, refer to the Details Screen chapter in the Asset Screens manual.
Job Progress and History
By default, this section does not show on the screen until the job is either queued to run or is currently running, as shown in the figure below.
The Job Progress section of the Details screen
You can Cancel or Pause the job by selecting the appropriate value from the Control list. If you Pause the job you can Resume it at a later stage by selecting it from the list.
Tip: If you resume a paused job, it will not be processed until the next time the Scheduled Jobs Manager is run.
Once the job has been successfully completed, a record is added to the history list. This list shows you when the job was run and how many recipients the email was sent to. The figure below shows an example history list for a Bulkmail Job.
The Job Progress and History section displaying the Bulkmail Job history
Validate Job
The Validate Job section of the Details screen allows you check that the settings for the Bulkmail Job are correct. For example, the asset that contains the content for the email may not have a Status of Live or may not have the correct permissions set.
When you click on the Validate Job button, the list of setting errors will be listed, as shown in the figure below.
Validation errors in the Validate Job section
In this example, the asset that is being sent, Bulkmail Content, is not Live and the Subject field on the Bulkmail Post Office has not been entered. Once the settings for the Bulkmail Job have been fixed the following message will appear:
A valid job listed in the Validate Job section
The Bulkmail Job can now be sent.
Warning
This section is shown when the Bulkmail Job has been queued to run or is currently running, and informs you that if you make changes to the list of recipients, the contents of the email or the header details, the change will not take affect until next time the job is queued to run. If you want these changes to take affect, cancel the Bulkmail Job and re-run it. The warning message that appears is shown in the figure below.
The Warning section of the Details screen
Recipients
This section allows you to select which User Groups, Users or Bulkmail Users you want to send the email to. You can select as many recipients as you want by clicking the More… button.
Content and Content Generation
The Content and Content Generation section allows you to configure the contents for the email.
The fields available are as follows:
- Asset to Send: this field defines the asset you wish to use as the content for the Bulkmail Job.
- Generation Method: this field sets the method by which Squiz Matrix generates the output email for the Bulkmail Job:
- Generate as set user: this is the default option for generating content and is used to create a standard bulkmail output which will be the same for each recipient. When the Bulkmail Job is run, Squiz Matrix will log in as the user that is set in the Generate As field and generate the email. This email is then sent to each recipient in the list.
- Generate as recipient: this option generates the content of the email specifically for each recipient in the list. Squiz Matrix will log in as each recipient in sequence, format the appropriate contents and send the email. You should use this option if keyword replacements are used within the content of the email.
Tip: The Generate as recipient method is processor-intensive and takes a long time to run. The quickest method of running a Bulkmail Job is to not use keyword replacements within your email, to select the Generate as set user method, and the Public user as the Generate As field.
- Email Type: select whether to send the email as HTML or Text Only. If this is set to Text Only, the Design and Paint Layout applied to the email will be ignored. The contents of the asset will be sent in a text-only email with all tags stripped out. By default, this is set to HTML.
- Generate As: this field defines which user is used to generate the content for the Bulkmail Job. If the Generate asset user option is selected for the Generate Method field, this is the user that Squiz Matrix uses to generate the email content to send. If Generate as recipient is selected, the user set in this field is used if the user is a Bulkmail User as they do not have access to log into Squiz Matrix. Any keyword replacements in the email content, however, will still be replaced with the information from the Bulkmail User.
- Design: this field defines the Design to use for the Bulkmail Job. If a Design is not set for the Bulkmail Job, the Design applied to the asset being used for the content will be used for the bulkmail. This field allows you to use an existing page in your site for your Bulkmail Job, but define a different Design. For example, you may wish to create a Design based on your Site design but with no menu, asset lineage, search box or login box.
- Paint Layout: this field defines the Paint Layout to use for the Bulkmail Job. If a Paint Layout is not set for the Bulkmail Job, the Paint Layout applied to the asset being used for the content is used. This allows you to use an existing page in your site, but define a different Paint Layout to use for the Bulkmail Job.
- Body Text Filter: if this filter is enabled, only those emails where the body meets the criteria will be sent. This is useful when the Generation Method setting is set to Generate as Recipient, where each user's content may differ depending on the permissions that have been applied to the asset.
Header Details
The Header Details section of the Details screen section shows which Bulkmail Post Office the Bulkmail Job is using. For example, in the figure below, the Bulkmail Job is using the settings entered on the Bulkmail Post Office, as it was created as a child of the post office asset in the Asset Map
The Header Details section using the Bulkmail Post Office Header Details
If the Bulkmail Job was not created as a child of a Bulkmail Post Office, it will use the Bulkmail Manager for its default Header Details, as shown in the figure below.
The Header Details section using the Bulkmail Manager Default Post Office Header Details
If you wish to override the settings it inherits from the Bulkmail Post Office, deselect the Use Post Office Header Details field and click Commit. The following fields now appear in the Header Details section.
The Header Details section using custom Header Details
For more information on these fields, refer to the Bulkmail Manager chapter in this manual.
Job Scheduling Screen
The Job Scheduling screen allows you to configure automatic scheduling of the Bulkmail Job.
In the Enabled field, specify whether to enable job scheduling. By default, no scheduling will be configured on the Bulkmail Job.
When job scheduling is enabled, the Scheduling Details field allows you to set the date from which the job will be run and the frequency of recurring runs. In the Start Date field, enter the date that the Bulkmail Job will being it's initial run from; then, in the Repeating field, specify the recurrence rate of this job -- the options available include either Hourly, Daily, Weekly, Monthly, Yearly or None Selected (i.e. not at all).
Please note that the Bulkmail Job must be correctly configured for job scheduling to work. You can verify the validity of your configuration using the Validate Job tool on the Details screen of the Bulkmail Job asset. For more information, refer to the Details Screen section in this chapter.
User Subscription Screen
The User Subscription screen allows you to enable user-based subscriptions for the Bulkmail Job.
In the Enabled field, specify whether to enable user subscriptions. By default, subscriptions will not be enabled on the Bulkmail Job. When enabled, additional fields will be displayed on the User Subscription screen, as shown in the figure below.
Additional fields on the User Subscription screen
The Categories field settings allows you to configure rules to match against the recipient users configured on the Bulkmail Job.
In the New Categories field, enter the name for the category you want to configure and click Commit; the category will be added to the Categories table.
Once a category has been created, you can configure its rules. In the Add New Rule drop-down, select the rule to add on the subscription category -- please note that currently only the Asset Metadata Field rule type is available -- and click Commit. The Asset Metadata Field rule will be displayed in the category, as shown in the figure below.
The Categories field settings
On the Asset Metadata Field rule, you can select the metadata field to query the bulkmail recipients' metadata and enter the value to match against. This value can use either Contains or Matches search logic. If no query value is entered, all metadata values of the selected metadata field will be matched.
Setting Up the User Subscription
To set up a user subscription for a Bulkmail Job, a Search Page needs to also be created to allow your bulkmail articles to be queries and returned to subscribers. This Search Page is configured with the corresponding data of the subscription category created on the Bulkmail Job.
The below example details the creation of a subscription on a Bulkmail Job. This subscription allows users to receive content specific to their locale.
- On the User Subscription screen of the Bulkmail Job, create a new subscription category named location. Please note that you must first enable subscriptions in the Enabled field if you have not already.
- Add a new Asset Metadata Field rule on the location category and select a metadata field that has been applied on your users. This metadata field value should contain the location subscription for each user (for example, Sydney or Melbourne).
- Select the Contains parameter for the Asset Metadata Field rule and enter a location, such as Sydney, as shown in the figure below.
Creating the 'location' user subscription categoryTip: You can create additional rules to the location category for other locales, such as Melbourne.
- Create a Search Page that uses the location of your bulkmail articles as the Root Node of the search query (on the Details screen).
- On the Search Fields screen of the Search Page, create a new search field and configure its settings. These settings determine how user's metadata values (e.g. Sydney or Melbourne) will be queried amongst the bulkmail articles. For more information, refer to the Search Page chapter of the Search manual.
- Back on the Details screen of the Search Page, create a new Stored Query Location (Stored Search section) for the search field you have just created. Use the subscription category name as the GET Variable Name source, in this case, location, as shown in the figure below.
Configuring the Stored Query Location settings - In the Stored Search Options section, enable the Show the Results Page option.
- Next, define the layout of the Search Page on the Default Format and Results Bodycopies. This will establish the information sent to subscribed users (via the bulkmail email).
- Finally, on the Details screen of the Bulkmail Job, select the newly configured Search Page in the Asset to Send field.
The user subscription has now been created. When the Bulkmail Job is run, the recipients of the job will be matched against the user subscription rule, i.e. their metadata will be queried with the rule value specified, such as Sydney. Corresponding recipients will be identified as subscribers of the Bulkmail Job, using the location subscription category.
The recipient's metadata values (from the specified metadata field) will then be queried against your bulkmail articles, as configured on the Search Page. The results of this search will be sent to the bulkmail recipients via the bulkmail email. So, for example, if the user's location is Sydney, the user will receive a list of articles that contain the keyword Sydney in them.
Preview Screen
This Preview screen is different to the Preview screen available for other assets. It allows you to send a test email so you can see what the email will look like when the Bulkmail Job is run.
Enter the email address you want to send the test email to and click Commit. The email will be sent and a message added onto the preview screen informing you a test email was sent as shown in figure below.
Logged emails on the Preview screen