Populations

Populations are the data source of members for a communication. Each communication must have a population defined.

Adding/Editing Populations

Population types

Populations can be sourced from one of the following population types:

Manual Email List: A list of email addresses and names.
Manual CSV List: A comma separated list of attributes of your choice with the fields defined in the first row.
Manual ID List: A list of HawkIds or UniversityIds. Additional attributes will be looked up in IDW.
Database Query: A SQL query to one of the defined databases. Currently, DWPROD and Dispatch's databases are supported.
Web Service Call: A REST web service call.
Predefined Population: A population constructed from the typical population groups on campus (Faculty, Staff, Undergrads, Retirees, etc.)
Adhoc API Data: You will push members into the population through a call to the Ad-Hoc API.
Subscription Lists: A list of email addresses where recipients can opt in or out. Custom fields can also be populated.
Subsets of Subscription Lists: A subset of a Subscription List based on query parameters.
Active Directory Group Membership: Gets members of an Active Directory group while retrieving additional attributes from IDW.
Combined: Combines multiple populations together into one super population.

Manual Email List

Each line can contain a comma-separated list of email address (toAddress) and name (toName). If only one value per line, that value will be assigned to the toAddress attribute.

Example: Both email address and full name

herky-hawk@uiowa.edu,Herky Hawk
cy@iastate.edu,Cy Clone

Example: Just email address

joe-smith@uiowa.edu
john-doe@uiowa.edu

Manual CSV List

Each line can contain a comma-separated list of various attributes with the first line defining the fields. One or both of the fields "toName" or "toAddress" should be in the population.

Example 1:

toAddress,toName,college
john-doe@uiowa.edu,John Doe,CLAS
jane-smith@uiowa.edu,Jane Smith,MED

Example 2: Row 2 has a null attribute

toName,address1,address2,city
John Doe,123 Main St.,Apt A.,Iowa City
Steve Smith,999 1st. Ave,,Cedar Rapids

Screenshot of Manual CSV List member tab

Manual ID List

You can use a list of HawkIds and/or UniversityIds to defined your population. Each value will be resolved in IDW. You can chose which attributes you want to return from IDW in your population. If the HawkId or UniversityId cannot be located in IDW, all the attributes returned for that member will be null.

Example 1: Mixed HawkIds and UniversityIds

hhawk
jdoe
00029728

Database Query

Database queries can be made against configured databases. Currently, Dispatch is setup to connect to DWPROD and Dispatch's internal database. If other database connections are needed, please contact the Dispatch administrator. In order to connect to the database, credentials must be used. These credentials are assigned to the Dispatch client and can be shared amongst populations. The saved credentials should match against username/password combinations on the target database.

Please keep in mind that for Oracle queries, columns are returned all in uppercase so your templates will need to reference the attributes in uppercase.

Web Service Call

Dispatch can consume a JSON array returned from a web service call to an external application. Applications must reside within the data center networks. Basic Auth is used to access secured web services by choosing a Saved Credentials.

[
   {
       toName: "Herky Hawk",
       toAddress: "herky-hawk@uiowa.edu"
   },
   {
      toName: "John Doe",
      toAddress:"john-doe@uiowa.edu"
   }
]

Predefined Population

Predefined populations are an easy way to get at typical large populations like Faculty, Staff, Undergraduates, etc. You can select from a list of common identity attributes. The attributes email (mail) and name (displayName) will always be returned even if you unselect them. Only people with valid @uiowa.edu email addresses that have mailboxes setup will be returned in a Predefined Population.

Dispatch will query the Identify Warehouse based on preset rules that describe those populations.

All Faculty: Current employee with a Faculty or Executive job code. Also includes Emeritus faculty.
All Staff: Current employee who is not a Faculty member. Also includes Emeritus staff and Iowa Center for Advancement employees.
All Graduate College Faculty: Faculty with appointments in the Graduate College
All Retirees: Retires plus Emeritus faculty and staff
All Students: Undergraduate and Graduate students
All Undergraduates: Current, future and enrolled previous semester students in undergraduate programs
All Graduate Students (Includes Professional Students): Description
All Teaching Assistants (TAs): Current student employees with teaching assistant appointments
All Students in a College: All students with majors in a college

You can filter the groups further by specifying gender, class year (if applicable for the college), or if the person is of legal age or not.

Screenshot of predefined population options

Adhoc API Data

If you are going to use the Ad-Hoc API to push data into a Dispatch communication, you need to create a population to act like a place-holder. When you push member data into Dispatch, it will need to be a JSON array of members like such:

{
    "members": [
    {
        "toName":"Herky Hawk",
        "yourAttribute":"FooBar",
        "toAddress":"herky-hawk@uiowa.edu"
    },
    {
        "toName":"John Doe",
        "yourAttribute":"flurb",
        "toAddress":"john-doe@uiowa.edu"
    }
]}

See the Communications/AdHocs API for more details.

Subscription List

See Subscription Lists for more details.

Subset of Subscription List

See Subsets of Subscription Lists for more details.

Active Directory Group Membership

You can construct a population based on the membership to a group in Active Directory. The group can be in either the IOWA or HEALTHCARE domain and the Active Directory object that has membership in the group must be a person that can be located in the Identity Warehouse. Membership in any nested groups will also be resolved, but only distinct members will be returned so there should be no duplicates. Like other population types, you can select which attributes are returned from the Identity Warehouse.

Screenshot of active directory population options

Combined

You may have multiple populations that you want to combine into a super list so you can contact more than one list with a single communication.

Unique Key: All members of a population have keys (aka columns or attributes) that are associated with each member. When you combine populations there is a good chance you will have duplicates. By providing the key that identifies the uniqueness of each member, duplicates can be removed. The default unique key is toAddress.

Please keep in mind the ramifications of combining populations and the various attributes each population includes. Member attributes keys are case-sensitive so make sure that all attribute keys are identical. If you have a mix of populations that includes a database query to the Data Warehouse, all the attribute keys will be converted to lowercase.

Screenshot of combined population options

Exclusion Key:

The exclusion key prevents multiple messages with the same key from being sent within a communication. For example, an exclusion key of 'toAddress' would ensure that an e-mail communication does not get sent to the same e-mail address twice if that toAddress was already used in the current or previous run of the communication. Applying an exclusion key is only valid for Manual CSV List population types.

If a message is excluded it will appear to be struck through when you view the members of a communication.

Identity Attributes

The Manual ID List, Predefined Population, and Active Directory Group Membership population types all support retrieving identity attributes from the Identity Warehouse. You can select multiple attributes which will be pulled from the Identity Warehouse for the members of the population and made available to include in your communication to customize the content.

* indicates the attribute is included in the default selection of attributes.

uid*: The UniversityId of a person. It referenced as the uiowaUnivId attribute in the Identity Warehouse. It is the unique immutable eight digit number assigned to all members of the institution.
hawkid*: The HawkID of a person. It referenced as the uiowaHawkId attribute in the Identity Warehouse. This is the unique username assigned to all members of the institution upon acceptance of enrollment or hiring.
firstName*: First name of a person. It referenced as the givenName attribute in the Identity Warehouse. The givenName attribute is used to hold the part of a person's name that is not their surname or middle name.
lastName*: Last name of a person. It referenced as the sn attribute in the Identity Warehouse. This is the family name of a person.
name*: Full name of a person in the format of FirstName MiddleInitial LastName. It referenced as the displayName attribute in the Identity Warehouse.
nameLNF*: Full name of a person in the format of LastName, FirstName MiddleInitial. It referenced as the uiowaDisplayName attribute in the Identity Warehouse.
email*: Email address of a person using the primary email alias plus "@uiowa.edu". It referenced as the mail attribute in the Identity Warehouse.
mruid: The MRUID of a person. It referenced as the uiowaMRUID attribute in the Identity Warehouse. The MRUID is a 16 character hex number generated for every person in the directory.
employeeid: The employee ID from HR:PeopleSoft. It referenced as the employeeNumber attribute in the Identity Warehouse. This is the unique numerical ID assigned to all employees in the HR:PeopleSoft system.
personType*: The basic classification of a person in the directory; ie. Faculty/Staff, Student, Affiliate, etc. It referenced as the uiowaPersonType attribute in the Identity Warehouse.
title: The title of a person from HR:PeopleSoft. It referenced as the title attribute in the Identity Warehouse.
department: The description of the HR department of a person's primary appointment. It referenced as the uiowaHRDeptDesc attribute in the Identity Warehouse.
jobCode: The job code from HR:PeopleSoft of a person'a primary appointment. It referenced as the uiowaJobCode attribute in the Identity Warehouse.
deptCode: The four digit code of the HR department of a person's primary appointment. It referenced as the uiowaHRDeptId attribute in the Identity Warehouse.
orgCode: The two digit code of the HR organization of a person's primary appointment. It referenced as the uiowaHROrgId attribute in the Identity Warehouse.
personStatusCode: A comma-separated list of person status codes which describe the various roles a person has within the institution. It referenced as the uiowaPersonStatusCode attribute in the Identity Warehouse.
privateEmail: The private email address captured during the admissions process. This address should not be used after the student's University-provided email account has been activated. It referenced as the uiowaMailRoutingAddress2 attribute in the Identity Warehouse.

Test and Preview Population

Testing and previewing a population will generate the population and tell you how many members will be in the population and preview the first few members with their various attributes.

Validate Population

Validating a population will render the population and begin the process of verifying all the email addresses in the population. Three types of validation happen:

Email addresses are checked for the correct format according to the rules specified by the W3C as that seems to be the most realistic interpretation of what constitutes a valid email address.
The domain of the email address is checked to make sure it has a valid MX record for delivery.
All email addresses ending in @uiowa.edu are validated against IDW to make sure that a person can be found for that address and that there is a routing address for that person.

Any addresses that fail validation should be removed from the population. The population will be validated when the batch members are generated. Validation failures will be recorded as delivery errors.

Clone Population

Cloning a population will make a copy of the population.

Export Population

You can export the generated population as a CSV file with all the attributes present.

Archive/Delete Population

If a population is not used in a communication, you have the option to delete the population in the top-right corner of the Edit screen. If the population is associated with a communication, it can only be archived. Archived populations can continue to be used in communications, they will just not be visible when selecting a population. You can see archived populations using the filter on the population list screen.

Hide/Show Population

You might have some source populations that you do not wish to expose during communication creation. You can opt to hide those from default views by clicking the Hide Population link in the top-right corner of the population edit page. The populations will still be available to use in combined populations or as source populations to queryparams. You can view hidden populations by adjusting the filter on the population list view.

Population Query Parameters

You can add parameters to your population to prompt the content creator to supply a value that is provided to either a Database Query or Web Service Call population. This is helpful when you have a population and it needs to fetch a unique membership based on a changing value. In order for your SQL (for a Database Query) or URL (for a Web Service Call) to be parsed for queryparameter tags, you must check the Parameterized checkbox.

Screenshot of database query with queryparameters

See Population Parameters for more details.