LISTSERV Maestro 8.1-4 Help

Ongoing Job Details

The Job Details pane of an ongoing job lets you access the details of a mail job that has been approved for delivery and is awaiting a future delivery time, is currently being processed, or has failed delivery.

In addition to showing a preview of the selected job's content on the Preview tab, this pane also gives you an overview of the job details on the Summary tab. You can switch between them by clicking on the respective tab.

If the current job is part of a message sequence, then the Sequence Info tab is available and shows additional details regarding the job and its predecessors and/or successors in the sequence.

Click on the View link for a specific section on the Summary tab to see the corresponding job details. Details cannot be edited from this tab. If you want to edit the job again, you need to revoke its delivery authorization (for authorized jobs whose processing has not yet started) or re-open it again (for failed jobs).

On the Summary tab, you can click the maximize icon in the top right corner to maximize the summary to full window size.

Jobs with "Triggered Delivery"

If "triggered delivery" is configured for a job, then this delivery can be triggered either from inside of LISTSERV Maestro (via the Edit menu, see above), or it can be triggered externally with an external trigger.

The external delivery trigger is of the "Simple URL Access" type and does not contain any download data in its response. See below for more details about external triggers and what this means in detail.

For the external trigger, a special security token is required.

Important: Everyone who is in possession of this security token and who can also access LISTSERV Maestro on its HTTP port (for example, with a normal web browser) will be able to trigger the delivery of the job. Therefore, the security token should be closely guarded and not be given out to unauthorized persons. Because of this, the tab does not display the token directly (so no one can simply look over your shoulder and "steal" the token). To display the token, you first have to click on the Show Security Token for Delivery Trigger link (this security token is not required for a manual trigger via the menu).

Creating a new Security Token: If you suspect that an unauthorized party has gained access to the security token, you can use the Create New Security Token link to invalidate the previously used token and to create a new one.

Delivery trigger security tokens are assigned to jobs as follows:

• Standard Job: Each standard job has a unique security token, which can be obtained from the job's details tab once the job has been authorized.

• Auto-Repeat Job: All jobs in an auto-repeat chain have the same security token, which can be obtained from the details tab of one of the jobs in the chain (while the job is authorized). This can be used to set up an auto-repeat job with "Triggered Delivery" and an external process that knows the security token for this auto-repeat job (or rather, the auto-repeat job chain that is started with this job). Whenever the external process uses the security token to trigger the delivery of the job, the job will be delivered and a new job in the auto-repeat chain will be spawned, which in turn waits in the list of "Ongoing Jobs" until the external process uses the same security token again to trigger this new job's delivery. Therefore, the external process can independently determine how often a new job in the auto-repeat chain is to be delivered.

• A/B-Split Job: The delivery trigger security token for A/B-split jobs are assigned depending on one of the following four cases:

  • Standard A/B-split job with common delivery settings for variants: The A/B-split job has a common security token that can be obtained on the A/B-split job's details page once the variants have been authorized. The variants do not have individual security tokens; therefore, the job details tab here does not contain an individual security token if the job is a variant of such an A/B-split job. If the common security token is used to trigger the action, then this will trigger the delivery of all variants.

  • Sampling A/B-split job with common delivery settings for the sampling variants: The A/B-split job has a common security token that can be obtained on the A/B-split job's details page once the variants have been authorized. Neither the sampling variants nor the main variant have individual security tokens; therefore, the job details tab here does not contain an individual security token if the job is a variant of such an A/B-split job. If the common security token is used to trigger the action, then this will trigger either the delivery of the sampling variants or the delivery of the main variant, depending on which variants are currently authorized for delivery. I.e., in this case the security token has to be used twice: At first the sampling variants are authorized, then the security token is used to trigger their delivery. Later, when the main variant is authorized, the same security token is used to trigger its delivery too.

  • Standard A/B-split job with individual delivery settings for variants: The A/B-split job does not have a common security token. Instead, each variant has an individual security token that can be obtained from the variant job's details tab here, once the variant job has been authorized, just as for a normal mail job. Each individual security token must be used to trigger the delivery of each individual variant job. This allows you to trigger the variants at different times.

    As a specialty, the security tokens of the variant jobs are very similar: Each security token is the same as the security tokens of its sibling variants, except for a unique suffix. The first variant will have the suffix "-A", the second the suffix "-B", and so on. That way, you only need to know the security token for one variant, and how many variants there are, to be able to trigger all variants. Simply vary the suffix that you use in the trigger URL to target a specific variant. This is especially useful when setting up an external script or process to do this triggering because you only need to tell the process the common part of the security token, plus how many variants there are. The process can then build the complete security token for each variant by extending the common part with the correct suffix for each variant job.

  • Sampling A/B-split job with individual delivery settings for variants: The A/B-split job does not have a common security token. Instead, each sampling variant and the main variant has an individual security token that can be obtained from the variant job's details tab here, once the variant job has been authorized, just as for a normal mail job.
    Each individual security token must be used to trigger the delivery of each individual variant job. This allows you to trigger the variants at different times. The same similar security tokens with different suffixes are used for the variants as described above for "Standard A/B-split job with individual delivery settings for variants".

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.