LISTSERV Maestro 8.1-4 Help

Subscriber Dataset Definition

The Subscriber Dataset wizard lets you define the settings of a new dataset or edit an existing dataset.

Note: A dataset is only fully editable while it is "empty", meaning that there are no subscribers or any lists in the dataset. For a non-empty dataset, only certain settings are editable.

The wizard has four pages: General, Profile Fields, Profile Field Details, and Summary.

The top row of the wizard displays links to these four pages. The page that is currently open is marked with a highlighted background color. Depending on the choices made on some of the wizard pages, other pages may become disabled or may be shown in different versions. If a wizard page is disabled, then it means that this page is not necessary with the current choices and can safely be ignored.

General Page: Name, Description and Advanced Dataset Settings

This screen defines the general settings of the dataset:

• Name: The name of the dataset is used both internally in LISTSERV Maestro as well as displayed externally to subscribers as the name of the dataset's subscriber area. The name must be unique. There cannot be two datasets with the same name in the subscriber warehouse.
   
• List-Administrator (Email address): The email address that is used as the "From:" address for all email sent "in the name" of the dataset, for example, double opt-in confirmation messages. This address must be a valid Internet email address.
   
• Internal Description: The internal description of the dataset is only used inside of LISTSERV Maestro, and it is not visible externally to subscribers.
   
• Public Description: An optional public description that is visible externally to subscribers as the description of the dataset's subscriber area.
   
• Dataset Mode: Defines if the dataset is in single list mode (which is the default) or in multiple list mode. A dataset in single list mode can only contain one single subscriber list. This allows for a simplified user interface both in LISTSERV Maestro itself (i.e. for the dataset and list owner) and for the subscribers (i.e. on the customizable subscriber pages), compared to a dataset in multiple list mode, which can contain several subscriber lists.
  If you have only one subscriber list anyway, then it is recommended to put it into single list mode dataset. If you have several but unrelated subscriber lists, then it is recommended to put them into several separate single list mode datasets. But if you have several related lists, then it is recommended to put them into a shared multiple list mode dataset. See here for more help on how to structure your datasets and subscriber lists and choose between single and multiple list mode.

Advanced Settings

• Access Pages Language: The language that is used to generate the access pages (the subscriber area pages). By default, only "English" is available. Other languages can be added by the LISTSERV Maestro administrator.

• Subscriber Area Password: Select when the subscriber area password is to be defined by each dataset subscriber. You can choose between Defined by the dataset subscriber before first manual login and Defined by the dataset subscriber when joining. This choice only affects how the initial password is defined when a subscriber joins the subscriber area. In both cases it is still possible for the subscriber to change his password at a later time.
  If the password is defined already when joining, then the join step has the additional slight inconvenience that the subscriber must also specify the password he wants to use, but the first login will be quick and easy because the password is already defined. In comparison, if the password is defined later, before the first manual login, then the join (or subscribe) step is more streamlined because the subscriber is not bothered to define a password. But the first login will be more inconvenient because then the subscriber will first have to define a password and confirm this password with a second confirmation email roundtrip.
  If your dataset has a number of lists that the subscribers can subscribe to and/or the dataset or lists have non-trivial subscription profiles that subscribers may want to edit on a regular basis, i.e. if you expect that your subscribers will login to the subscriber area regularly, then it is probably a good idea to use the "defined during join" option. This is a bit more inconvenient during join, but in such a situation you would expect your subscribers to need a password anyway, sooner or later, so defining it already during join saves the subscribers from the hassle of having to go through an additional confirmation email roundtrip before the first login.
  If your dataset has only a few lists with simple subscriber profiles, i.e. if you expect that, after joining or subscribing, the subscribers will usually not have to login to the subscriber area at all, then the "defined before first login" option is usually the best option, as it streamlines the join/subscribe process and moves the inconvenience of having to define a password to the login step that will usually not be encountered by most subscribers anyway.
  
  Note: If the LISTSERV Interface Link option (see below) is enabled, then the only available choice for the subscription password is the Defined by the dataset subscriber before first manual login option.

• Quick Login: Define if a special "quick login" option shall be available on the login page of the subscriber area. If checked, then an additional checkbox appears on the subscriber area login page. If a dataset subscriber checks this additional option during login, then his login information is remembered by the system; therefore, when he visits the login page again (with the same browser on the same computer), the email address and password fields are already filled out and the subscriber only needs to click the [Login] button to login.

• LISTSERV Interface Link: Define if additional links to the LISTSERV Archive pages shall appear in the subscriber area. If checked, then these additional links can be used by subscribers to switch over to the LISTSERV Archive pages without having to login separately; therefore, they can view any LISTSERV list archive that is accessible. Consequently, enabling this option only makes sense if the dataset contains any Advanced Subscriber Lists or Linked LISTSERV Lists for which an archive is available.
  
  Note: This option on the General page is only available if it has previously been enabled by the LISTSERV Maestro administrator (this is a setting in the Administration Hub).
  
  Note: If you enable this option for a dataset, then the Subscriber Area Password option (see above) is automatically set to "system defined password" and can no longer be changed to "user defined password".

• Individual Mail Limit: Define if there shall be a limit for each dataset subscriber of how many individual emails shall be sent to that subscriber. If this option is enabled, then you also need to fill out the values for the "No more than [ X ] mails over [ Y ] days" edit fields.
  
  The limit works as follows: If a mail job is targeted to the subscribers of this dataset (either via a direct mailing to the dataset, or via a mailing to one of the lists in the dataset), then subscribers that already received X mails during the last Y days will not receive this message, even if they otherwise fulfill all conditions for a recipient of the mail job.

• External Download: The subscribers of the dataset can be downloaded via an external download URL, i.e. an URL that can be accessed without first logging in to LISTSERV Maestro. This external download URL is a so called "external trigger" of the type "Simple URL Access", with the download data in the body of the HTTP response (in form of a ZIP file). See below for more details about external triggers and what this means in detail.
  
  For the external trigger, a special security token is required. Each dataset has a unique download security token.
   
  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) is able to download the dataset subscribers. 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 Download Security Token link.
   
  Creating a new Download Security Token: If you suspect that an unauthorized person has gained access to the download security token, you can use the Create New Download Security Token link to invalidate the previously used token and to create a new one.

• Data Encoding: The encoding used to store the profile values of the dataset subscribers. This encoding is also inherited by all lists in the dataset, meaning that it also determines the encoding used to store the profile values of all list subscribers in all lists of the dataset. Select an encoding that matches the language that is going to be used when the profile fields are being filled out.
  
  Note: The encoding can no longer be changed once there is at least one dataset subscriber or one list in the dataset. It can only be changed while the dataset is still empty.

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.