Recipient list

To send letters using WorkZone Mass Dispatch, you must create a recipient list. Each contact in the list will receive the letter.

The recipient list is a Microsoft Excel workbook with a mandatory set of two sheets describing the recipients: a schema sheet and a data sheet.

  • Contacts.Schema—required name of the schema sheet. This sheet contains system information on the aliases specified in the data sheet or taken from the WorkZone database. The A1 cell must refer to the name of the data sheet.
  • Contacts—the data sheet that you can name as you like. In the example below, it is named Recipients. The information from this sheet populates the letter template after you start the mass dispatch.
Note: In this release, only schemas for contacts and cases (files) are supported. Schemas for documents (records) and custom fields are not supported.

Recipient list in Excel

If you want to save dispatched letters on individual cases per recipient, you can add another set of schema and data sheet to the Excel workbook:

  • Files.Schema—required name of the schema sheet. This declares the relation of cases and recipients for the mass dispatch, and contains system information on the aliases specified in the data sheet or taken from the WorkZone database. The A1 cell must refer to the name of the data sheet.
  • Cases—you can name the data sheet as you like. This sheet contains the cases on which the dispatched letters will be saved.

The recipient cases can either be existing cases that you specify in the recipient list or new cases that are created based on a case template and information that you specify in the Start mass dispatch dialog box. See Start a mass dispatch ( steps 10-11).

Contacts.Schema sheet

All strings on the Contacts.Schema tab are case-sensitive, except Type.

Example: This example shows the Contacts.Schema tab of a recipient list that contains basic personal information:

The A1 cell refers to the name of the Contacts sheet. WorkZone Mass Dispatch requires a fixed structure of the recipient list to be able to process it, so you must define fields in this sheet as described in the table below.

Field name  

Alias

The field name used on the Contacts tab and in letter templates.

ServerPath

The path to the field values in WorkZone Content Server. If this field is empty, the information will be pulled not from the WorkZone Content Server but from the Contacts sheet.

Tip: You can use WorkZone QueryBuilder to view available fields and their paths.

Type

This field is not case-sensitive. Enter one of these types:

  • bool
  • uint
  • byte
  • long
  • sbyte
  • ulong
  • char
  • short
  • decimal
  • ushort
  • double
  • string
  • float
  • DateTime
  • int
  

Constraint

Enter Required if the field values cannot be empty.

Enter ServerKey in the field that will be used as key.
Note: The DateTime field type is used for defining both date and time. In the letter template, change formatting in the merge field of the DateTime type to get a desired format of the date or time. See more in Tips for formatting date, currency, and number.

Contacts sheet

This Contacts sheet contains the WorkZone contacts that will receive the letters using WorkZone Mass Dispatch and the information regarding these contacts. In this sheet, columns represent the fields that are defined on the Contacts.Schema sheet, and rows represent values.

Note: The contacts that you add to the recipient list must exist as WorkZone contacts for the mass dispatch process to send to these contacts. The validation will detect if the contacts exist. If a contact does not exist, the validation will add an error in the validation report. You can then create the missing contacts in WorkZone or you can choose to continue the mass dispatch process without sending to these contacts.
Example: Contacts sheet. In this example it is named Recipients.

Note: If a cell is empty and the server path is defined for the alias, the value will be taken from WorkZone Content Server. In the example above, the values for the AddressMain, AddressSuppl, and ZIPcode aliases will be populated from WorkZone Content Server.

Files.Schema sheet

The Files.Schema sheet is used to define the relation between cases and mass dispatch recipients.

The A1 cell refers to the name of the data sheet (in our example, Cases sheet). WorkZone Mass Dispatch requires a fixed structure of the fields to be able to process them, so you must define fields in this sheet as described in the table below.

Field name  

Alias

The field name used on the Cases sheet.

ServerPath

The path to the field values in WorkZone Content Server.

Tip: You can use WorkZone QueryBuilder to view available fields and their paths.

Type

This field is not case-sensitive. Enter one of these types:

  • bool
  • uint
  • byte
  • long
  • sbyte
  • ulong
  • char
  • short
  • decimal
  • ushort
  • double
  • string
  • float
  • DateTime
  • int
  • json

Constraint

Enter ServerKey in the field that will be used as a Contact key.

Enter ForeignKey in the field that points out the existing cases. In the example above, the cases with the numbers filled in the CaseNo. field on the Cases sheet will be used to store the documents that are sent.

Fields with no constraints are used to create the new cases.

Cases sheet

The Cases sheet is a data sheet that contains the information that is required to find or create cases where the sent letters will be saved. The Cases sheet can only contain recipients that are also on the Contacts sheet.

In the Cases sheet, columns represent the fields that are defined on the File.Schema sheet, and rows represent values. The dispatched letters will be saved on the existing cases that are specified for the recipients. If a case number is not specified, a letter will be saved on a new case or on the dispatch case depending on the information that you specify in the Start mass dispatch dialog box. See Start a mass dispatch (step 10).

Note: If a cell is empty and the server path is defined for the alias, the value will be taken from the template case specified in the Recipient cases tab of the Start mass dispatch dialog box.
If a recipient is specified on the Contacts sheet but is not on the Cases sheet, a new case for such recipient will be created if the Create recipient cases check box is selected in the Start mass dispatch dialog box. See Start a mass dispatch (step 10).

Validation

To ensure a successful mass dispatch, the following requirements to the recipient list must be met:

  • All fields are strictly aligned between the schema and data sheets. For example, all fields in the Contacts.Schema sheet must be present in the Contacts sheet, and all fields in Contacts sheet must be defined in the Contacts.Schema sheet.
  • Alias and type must be filled in for each field.
  • Each field has a unique alias and a unique server path.
  • Server paths only contain letters, numbers, underscores, and slashes.
  • Only one field is defined as ServerKey. Mind that the key values must be unique in WorkZone.
  • If there is a defined ServerKey in the Cases data sheet, then it should correspond to the ServerKey in the Contacts data sheet.