LISTSERV Maestro 8.1-4 Help

Delivery Settings

Information about when and how often to deliver the email job.

Basic Delivery Options

To schedule a job for delivery, select the option for the delivery scheduling desired. There are three basic options for scheduling the delivery of the job after it has been authorized:

• Immediately begin delivering the mail job: With this option, the job will be delivered immediately after it is authorized.

• Wait until mail job delivery is triggered: With this option, the authorized job will not be delivered until delivery is triggered explicitly. This means that the authorized job remains in a waiting state (in the Ongoing Jobs list) until this trigger happens. The delivery can be triggered manually from inside of LISTSERV Maestro or through an external trigger of the type "Simple URL Access" (see below). The security token that is required for the external trigger can be obtained from the job's details page once the job has been authorized for delivery.

• Schedule the mail job delivery to begin at the following time: With this option, the user can specify the exact date and time to begin delivery of a job. Enter both the date and time in the format shown at the right of the edit boxes. Scheduled delivery dates and times must occur in the future of your present session for this to work correctly.

The authorization for delivery occurs in its own job-related workflow step that can only be executed after the delivery schedule is defined.

Advanced Delivery Options

In addition to the basic options described above, there are also advanced options available for defining the delivery schedule.

The advanced options are disabled by default. Click on the click to enable link to enable the advanced options. If you want to disable the advanced options at a later time, click on the click to disable link that appears together with the advanced options. The advanced options are enabled or disabled on a per-job basis.

The advanced options available are:

• Normal Delivery: With this option, the mail job will be delivered only once, at the delivery time specified in the basic options (see above), and it will be delivered to exactly the recipients that exist at delivery time, no more, no less. This is the default. It is also used when the advanced delivery options are disabled.

• Extended Delivery: This advanced option is only available if the mail job's recipients are set to the "Send to a List or Dataset in the Subscriber Warehouse" type. The option is not visible for a job that has recipients of a different type, or if the recipients are not yet defined.

  With this option, the mail job will initially be delivered to the recipients that exist at delivery time. The job will also be marked as "completed" at this point, so that it is for example available for tracking reporting. However, the job will continue to scan for further additional recipients that may become available over the specified extended delivery period. This extended delivery period can be set to either open-ended or to end at a specific date and time.

  During this period, the job will scan for new recipients once per day, at the same time of day as was used for the initial delivery. If any new recipients are found, then the same content is sent to these new recipients as was sent to the initial recipients and the recipient count of the mail job is increased accordingly.

  When scanning for new recipients, the job simply applies the same recipient selection condition to the underlying subscriber list as it originally used during the initial delivery. Any subscriber that now fulfills this condition and that was not already a recipient of the same job, will then be treated as a new recipient.

  For example: A job was defined without a recipient selection condition. Therefore, the initial delivery included all subscribers of the list as recipients. With extended delivery active, each day after the initial delivery the job will again be sent to all subscribers of the list that did not already receive the job. In other words, the previously existing subscribers will be ignored during this extended delivery period, as they already were recipients of the job. But any new subscribers that are added to the list during the extended delivery period will then also receive the job, since they then fulfill the trivial default condition of "being subscribed to the list".

  Or a job that was defined with a condition to only include subscribers that specified "Sweden" as the country of residence. The initial delivery therefore included only the subscribers with this profile setting. With extended delivery active, on each of the following days, the job will again be sent to all subscribers with "Country=Sweden" that did not already receive the job. This can potentially include two types of subscribers: New subscribers that were not on the list during the initial delivery and that subscribed at a later time, with "Country=Sweden" in their profile. But also existing subscribers that were already on the list during the initial delivery, but who at this time had specified a country different than Sweden (and which were therefore not included as recipients), who have since then moved to Sweden and have therefore modified their country profile field, so that now they do fulfill the recipient selection condition.

• Repeated Delivery of Job Copies (Auto-Repeat): With this option, the job will start an auto-repeat sequence upon delivery. Further information concerning Auto-repeat Jobs is shown below.

  Triggered auto-repeat delivery: If you chose triggered delivery in the basic options above, then each delivery occurs when triggered. Right after the triggered delivery has occurred, an exact copy of the job will automatically be created and authorized for delivery, again waiting for its delivery trigger. Once this copy has been delivered, another copy will be created and authorized and is waiting for the triggered delivery, and so on, until stopped manually.

  Standard auto-repeat delivery: The job will be delivered for the first time at the time specified in the basic options (see above). Right after the job has been delivered, an exact copy of it will automatically be created and authorized for delivery, with a delivery time that is scheduled at a given interval after the first delivery.

  Once this copy of the job has been delivered, another copy will be created and authorized, again with a scheduled delivery time that is offset from the previous delivery by the same interval, and so on, until the defined auto-repeat end-condition is met (see below).

  If this option is chosen, then you must supply the delay interval between each repeated delivery of a copy of the original job by entering a positive value into the Delay interval between repeated deliveries field and choosing an appropriate time unit from the selection list. You may choose between hours, days, weeks, and months.

  In addition, you must specify the end condition to stop the auto-repeat sequence. Select one of these options:

  • Repeat until stopped manually: After each delivery, a new auto-repeat copy will always be created and authorized. This can only be stopped manually by selecting the latest copy, located in the ongoing jobs list awaiting delivery, and revoking its delivery authorization.

  • Repeat until the following threshold time: With this option you must specify the threshold date and time to stop the auto-repeat sequence. After each delivery, a new auto-repeat copy is created and authorized only if its designated delivery time (the time of the previous delivery plus the specified interval) is not later than the date and time specified here.

• Time zone to be applied to the dates and times specified above: This option allows the choice of which time zone to use when determining what time a job is sent. For example, if the server is located in London (GMT 00:00) and the user is based in New York (GMT -05:00), when the user specifies 10:00 what time will the job be sent? Will it be 10:00 London time or 10:00 New York time?

  Note: This setting will not alter the time put into the date of the email. This value is inserted by the SMTP server at the time of delivery and is usually based on local settings. This is not incorrect as it accurately reflects the time the email was actually sent.

---

About Auto-Repeat Jobs

Auto-repeat jobs are made up of a sequence of identical jobs based on the first job created in the series and scheduled to be delivered at regular programmable intervals. Various settings control the auto-repeat sequence, and these sequences can be used in many ways. Topics to consider when creating and using auto-repeat sequences are:

• Specifying the Delivery Time
• Auto-Repeat Jobs together with Dynamic Recipients or Dynamic Content
• Auto-Repeat Jobs and Delivery Failures
• Auto-Repeat Jobs and System Shutdown
• Revoking and Re-Authorizing Auto-Repeat Jobs

Specifying the Delivery Time

The delivery time of auto-repeat jobs is defined as follows:

The first job in the auto-repeat sequence will be delivered at the date and time specified in the basic options of the Schedule Delivery page (see above).

Each subsequent copy of the original job will then be delivered a certain amount of time after the previous delivery, which is defined in the advanced options as the Delay interval between repeated deliveries.

Examples:

• If you specify "Immediate Delivery" and a repeat interval of "12 Hours" for the first job and authorize that job at 09:15, then the initial job would be delivered at 09:15, the first copy would be delivered at 21:15, the second copy at 09:15 of the next day, and so on.
• If you specify "Deliver at 12:00" and a repeat interval of "24 Hours" (or for the same effect "1 Day"), then you would get one delivery each day, at 12:00.
• If you specify "Deliver at 10:20 on Nov. 25th 2004" (which happens to be a Monday) and a repeat interval of "2 Weeks", then this would cause a copy of the job to be delivered at 10:20 of the Monday of every second week after the initial delivery.
• If you specify "Deliver at 12:00 on Jan. 1st 2005" and a repeat interval of "3 Months", you would get a delivery on the first of each of the months January, April, July, and October resulting in one mailing at the beginning of each quarter.

Auto-Repeat Jobs Used Together with Dynamic Recipients or Dynamic Content

Auto-Repeat delivery is particularly useful together with dynamic recipients and/or dynamic content:

• Dynamic recipients are the just-in-time variants of recipients defined by text upload or a select from a database, as well as Classic LISTSERV lists, LISTSERV Maestro subscriber lists or recipients selected from a database by LISTSERV. What all these recipient types have in common is that the actual list of recipients a job will be mailed to is determined "just-in-time" at the moment prior to delivery. If such a job auto-repeats itself, each repeated copy may be mailed to a different list of recipients.

  This strategy can be employed in many ways. An example of using dynamic recipients could be sending a generic "Your account balance is negative" warning message, on the 1st of each month, to the recipients who have a negative account balance on that day.

  To set up such an auto-repeat job, you would create a job with static content telling the recipients that their account balance is negative (probably using the balance value as a merge field). You would use a recipient definition that is "just-in-time" and that selects exactly those recipients from the database where the account balance is negative. Next, you would schedule this job to be delivered at a certain hour of the first day of the next month, with a repeat interval of "1 Month". After the initial authorization of that first job, the mail would automatically go out at the set hour of the 1st of each month, to only the recipients with a negative account balance.

• Dynamic content uses drop-ins to pull content into the message "just-in-time" before delivery. Like dynamic recipients, this can be employed in useful ways.

  For example, each morning you could automatically mail the daily weather forecast to all subscribers. To do this, you would set up a job with content that uses a drop-in that pulls the text of the daily forecast from a suitable source (for example from a web server). Next, you would schedule this job to be delivered at a certain hour of the next day, with a repeat interval of "1 Day". Before setting the hour of delivery you would have to make sure that the source of your weather forecast drop-in is updated before the hour of the delivery time. After the initial authorization of that first job, the mail would automatically go out at the scheduled hour each day, with a different forecast (as pulled from the web server source by the drop-in) each day.

Auto-Repeat Jobs and Delivery Failures

If delivery of an auto-repeat job fails for any reason, the failure is handled slightly differently than with normal jobs. A normal job that fails remains in the ongoing jobs list and is marked as failed. You then have the option of closing the job (transferring it into the list of completed jobs), retrying the delivery or re-opening the job for editing.

With auto-repeat jobs, failures are handled in this way:

The failed job is marked as failed as usual, only it is automatically closed and transferred to the list of completed jobs, just as if the user had manually closed a failed normal job. If the end condition for the auto-repeat has not yet been met, a new copy is created and authorized to be delivered after the corresponding delay interval, just as if the delivery of the previous job had succeeded.

As a result, if at a given delivery time some condition (that may exist outside of LISTSERV Maestro, for example the accessibility of a database) causes the delivery to fail, then only this auto-repeat instance will fail. The next auto-repeat instance will be created and authorized normally, and will proceed to be delivered at its scheduled delivery time. If the condition that caused the first failure still exists at the next interval, then the delivery of the next copy will probably fail as well. But the copy after that (if there is one) may have a chance to get through if conditions change, and so on.

Note: "No recipients found" is also a reason for a delivery failure. However, in the context of auto-repeat jobs, this may actually be an acceptable state if there are no recipients to fit the conditions of the job. In the example above, a message was supposed to be delivered to all recipients with a negative account balance on the 1st of each month. If in a given month there are no recipients with a negative account balance, no mail would be sent out for that month, and the job instance for that month would fail with "No recipients found" as the reason for failure. In this case, the failure should be interpreted as a valid state because there simply were no recipients to which the mail had to be delivered on that day. The auto-repeat sequence would continue with another copy for the next month; therefore, if any recipients have a negative balance on the 1st of the next month, then they would get the reminder mail.

Auto-Repeat Jobs and System Shutdown

Auto-repeat jobs do not act like normal jobs if the system is shut down during the scheduled delivery time.

For a normal job, if the system is down at the scheduled delivery time, the job will be delivered immediately after the system is started the next time. The system will recognize that the delivery time of the job has passed while the system was down and will immediately start the delivery to "make up" for the lost time.

This is not true for auto-repeat jobs. If the system is down at the scheduled delivery time of an auto-repeat job, then the system will recognize that the delivery time of the job has passed while the system was down. Instead of starting delivery immediately, the job will be re-scheduled to the next available "delivery slot" of the auto-repeat sequence it belongs to. The job will remain in the ongoing jobs list as "authorized for delivery", but now with a new delivery time that occurs after the system startup. If there is no such delivery slot available because the end condition for the auto-repeat has already been met, (the threshold time has passed) the job will be marked as failed with a corresponding error message and will immediately be transferred to the list of completed jobs (as explained above, in Auto-Repeat Jobs and Delivery Failures).

Example:

If a job is scheduled to be delivered at 08:00, with an auto-repeat delay interval of "12 hours" (the job is supposed to repeat itself at 08:00 and 20:00 of each day), but the system is down at that time, then during the next system startup, the job will be re-scheduled from 08:00 to 20:00. Or if the next system startup occurs after 20:00 of that day, the job will be re-scheduled to 08:00 of the next day, or even 20:00 of the next day, if necessary, and so on until a delivery time is found that occurs after the system startup. During the whole process, the job will not fail and no new job copies are created. The system simply takes the job that should have been delivered earlier and re-schedules it for the next available delivery time. If the job was supposed to stop auto-repeating itself at a time that has passed before the system startup, the system will not find a "next available delivery time" for re-scheduling. In that case, the job will fail with an according message.

Revoking and Re-Authorizing Auto-Repeat Jobs

Any auto-repeat job currently in the ongoing jobs list awaiting its scheduled delivery time can have its delivery authorization revoked just like a normal job. If authorization is revoked, the job will be put back into the Open Jobs list, where you can edit it again.

If this job is re-authorized for future delivery, where does this job stand in respect to the auto-repeat sequence it was part of before the authorization was revoked? The possibilities are listed below:

• The job is the first job of an auto-repeat sequence: This means that no delivery has taken place for this job because it was the first job of the sequence and was revoked before its scheduled delivery time. When re-authorized, the job will simply continue to be the first (and still only) job of the same auto-repeat sequence it belonged to before.
   
• The job is not the first job of the auto-repeat sequence and has been changed since the delivery authorization was revoked: This means that this job is already an automatically created copy that is part of an auto-repeat sequence. The delivery authorization of this job was revoked and then it was changed in some way. When re-authorized, the job will create a new auto-repeat sequence and it will no longer be part of the sequence it belonged to before the delivery authorization was revoked. This happens because job is no longer an exact copy of the previous jobs in its original sequence. Instead, it will, by itself, be the first (and still only) job of a new auto-repeat sequence.
   
• The job is not the first job of the auto-repeat sequence but has not been changed since the delivery authorization was revoked: This means that this job is already an automatically created copy that is part of an auto-repeat sequence. The delivery authorization of this job was revoked, but it has not changed the job since then. When re-authorized, the job can either continue as part of the same auto-repeat sequence, or it can start a new auto-repeat sequence. You will have to make this choice on the Authorize Delivery screen.

Note: A job is defined as changed since authorization was revoked if you have changed either the recipients definition, content definition, tracking definition, or sender definition of the job since the delivery authorization was revoked. If these four parts remained unchanged, then the job is interpreted as unchanged. In this respect, changes on the Delivery Test or Schedule Delivery screens are not interpreted as changes to the job.

---

External Triggers

LISTSERV Maestro offers several actions that can be triggered remotely from an external source by simply accessing a special external trigger URL, via the HTTP protocol. This trigger URL can be accessed without the need to first login to LISTSERV Maestro.

With this, several scenarios are possible:

• If there are actions that need to be triggered manually by a user who does not want to login to LISTSERV Maestro first; then, the user could create bookmarks in his browser, where each bookmark contains a trigger URL and stands for an action that can be triggered. Or, perhaps a custom-made HTML page could be created with links that point to the trigger URLs.

• In a different scenario, these actions could be triggered by another process, such as a script or program. To trigger an action, all this other process has to do is to open a HTTP communication to the action's trigger URL. This type of external process could, for example, trigger an action according to a certain time schedule or each time a certain outside event happens.

To secure the external trigger URLs against unauthorized access, a security token needs to be included in each URL. Each action that can be triggered externally has a unique security token. Therefore, the security token in the URL serves two purposes: It identifies the action that is to be triggered, and it validates that the user or process that makes this request is indeed authorized to do so.

The security token for the action in question can be obtained from inside of the LISTSERV Maestro user interface. The exact location where the token can be obtained depends on the action that it stands for. Please see the description of the action in question for this information.

Important: You should make sure that this security token is not given out to unauthorized persons because anyone who knows the security token of a certain action is able to trigger this action, as long as he also has HTTP access to the LISTSERV Maestro server. If you suspect that an unauthorized person has gained access to the token, then you can create a new token (and invalidate the existing token) by clicking the appropriate link at the location where you obtained the token.

A trigger URL always has the following form:

http://SERVER_NAME/lui/externalAction.do?token=SECURITY_TOKEN

• where SERVER_NAME is replaced with the name of your LISTSERV Maestro server. (If a non-standard HTTP port is used, also include the port, separated with a colon ":". If access to your LISTSERV Maestro is protected with HTTPS, you need to specify "https://" instead of "http://".)

• where SECURITY_TOKEN is replaced with the security token for the action that the URL shall trigger.

External triggers come in two variants:

• Simple URL Access: The action is triggered by accessing the external trigger URL with a HTTP GET request.

  By accessing this URL, a HTTP GET request is made to LISTSERV Maestro. The server then first verifies the given security token and, if it is valid, triggers the corresponding action. The result of the action is returned in the form of a HTTP response.

  If everything went well, a response with the status code "200 - OK" is returned. In this case, the response body contains the result of the action. Most actions return a simple "OK" text in the result, but some actions may also return more data in the result; for example, if the purpose of the action was to download certain data from LISTSERV Maestro.

  If there was a problem executing the action, a response with a different status code is returned, such as "404 - Not Found" if an invalid security token was specified.

• URL Access with Additional Data: The action is triggered by accessing the external trigger URL with a HTTP POST request.

  In contrast to the "simple URL access" of above, the trigger URL must be accessed with a HTTP POST request, and the additional data that is necessary for the action must be included as part of the request body. The data that is required depends on the action in question. Please see the description of the action for this information.

  The result of the action is returned in form of a HTTP response, just like for the "simple URL access". Please see above for details.