Subscriber Importers
- To access the subscriber importers of a dataset, select the desired dataset node in the Subscriber Datasets subtree. Then select Edit -> Subscriber Import -> View Subscriber Importers from the menu (or go via the right-click menu of the dataset node in the explorer tree).
-
To access the subscriber importers for a list, open the node of the parent dataset of the desired list in the
Subscriber Datasets
subtree, to show its subnodes.
- For a standard dataset (in subscriber area mode), proceed to open the Lists subnode, to show the subtree with all the lists in the dataset. Then select the desired list node in this subtree.
- For a "single list mode" dataset, there is no such "Lists" subnode. Simply select the node for the single list from the subnodes of the dataset node.
- To create a new subscriber importer, select the desired dataset in the Subscriber Datasets subtree and select Edit -> Subscriber Import -> Create New Subscriber Importer from the menu (or go via the right-click menu of the dataset node in the explorer tree).
- To create a new subscriber importer, select the desired list in the "Lists" subtree of its parent dataset and select Edit -> Subscriber Import -> Create New Subscriber Importer from the menu (or go via the right-click menu of the list node in the explorer tree).
Lists all subscriber importers that are defined for the selected subscriber dataset or 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 LISTSERV 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 LISTSERV 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 LISTSERV 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 id="copyrightLine" style="margin: 0; position:fixed; bottom:0; width:100%;" class="small helpCopyrightLine"> © 2002-2017 L-Soft Sweden AB. All rights reserved. </div> </body> </html>
Tip: LISTSERV 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 LISTSERV 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 LISTSERV 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 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.