Table of Contents Previous Next Index

Section 9 Adding and Maintaining Dataset Members and List Subscribers

Section 9 Adding and Maintaining Dataset Members and List Subscribers
Dataset members and list subscribers can be added to a dataset and to lists by the data administrator or designated team members. Alternatively, they can add themselves if the dataset (membership area) or any lists in the dataset are visible to the public on the Web. Anyone joining a membership area using the web form has the option of subscribing to any available lists there. Subscribing directly to a list using the list’s web form will automatically add the subscriber to the list’s dataset. More information on self-subscribing to membership areas and lists is covered in Section 10 Allowing Members to Join a Dataset.
Once members belong to a dataset, their data can be managed within the dataset by the data administrator. Management can take place at the dataset level and at the list level. The data administrator can search for members, delete members, change a member’s data, add a single member, download all members, and modify multiple members by uploading a file. Members of a dataset are managed by selecting the dataset. Subscribers to a list are managed by selecting the list.
9.1 Managing Dataset Members and List Subscribers
Dataset members can be reviewed, changed, or deleted by clicking on the dataset in the left pane of the Recipient Dataset Details screen and selecting Dataset > Browse / Edit Confirmed Members from the Toolbar. The Manage Members of Recipient Dataset screen opens.
Figure 9-1 Managing Members of a Dataset
This screen displays a list of all the confirmed members of a dataset. Confirmed members are those members who have been added to the dataset by the data administrator or have added themselves from the web form and then confirmed their membership using a special email message sent to them by LISTSERV Maestro. Unconfirmed members are not displayed here. Unconfirmed members are those who have joined the membership area or subscribed to a list themselves, but have not yet replied to the confirmation email message sent to them by the system.
Subscribers can be reviewed, changed, or deleted by clicking on the list in the left pane of the Recipient Dataset Details screen and selecting Hosted List > Browse / Edit Confirmed Subscribers from the Toolbar. The Manage Subscribers of Hosted List screen opens.
Figure 9-2 Managing List Subscribers
If subscribers of a list are deleted from the list, they are not automatically deleted from the dataset. However, if members are deleted from a dataset, they will be deleted from all lists in that dataset. The functions and rules for managing dataset members and list subscribers are almost identical and will both be covered in this section. Pertinent differences will be pointed out in the text and screen shots.
In addition, when browsing/editing subscribers of a Hosted Recipient List (HRL)/Hosted LISTSERV List or members of a dataset, there is now a new column that lets you know when that subscriber/member subscribed to the list or joined the dataset. This new column is called Membership Date (Figure 9-1) or Subscription Date (Figure 9-2).
The members of a dataset or list are displayed 15 at a time per page. A navigation system for paging through members appears when more than 15 members are in a dataset or list. Each page number is a clickable link and contains the next 15 members or subscribers. A maximum of ten page links will appear on the screen at a time. Datasets and lists with more than ten pages will use << to denote the set of 10 pages before the open page, and >> to denote the set of 10 pages after of the current page links.
Members and subscribers are sorted alphabetically by email address. Members have their entire dataset profile displayed on the screen. Subscribers have their dataset profile along with any list specific fields displayed on the screen. The table header lists the profile field names in the dataset and list. Each column in the table represents one profile field on the web form. Each field is filled out with the corresponding value for that profile field and member. Mandatory fields have all values filled in for members, while optional fields can be blank. Boolean fields will have a “T” for true and an “F” for false. Datasets with selection menus that allow for multiple selections will display all selected values separated by commas. LISTSERV lists with topics have all the selected topics displayed.
9.1.1 Editing Member and Subscriber Profiles
Each email address is a link that opens the profile page for that member. Click on the email address of the member to be edited. Enter the new data in the profile fields, and then click [OK] to save the new data and return to the previous screen. Click [Cancel] to return to the previous screen without saving the new data. Click [Delete] to delete the member from the dataset.
Member profiles will contain only those fields that belong to the dataset.
Figure 9-3 Edit Dataset Member
Subscriber profiles will contain the member profile in the top part of the screen with the values grayed out and the list specific fields and the subscription options below. It is possible to edit the member profile from the list profile screen by clicking the Edit link located on the upper right. The Subscription Options section lets the data administrator have access to the subscription options, just as the subscriber would.
Figure 9-4 Edit List Subscriber
9.1.2 Filtering Members and Subscribers
Locating members within a large dataset can be easily accomplished by using the filtering system available on the Manage Members of a Recipient Dataset screen. Locating subscribers within a large list can be accomplished using the filtering system on the Manage Members of Host List screen. Filtering works the same way for members and subscribers.
A funnel icon located in the upper left of the recipient data table precedes a row of blank edit boxes at the top of each column. Use the boxes to enter filtering conditions to narrow the search for specific members or subscribers. After adding the filtering conditions in the text boxes, click the funnel icon to filter the members. A new set of members will be displayed on the screen. This set can be filtered again by adding additional conditions in the text boxes and clicking the funnel again. After filtering, the full set of matching members can be downloaded by clicking the download icon located in the blue header row of the table. The file that is downloaded is in zipped format.
There are many ways to enter conditions to filter members of a dataset or list subscribers. The type of profile field determines what types of filtering can take place. Wildcards and operators can assist with filtering.
Text Field Filtering – Fields based on text can be filtered using the following operators and wildcards:
The text “GINA” was used as an example in this table. Any text string can be filtered using these rules.
Number Field Filtering – Fields that are based on numbers can be filtered using the following operators and wildcards:
The number “23” was used as an example in this table. Any number can be filtered using these rules.
Boolean Fields – Fields that are based on Boolean logic display a drop-down menu with the choice of three filters:
Single Select Fields – Fields that are based on single selection menus can be filtered using the same rules for filtering text.
Multiple Select Field Filtering – Fields based on multiple selection menus cannot be filtered.
Topics Field Filtering – LISTSERV lists that contain topics cannot be filtered using the special topics field that is displayed when browsing the list members.
9.2 Adding a Single Member or Subscriber
The data administrator can add members to a dataset or subscribers to a list one at a time. It is important to have the necessary data for each addition.
To add a single member to a dataset:
1.
2.
Click Dataset > Add Single Member.
3.
4.
5.
Click [OK].
The member will be added to the dataset. Members added to a dataset are not automatically added to any lists in that dataset set. To add or change information at the dataset level, click Dataset > Browse / Edit Confirmed Members.
To add a single subscriber to a list:
1.
2.
Click Hosted List > Add Single Subscriber.
3.
4.
Click [OK].
5.
If the address is not already a member of the dataset, fill in all the mandatory fields for the dataset and the mandatory fields for the list. If the email address already is a member of the dataset, the dataset fields will already be filled in and their values will appear in gray. Fill in the list specific fields.
6.
7.
Click [OK].
New list subscribers that are not dataset members are automatically added to the dataset when they are subscribed to any list in that dataset. To add or change information on the list level, click Hosted List > Browse / Edit Confirmed Subscribers.
9.3 Modifying Members or Subscribers by Upload or Import
Any existing dataset or list can have its current membership modified by the data administrator uploading a file in to the system or importing dataset members from an existing database.
9.3.1 The Import Members/Import Subscribers Wizard
LISTSERV Maestro uses the Import wizard to assist the data administrator with modifying the data in an existing dataset or list. The wizard is comprised of seven pages that go through the process of modifying the data of an existing dataset or list step by step. Depending on the choices made on some wizard pages, other pages may become disabled or appear in different versions. If a wizard page is disabled, it is not necessary with the current selections and can safely be ignored.
To access the Upload Members wizard from the Recipient Wizard for a dataset, click on the Dataset menu, select Member Import, and then select Import Members Now.
To access the Upload Subscribers wizard from the Recipient Wizard for a list, click on the Hosted List menu, select Subscriber Import, and then select Import Subscribers Now.
9.3.1.1 Type
The first screen of the Upload wizard is Type. The existing data can be modified five different ways. Available types for datasets are:
Add to Dataset – Adds new members to the dataset. All existing members are left unchanged. If records for existing members or subscribers are present in the file/database, then these will be ignored.
Update in Dataset – Updates the existing members with the values fond in the file. Does not add any new members to the dataset.
Synchronize with Dataset – This is a combination of the "add" and "update" functions. Adds any new members found in the file/database and updates values for existing members found in the file/database.
Full Synchronize with Dataset – The data will become the exact data in the dataset. Adds any new members and updates values for existing members. Any existing members not included in the file/database will be deleted from the dataset and from any lists they are subscribed to.
Remove from dataset – Removes members listed in the file/database from the dataset and from any lists they are subscribed to. Only the email addresses of those members to be deleted are required to be in the file/database; all other columns are ignored.
Figure 9-5 The Import Members Wizard –Type Screen for Dataset
When modifying subscribers for a list, the values for the dataset are included. The available modifications for lists are:
Add to List – Adds new subscribers to the list. All existing subscribers are left unchanged.
Update in List – Updates the existing subscribers with the values found in the file. Does not add any new subscribers to the list.
Synchronize with List – This is a combination of the "add" and "update" functions. Adds any new subscribers found in the file and updates values for existing subscribers found in the file.
Full Synchronize with List – The list data in the file will become the exact data in the list. Adds any new subscribers found in the file and updates values for existing subscribers found in the file. Any existing subscribers not included in the file will be deleted from the lists. Subscribers removed from the list will not be removed from the dataset.
Remove from List – Removes subscribers listed in the file from the list. Only the email addresses of those members to be deleted are required to be in the uploaded file; all other columns in the file are ignored.
Once you’ve selected the modification type, click [Next ->] to continue.
9.3.1.2 Type Details
The Type Details screen defines the details for the selected modification type. This screen may not be available for all modification types. For modifying datasets the following details are available:
Table 9-1 Modifying Datasets Details
Overwrite Manual Changes: If members have changed their settings since the last upload modification, will their changes be overwritten?
Overwrite Manual Changes: If members have changed their settings since the last upload modification, will their changes be overwritten?
Overwrite Manual Changes: If members have changed their settings since the last upload modification, will their changes be overwritten?
 
 
 
For modifying lists the following details are available:
(select the desired option button for each of the two sets of alternatives)
Overwrite Manual Changes: If subscribers have changed their settings since the last upload modification, will their changes be overwritten?
(select the desired option button for each of the three sets of alternatives)
Overwrite Manual Changes: If subscribers have changed their settings since the last upload modification, will their changes be overwritten?
(select the desired option button for each of the three sets of alternatives)
Overwrite Manual Changes: If subscribers have changed their settings since the last upload modification, will their changes be overwritten?
Once you’ve selected the type details, click [Next ->] to continue.
9.3.1.3 Source
The Source screen is used to determine where the uploaded text file originates or what database to import dataset members from.
To upload a text file, select the Import Dataset Members from a text file option. Browse for the file on a local drive, and then click [Upload]. If a file has already been uploaded to the system, the Upload a different file link appears.
Note: For a text file, the file must be encoded with the same character set (charset) that has been defined for the dataset being modified. For more information about character sets, see Appendix C: Email and International Character Sets.
To import dataset members from a database, select the Import dataset members from a database option. Click on the Database Plugin drop-down menu and select the plugin to use. Enter a SQL statement in the box provided.
Figure 9-6 The Import Members Wizard - Source Screen
Once you’ve finished defining your import source, click [Next ->] to continue.
9.3.1.4 Parse Details
The Parse Details screen lets you determine whether or not the data was uploaded/imported and parsed correctly.
Figure 9-7 The Import Members Wizard - Parse Details
When a text file is uploaded, LISTSERV Maestro will try to determine how the columns of data are separated, and how each column or field of data is labeled (header). In order to modify a dataset or list, LISTSERV Maestro must correctly interpret which column contains the email address of the recipient. Other fields may be included and will appear in the Preview table located on the lower half of the screen.
Click the [Next ->] button to continue if the parsing is accurate and each column of data is separated correctly and labeled with a header row.
If LISTSERV Maestro has not interpreted the data correctly, or an unconventional delimiter and/or quote character has been used, click on the Specify separator and quote manually link to configure the parsing manually. For example, if the USERNAME field contained Tom “the cool cat” Jones as an entry, and double quotes happened to be the quote character for the file, then the details would have to be specified manually. The same would be true if a field named LOCATION contained the entry Atlanta, GA where the comma was the separator character.
LISTSERV Maestro has four selections for choosing separator characters:
Tab (\t)
Comma (,)
Other – if this is chosen, type the character into the adjacent box.
Columns can be defined as not enclosed by a quote character or select the quote character from three choices:
Other – if this is chosen, type the character into the adjacent box.
After separator and quote characters have been entered, and any encoding change made, click [Refresh Preview] to have LISTSERV Maestro attempt to parse the file again with the new settings. The new columns will then be displayed. If the columns are now separated correctly, proceed. If the columns are not correct, repeat the process and click [Refresh Preview] to see the new changes. Click the [Next ->] button to continue if the parsing is accurate and each column of data is separated correctly and labeled with a header row.
Headers are specially defined rows used to label the columns of data so that the system and the user can correctly identify the columns. An uploaded text file may contain headers or not. If the file does not contain headers, select the No, the file does not contain a header row option and the system will automatically add a header row. Each column of data in the header row will have a generic name using the pattern COL1, COL2, COL3, and so on. If the uploaded file does have a header row, select the Yes, the first row in the file containers headers option and the headers within the file will be used. Click the [Next ->] button to continue if the parsing is accurate and each column of data is separated correctly and labeled with a header row.
9.3.1.5 Map Fields
The Map Fields screen lets you map the columns of your uploaded file to the fields in the dataset. For example, if the header names for the columns of data do not match the names of the fields in the dataset or list, then they can be “mapped” to the correct fields. Boolean fields in this context are considered mandatory. Optional fields can be mapped, but it is not necessary for a successful upload. Any “extra” fields that may be contained in the file (fields that are not listed in the dataset or list) will be ignored by the system. This way, data to be used to modify datasets and lists does not need to match the format of the dataset or list exactly, but can contain other fields and different header names.
If the uploaded file contains headers, LISTSERV Maestro will attempt to map the fields to the column names. Fields that are mapped successfully appear with a green checkmark icon next to them. Fields that cannot be mapped automatically appear with a yellow arrows icon; these may be mapped to a column from the file, or a default value may be assigned in a later step. Fields that are mapped to more than one column have a red null icon; these must be fixed before proceeding.
To map a column from a file to a list or dataset field, use the drop-down menu under the header to locate the correct field and select it. If the file contains columns that do not map to any field, select <ignore> for these columns.
Figure 9-8 The Import Members Wizard - Map Fields Screen
Once all the fields are correctly mapped, click the [Next ->] button.
9.3.1.6 Mapping Details
The Mapping Details screen is used for further defining fields so LISTSERV Maestro can correctly interpret the uploaded values. This screen is also used to provide default values, when necessary.
The following fields may be available for definition:
Default Values – If values are missing in the uploaded data, then define the default values to be used for each field.
Boolean Value Mapping – If Boolean fields are among those mapped on the Map Fields screen, then the Boolean value for these fields needs to be defined.
Multiple Value Parsing – If Multiple Selection fields are among those mapped on the Map Fields screen, then the data in the uploaded file needs to be defined as to how it will be parsed to correctly extract multiple values from it.
The Mapping Details screen differs depending on the type(s) of fields mapped on the Map Fields screen. If only one of the above fields need further definition, then the Mapping Details screen displays only that value. If there is more than one field that needs defined, then the screen will display a tab for each type of field. For example, if both Boolean fields and multiple selection fields need further definition, then the Mapping Details screen will appear with two tabs, one representing each type of field, allowing you to define each value. When each tab is completed, a green checkmark will appear on that tab. The [Next->] button will not be available until all required mapping details are completed.
Default Values
Default values are applied when field values from the uploaded data are missing. This tab displays a list of all the fields with the currently defined defaults. Click on a field to edit its default value. The Define Default Value screen opens.
Default values are used in two cases:
If the field is mapped to a file column, then the provided default will only be used for those uploaded rows where the value of the mapped column is empty. In this case, the field will not be assigned the empty value from the column, but the default defined here.
For fields that are optional (including the hidden and read-only types, which are variations of the optional type), then it is not necessary to define a default. If, for such a field, no default is defined, then the empty default is assumed. Therefore, for fields of this type, you can define a default (to get the defaulting behavior as described above), but it is not mandatory.
For fields that are mandatory (including the visible type, which is a variation of the mandatory type), then, in some situations, a default is required, and in some, it is not:
Mandatory fields that are not mapped to a file column: For fields of this type, it is required to define a default; otherwise, the field would be empty for every uploaded row, and since a mandatory field is not allowed to be empty, then that would mean every uploaded row would be rejected as invalid.
Mandatory fields that are mapped to a file column: For fields of this type it is not required to define a default; however, in many cases it may be advisable. If no default is defined, then any uploaded row where the value of the mapped file column is empty will be rejected as invalid (because the mandatory field may not be assigned an empty value). Therefore, if you want to avoid rows being rejected, define a default for use whenever the mapped column is empty.
Boolean Fields
When Boolean fields are present in a dataset or list, LISTSERV Maestro needs to know what value equates to “true” and what value equates to “false” for each field. These values do not have to be the same for all fields in the dataset or list. Each Boolean field can have its own true and false values. For example, one field might have the digit “1” represent true and the digit “0” represent false, and another field might have the letter “Y” represent true and the letter “N” represent false. Once the true and false values have been defined, they can be used to tell the system how to use the values to register a true or false in the dataset.
A “true” value can be registered by selecting one of the options:
A “false” value can be registered by selecting one of the options:
Three valid combinations of these options are possible:
A value representing “true” is specified and a value representing “false” is specified. This combination will assign the corresponding Boolean values to all rows that have the specific true and false values. Any rows that do not have the specified true and false values will be skipped as invalid and can be downloaded from the Results Statistics screen after the upload is completed.
A value representing “true” is specified and the “false” is every value that is not equal to the true value. This combination will assign the true value to those rows that have the specified value, and assign false to all other rows. No rows will be skipped due to an invalid value in that field.
A value representing “false” is specified and “true” is every value that is not equal to the false value. This combination will assign the false value to all those rows that have the specified value, and true to all other rows. No rows will be skipped due to an invalid value in that field.
In the second step of Boolean field mapping, select which field to apply the values to by clicking the name of the field. If all of the Boolean fields use the same definition, click the apply to all fields link.
Multiple Select Values
If there are multiple selection fields, LISTSERV Maestro needs to know how multiple entries are separated. If the separator character is used in one or more of the entries, those entries need to be surrounded by a quote character that LISTSERV Maestro needs to be aware of as well (see Section 9.3.1.4 Parse Details).
Click [Next ->] to continue if there are no other tabs to set mapping details for, or if each tab has a green checkmark.
9.3.1.7 Launch Import
The Launch Import screen summarizes the options for the import. Use the [<- Back] button to return to the previous screen, or any of the links in the navigation bar to return to a previous screen to change selections. Click the [Launch] button to upload the file/start the import. An Operation in Progress bar will display until the import is completed. Results of the modification will be displayed. Download any unprocessed rows by using the download links.
Figure 9-9 The Import Members Wizard - Launch Import
Click [OK] to accept all modifications and return to the Recipient Dataset Details screen.
9.3.2 Defining Recipient Importers
For those occasions where you’d like to manage your dataset members or list subscribers on a regular basis, LISTSERV Maestro 4.0 now contains a feature that allows you to define these member or subscriber imports once. This lets you store these settings and run the import whenever necessary.
To define a Recipient Import for a dataset, go to the Recipient Warehouse, click on the dataset you’d like to work with, click on the Dataset menu, select Member Importer, and then select New Member Importer. The Edit Member Importer wizard open. This wizard mirrors the Import Members wizard. Define each page as you would the Import Members wizard (see Section 9.3.1 The Import Members/Import Subscribers Wizard for details).
Figure 9-10 The Edit Member Importer Wizard
Once you’re finished defining the Member Importer, it will be listed on the Member Importers screen. To access this screen, click on the Dataset menu, click on Member Importer, and then select Member Importers.
Figure 9-11 The Member Importers Screen
To define a Recipient Import for a list, go to the Recipient Warehouse, and then click on the dataset that contains the list you’d like to work with. From the Recipient Dataset Details screen, click on the list name, click on the Hosted List menu, select Subscriber Importer, and then select New Subscriber Importer. The Edit Subscriber Importer wizard open. This wizard mirrors the Import Subscribers wizard. Define each page as you would the Import Subscribers wizard (see Section 9.3.1 The Import Members/Import Subscribers Wizard for details).
Figure 9-12 The Edit Subscriber Importer Wizard
Once you’re finished defining the Subscriber Importer, it will be listed on the Subscriber Importers screen. To access this screen, click on the Hosted List menu, click on Subscriber Importer, and then select Subscriber Importers.
Figure 9-13 The Subscribers Importers Screen
Before the Recipient Importer can be used, it needs to be enabled. To enable, click the Enable link. If you no longer want the importer available for use, but you don’t want to permanently delete it, then click the Disable link. The Recipient Importer will remain on the Member Importer/Subscriber Importer screen.
To edit a Recipient Importer, click the Edit link associated with that importer. The Edit Member Importer/Edit Subscriber Importer wizard opens.
To delete a Recipient Importer, click the Delete link associated with that importer.
9.3.2.1 Launching a Recipient Importer
To run a Recipient Importer, click the Launch link associated with that importer. The Import Member/Import Subscriber wizard runs automatically according to the settings you defined for the Recipient Importer.
9.3.2.2 Launching a Recipient Importer Externally
In order to trigger the launch externally, the external process or application has to access the server where the LISTSERV Maestro User Interface (LUI) is running via HTTP (or HTTPS, depending on your setup). In addition, a security token must be obtained.
Note about Security Tokens: Since triggering a launch externally is a highly privileged operation, LISTSERV Maestro requires that the external process or application delivers a security token for authorization. This security token is assigned internally by LISTSERV Maestro.
To obtain the security token, simply click the Show Launch Security Token link to open a popup box. Copy the security token from this box and make sure that the external process or application accesses the URL described above, replacing [SECURITY_TOKEN] with the value pasted value from the popup box.
Note: To create a new security token, click the Create New Launch Security Token link in the popup box. Once a new security token is created, the old token is no longer valid and cannot be used to trigger a job externally.
Once you know the security token, the following URL must be accessed. A trigger URL always has the following form:
http[s]://[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://".
and where SECURITY_TOKEN is replaced with the security token for the action that the URL will 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 verifies the given security token and, if it is valid, triggers the corresponding action. The result of the action will be returned in the form of a HTTP response.
If everything went well, a response with the status code "200 - OK" will be returned. In this case, the response body will contain the result of the action. Most actions will simply 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 will be returned; for example, "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 will be returned in the form of a HTTP response, just like for the "simple URL access" (see above for details).
Important: If you type the value manually, then make sure to maintain the exact spelling because security tokens are case sensitive.
9.3.2.3 Viewing a Recipient Importer’s History
To view the usage history for the Recipient Importer, click on the View History link. The Importer Launch History screen opens.
To download error records, click on the Download link next to the error description you’d like to view. The data will be downloaded in the form of a ZIP-file with the data in the form of a text file with comma separated values (a CSV-file). This CSV-data can then be imported into 3rd party tools (for example Excel) for further analysis.
To delete entries from the Launch History screen, click on the Scissor icon above the entries you’d like to delete. The entries below this marker will be removed.
Figure 9-14 Viewing the Member Importer’s History
9.4 Downloading Dataset Members and List Subscribers Externally
LISTSERV Maestro 4.0 now gives you the ability to download dataset members and/or list subscribers externally. For this to work, the external process or application has to access the server where the LISTSERV Maestro User Interface (LUI) is running via HTTP (or HTTPS, depending on your setup). In addition, a security token must be obtained.
Note about Security Tokens: Since downloading dataset members and list subscribers is a highly privileged operation, LISTSERV Maestro requires that the external process or application delivers a security token for authorization. This security token is assigned internally by LISTSERV Maestro.
To obtain the security token for a dataset, open the Recipient Dataset Details screen, click on the Dataset menu, and then select Edit Dataset Settings. The Recipient Dataset Definition wizard opens. On the General screen, the External Download field will contain a Show Download Security Token link. Click this link to open a pop-up box that contains the security token. Copy the security token and make sure that the external process or application accesses the URL described above, replacing [SECURITY_TOKEN] with the value from the popup box.
To obtain the security token for a list, open the Recipient Dataset Details screen, select the list, click on the Hosted List menu, and then select Edit List Details. The Hosted List Definition wizard opens. On the General screen, the External Download field will contain a Show Download Security Token link. Click this link to open a pop-up box that contains the security token. Copy the security token and make sure that the external process or application accesses the URL described above, replacing [SECURITY_TOKEN] with the value from the popup box.
Figure 9-15 Downloading Subscribers Externally
Note: To create a new security token, click the Create New Download Security Token link in the popup box. Once a new security token is created, the old token is no longer valid and cannot be used to trigger a job externally.
Once you know the security token, the following URL must be accessed. A trigger URL always has the following form:
http[s]://[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://".
and where SECURITY_TOKEN is replaced with the security token for the action that the URL will 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 verifies the given security token and, if it is valid, triggers the corresponding action. The result of the action will be returned in the form of a HTTP response.
If everything went well, a response with the status code "200 - OK" will be returned. In this case, the response body will contain the result of the action. Most actions will simply 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 will be returned; for example, "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 will be returned in the form of a HTTP response, just like for the "simple URL access" (see above for details).
Important: If you type the value manually, then make sure to maintain the exact spelling because security tokens are case sensitive.
9.5 Team Collaboration
Team Collaboration is now available for datasets, allowing the data administrator to designate certain rights to other team members. These rights include the ability to add, remove, or modify subscribers, plus the ability to browse through subscriber data for purposes of downloading data for reports. Also available is the right to customize the subscriber access web pages.
To set up team collaboration for a dataset, click Dataset > Team Collaboration. The Team Collaboration screen opens. All of the team members in the same group as your own account are listed in the table on this screen.
Note: Only data administrators have the right to grant team collaboration permissions to other team members; therefore, if you cannot access the Team Collaboration screen, then you are not a data administrator.
To grant permissions to other team members, simply check the box that corresponds to that particular permission. To revoke permissions, simply uncheck the box for that particular permission. To grant or revoke all of the permissions for a team member, click on the team member’s name. To grant or revoke all of the permissions for all team members, click the Team Member link. To grant or revoke one specific permission to all team members, click the link for that permission. All of the boxes will either be checked or unchecked simultaneously.
To copy existing permissions from another dataset, select the dataset from the drop-down menu. The permissions will be automatically copied.
Figure 9-16 Team Collaboration Screen
The following permissions can be granted to a team member:
Customize Subscriber Pages – If this box is checked, then the team member has permission to customize the subscriber pages associated with the dataset and its hosted lists.
Add/Remove Subscribers – If this box is checked, then the team member has permission to add new members to the dataset and new subscribers to the hosted lists in the dataset. They can also remove members or subscribers from the dataset or its lists.
If this permission is granted, then the Modify Subscribers and Browse Subscribers permissions are also automatically granted.
Modify Subscribers – If this box is checked, then the team member has permission to modify existing members of the dataset or modify existing subscribers of the hosted lists in the dataset.
If this permission is granted, then the Browse Subscribers permission is granted.
If this permission is revoked, and the Add/Remove Subscribers permission was already granted, then both permissions are revoked.
Browse Subscribers – If this box is checked, then the team member has permission to browse and view the list of current members of the dataset or subscribers of the hosted lists in the dataset.
If this permission is revoked, and the Add/Remove Subscribers and/or the Modify Subscribers permissions were already granted, then all three permissions will be revoked.
Note: Some team members in the list may be displayed as “read only”, with all permissions granted and the Data-Admin label. This means that this particular team member is a data administrator. A data administrator always possesses all possible permissions, which can not be revoked from them on this screen. A user is considered a data administrator if the Administer Hosted Recipient Datasets option is granted in the Administration HUB (set by the administrator).
9.6 Member and Subscriber Statistics
The Membership Statistics or Subscriber Statistics tabs on the Recipient Dataset Details screen show dataset and list subscriptions and signoffs over time using line charts.
Click on the Show Settings link to change the time period or interval for the line chart.
Figure 9-17 Change Settings for the Membership/Subscriber Statistics Tab
To view information for a specific date, move the cursor back and forth until you find the date, then click on that date. A box is displayed with the specific information for that date. This box may also contain links that, if clicked, will display another chart with the statistics for that day.
Figure 9-18 Sample Subscriber Statistics Report
9.7 Viewing Demographic Reports for a Dataset or List
You can now view a Demographic Breakdown report on the members of the selected dataset or on the subscribers of the selected list.
To view the Demographic Breakdown report for a dataset, go to the Recipient Dataset Details screen for that dataset, click the Membership Statistics tab, and then click on the Demographic Breakdown sub-tab.
To view the Demographic Breakdown report for a list, go to the Recipient Dataset Details screen for the dataset that the list belongs to, click on the list name, click on the Subscriber Statistics tab, and then click on the Demographic Breakdown sub-tab.
Figure 9-19 Demographic Breakdown Report for a Dataset
By default, the report shows each individual profile with all available profile fields selected as report header columns. Up to 100 profiles are shown in the list.
The Demographic Breakdown report is most useful if profile fields with only a few different values are shown (fields that contain larger geographic regions or product groups are good candidates). Each profile values group is shown with its numeric count to the left and a bar whose length corresponds to this count.
To rearrange the order of the columns, use the left and right arrows associated with each column. To remove a column, simply click the [x] box. When you’re finished rearranging the columns, click [Apply].
To add a previously removed column to the report, click the More Columns link. This opens a drop-down menu with the previously removed columns; select the desired column to once again add it to the report header columns.
Note: You can add, remove, or reorder the report columns several times all at once. When you are satisfied with your report header columns, click the [Apply] button.
Important: The email and tracking permissions column types are never part of the Demographic Breakdown report. For more information, please see the online help.
Use the Sort Order link to modify the ordering of the report result bars.
Below the report, information about when the report was executed is displayed.
This message bar also contains the Download icon for the report at the very right. Click on the icon to open a popup menu that lets you chose between two different download formats:
Download as PDF – The report will be downloaded in the form of a PDF file, for easy distribution or printing.
Download as Text File (CSV) – The report will be downloaded in the form of a ZIP-file that contains the current report in the form of a text file with comma separated values (a CSV-file), plus an additional readme.txt file with details about the report. This CSV-data can be imported into 3rd party tools (such as Excel) for further analysis.
9.7.1 Sending Messages to Specific Demographics
LISTSERV Maestro 4.0 has made it easier than ever to send a message to a specific demographic in your dataset or list. Each bar in the report describes one particular demographic of the subscriber base. This gives you the chance to use the Demographic Breakdown report as a visual means to define the recipients set for either a target group or a mail job
To send a message to a specific subscriber base and immediately create a new mail job, go through the report and place a check next to each subscriber group you’d like to include in the mailing. Once this is done, click the Create Mail Job link. This opens the Start New Job screen. Enter the email jobs information and click [OK]. You’ll be taken to the Workflow Diagram with the Define Recipients section completed for you. From here, finish creating your email job and authorize it for delivery. Only the selected subscribers will receive this message.
Figure 9-20 Creating a Mail Job or Target Group Based on Demographics
To reuse the subscriber base for several mail jobs, go through the report and place a check next to each subscriber group you’d like to include in future mailings. Once this is done, click the Create Target Group link. This opens the Target Group Definition wizard with settings that match the recipients selection defined by your selected checkboxes on the report. Use the Target Group Definition wizard to further refine the target group settings and to store the target group under a name of your choice for later use.