LISTSERV Maestro 8.1-4 Help

A/B-Split Job Details

The A/B-Split Job Details screen lets you access the details of an A/B-split job so that you can view and edit the various job parts and variant jobs.

You will be presented with summaries of the most important information about the A/B-split job and its variant jobs, and you can use the associated Edit links to edit any of the job parts or variants:

• A/B-Split Job
  Edit the job title, job-ID prefix, job type, delivery notification, "authorization due by" date, and auto-archive settings.

  Not all settings may be editable at all times, depending on the A/B-split job's state.

• Recipients
  Define the recipients of the A/B-split job.

  Depending on the A/B-split job's state, this section may not be available.

• Variant Jobs
  Define the variant jobs that are part of the A/B-split job. Each variant job is displayed in a separate row, with job ID, job title, and four state icons representing the four aspects that are unique to each variant job - Content, Tracking, Sender, and Test. The state icons reflect the states of the corresponding workflow steps of each of the variant jobs. Click on a variant job's ID to edit this job.

  In addition, a Delete link may appear next to each variant job, allowing you to delete the corresponding variant job (the link does not appear if only the minimum number of variant jobs is present in the A/B-split job).

  Click the Add Variant Job link at the bottom of the list to add another variant job to the A/B-split job.

  For A/B-split jobs with sampling, you also have the choice to define the settings of the main job manually or to let LISTSERV Maestro do this automatically. If the manual choice is selected, then the variant jobs are separated into two tabs labelled Sampling Variant Jobs and Main Variant Job. The first tab contains all sampling variants while the second tab contains only the main variant in the A/B-split job (the main variant can never be deleted and there is no link to add more variants on this tab because there can only be one main variant).

  If the automatic choice is selected, then LISTSERV Maestro will automatically pick the most successful of the sampling variants, based on their tracking results, and use this variant's message and other settings for the main variant and then automatically authorize the delivery of the main variant.

  In this case, the main variant job itself is not accessible for editing. Instead there is the additional Automatic Main Variant Selection section where you can define the tracking metric by which LISTSERV Maestro shall select the most successful sampling variant, when to do this selection, and when to start the automatic delivery of the main variant.

  Adding, editing, or deleting variants is only possible if the A/B-split job's state allows it.

• Delivery / Sampling Delivery / Main Delivery
  Schedule the delivery of the A/B-split variant jobs to take place immediately after authorization, when triggered, or at a future date and time relative to a selected time zone.

  For a normal A/B-split job, the section is called Delivery and its settings either apply to all variant jobs equally (common delivery settings), or each variant job may have its own delivery settings (individual delivery settings). This type of common or individual settings is defined via the Edit link of the A/B-Split Job section (see above). Depending on the type, the Delivery section either also shows an Edit link, to edit the common delivery settings, or it shows a list of all variant jobs, with the job IDs as clickable links to define the individual delivery settings.
  No matter which type, the authorization of the variants in a standard A/B-split job always applies to all variants, i.e. all variants are authorized at the same time.
  This also means that a standard A/B-split job can only be authorized once the delivery settings for all variants have been defined (either common or individual), and also of course only once all variants have been completed (all four states of all variant jobs are complete and marked with the green check mark). Once a standard A/B-split job is authorized, all variants are authorized and will be delivered according to the common or individual delivery settings defined here.

  For an A/B-split job with sampling and manual definition of the main variant settings, there are two separate delivery settings that need to be defined - Sampling Delivery, which applies to the sampling variants, and Main Delivery, which applies only to the main variant. Therefore, for a sampling A/B-split job, the respective delivery settings are included on the Sampling Variant Jobs tab and the Main Variant Job tab.
  While the main variant is always only a single variant, with its own delivery settings, there are always several sampling variants (at least two). For these, the delivery settings can either apply to all sampling variant jobs equally (common delivery settings), or each sampling variant job may have its own delivery settings (individual delivery settings). This type of common or individual settings is defined via the Edit link of the A/B-Split Job section (see above). Depending on the type, the Sampling Delivery section either also shows an Edit link, to edit the common delivery settings, or it shows a list of all sampling variant jobs, with the job IDs as clickable links to define the individual delivery settings.
  The authorizations of the sampling variants and the main variant happen one after the other. The sampling variants have to be authorized first, which is only possible if all sampling variants are complete (with green check marks, similar to a standard A/B-split job) and their delivery settings, either common or individual, have been defined. Once the variant delivery is authorized, all sampling variant jobs will be delivered according to the Sampling Delivery settings. Authorization of the main variant is only possible after the delivery of all sampling variants has been completed (either successfully or with failure). Also, the main variant job must be completed first (with green check marks), including its delivery settings. Once authorized, it will be delivered according to the Main Delivery settings.

  For an A/B-split job with sampling and automatic definition of the main variant, only the delivery settings for the sampling variants need to be defined, in the same was as described above, because the settings for the main variant are defined in the Automatic Main Variant Selection section instead. In this case, it is also not necessary to authorize the main variant for delivery, as this will happen automatically.

  If all or some of the variant jobs have their delivery settings set to Triggered Delivery, then this delivery can be triggered either from inside of LISTSERV Maestro (via the "Edit" menu), 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 variant jobs. The security token should therefore be closely guarded and not be given out to unauthorized persons.
  Because of this, the screen 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 person 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.

  For a 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 here, once the variants have been authorized. The variants do not have individual security tokens.
  If the common security token is used to trigger the action, then this will trigger the delivery of all variants.

  For a 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 here, once the variants have been authorized. Neither the sampling variants nor the main variant have individual security tokens.
  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 the main variant is authorized, then the same security token is used to trigger its delivery too.

  If the A/B-split job has individual delivery settings for the variants (either standard variants or sampling variants), then this page here does not contain a delivery security token because in such a case each variant also as an individual security token. These tokens can then be found on the individual job details pages of the variants (once the variants have been authorized).

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.