LISTSERV Maestro 11.1-3 Help Table Of Contents

Subscriber Importers

To access the subscriber importers list of a subscriber list or list group, open the subscriber list overview or the list group overview of the desired list or group. Then select Import Subscribers... from the menu (or go via the right-click menu of the selected list or group node in the left pane).

Two methods to import subscribers are available:

  • Import Subscribers Now: Use this option if you are not planning to repeat a similar import operation in the near future. With this method, LISTSERV Maestro does not store the settings you supply for the import but only performs the actual import. Click the [Import Subscribers Now] button to proceed using this method.

  • Create Reusable Importer: If you will be repeating this import operation in the future (either, for an uploaded file, because you will repeatedly be getting a new version of the file, or, for an import of data stored in an LDAP directory or an SQL database, this source of data may contain different data with similar structure in the future). When using this method, Maestro does not immediately perform the data import but instead stores your settings in the form of a Importer which can in the future easily be picked and launched, either automatically or manually. Click the [Create Reusable Importer] button to proceed with creating an importer.

The screen lists all reusable subscriber importers that already have been created for the selected list group or subscriber list.

Each importer is shown with its name, type, source, description, and status. For an importer with the status Complete, the whole importer definition has been supplied in the importer wizard. If the status is Incomplete, then the importer wizard was closed with "Save & Exit" before the definition was complete.

The following actions can be performed on an existing importer, by clicking the matching link:

  • Edit: Opens the importer wizard to edit the importer.

  • Enable (only available for a "complete" importer that is currently disabled): This enables the importer for launch. Only an enabled importer can be launched (either via the Launch link or via an external trigger, see below).

  • Disable (only available for a "complete" importer that is currently enabled): This disables the importer for launch (see Enable above for more details).

  • Delete: Deletes the importer.

  • Launch (only available for a "complete" importer that is currently enabled): This launches the importer. Depending on its definition, the importer may query for a file upload with the import data. Once the importer is started, it processes the import in the background. The progress of the import will be displayed under "Last Run" (see below).
    An importer may also be launched via an external trigger, which is also only possible if the importer is "complete" and enabled (see below).

  • Show Launch Security Token: The launch of an importer can be triggered either from inside of Maestro (via the Launch link), or it can be triggered externally, with an external trigger. The launch security token is required for such an external trigger. See below for details about an importer launch with an external trigger and how to use the security token.

  • View History: Opens the Importer Launch History screen that shows details about all previous launches of this importer (launch date/time, success state, rejected data, etc.).

The Last Run field displays the status of the last importing process of the importer: It shows if the last run is still ongoing (and at which percentage of completion) or if it has already completed. It also shows when the last run was, and it provides the View History link by which you can view the run-history of the reporter.

Importer Launch with an External Trigger

As described above, you can launch an importer either manually from inside of Maestro with the Launch link, or you can launch it with an external trigger. This section describes how to use an external trigger to launch the importer.

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 Maestro on its HTTP port (for example with a normal web browser) will be able to trigger the launch of the importer. 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 Launch Security Token link (this security token is not required for a manual launch via the Launch link).

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 Launch Security Token link to invalidate the previously used token and to create a new one.

If the importer was defined to read from a server file or from an external database, then the external launch trigger is of the Simple URL Access type and the response does not contain any download data. See below for more details about external triggers and what this means in detail.
Note: The following discussion of how to specify "additional data" is not applicable in this case!

If the importer was defined to expect an uploaded file with the import data, then the external launch trigger is of the URL Access with Additional Data type (also without any download data in the response), with the import data file as the "additional data". As described below, in such a case the external trigger must happen in form of a HTTP POST-request to the trigger URL, which contains the additional data. For this, the request must use the multipart/form-data encoding type and, to trigger an importer launch, must define the following three parts:

Part Name Part Value Additional Part Information
token The launch security token (see above) none
encoding The encoding that is to be used to interpret the uploaded text file none
data The uploaded text file "filename" attribute in the "Content-Disposition" header,
"content type" in the "Content-Type" header (normally "text/plain")

Since the multipart/form-data encoding type uses the MIME standard, these parts must be defined using the suitable headers for each part, and empty lines (CR LF) and multipart-boundaries to separate the parts.

The value for the "encoding" must be one of the encodings that is supported by Java (see here; both the "Basic Encoding Set" and the "Extended Encoding Set" from that page are supported, and you can specify a encoding by its name either from the "Canonical Name for java.nio API" or the "Canonical Name for java.io and java.lang API" column).

Examples:

The following example shows the HTTP POST-request data for an external launch trigger, if the importer expects "additional data" as described above:

Content-Type: multipart/form-data; boundary=AaBbCcXx --AaBbCcXx Content-Disposition: form-data; name="token" ... launch security token here ... --AaBbCcXx Content-Disposition: form-data; name="encoding" ... encoding to use for interpreting the text file here ... --AaBbCcXx Content-Disposition: form-data; name="data"; filename="members.txt" Content-Type: text/plain ... contents of members.txt import data file here ... --AaBbCcXx--

The following example shows the HTML code of a simple HTML page that displays a form like the following:

Security Token:
Encoding:
File:

into which the user can enter the security token, file encoding and the file to upload. Then when the user clicks the "OK" button, the form will submit a HTTP POST-request with "additional data" like the one described above to the external trigger URL (if "TRIGGER_URL_HERE" is replaced accordingly):

<html> <form method="POST" action="TRIGGER_URL_HERE" enctype="multipart/form-data"> Security Token: <input type="text" name="token"><br> Encoding: <input type="text" name="encoding"><br> File: <input type="file" name="data"><br> <input type="submit" value="OK"> </form> </div> </div> </div> <div id="copyrightLine" class="helpCopyrightLine"> &#169; 2002-2023 L-Soft Sweden AB. All rights reserved. </div> </body> </html>

Tip: Maestro already contains a convenience page that displays a form just like the one shown in the example above. This page can be accessed without the need of first logging in to Maestro. As long as you know the security token of an importer, and have a data file that is compatible with that importer, then you can use this page to upload the file and launch the importer without logging in. The URL for the page on this Maestro server is:

null/lui/JSP/externalAction.jsp

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 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 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 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 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 Maestro server. (If a non-standard HTTP port is used, also include the port, separated with a colon ":". If access to your 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 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 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.

© 2002-2023 L-Soft Sweden AB. All rights reserved.