Assign recipients to bursts#

A job that fans out into many outputs often needs each output to reach a different person. This page covers the ways an output gets a recipient and how they interact.

A recipient is not required. An output with no recipient is still produced and still delivered, using the job's own destinations: a fixed network folder, a static email list, a SharePoint location. Plenty of jobs never assign one.

The address book is not the only place recipient information can live, and often it is not the best one. If your source system already records who owns each cost center, or the report itself looks the address up on a worksheet, that information is already where it belongs. Use the address book when you need somewhere to keep distribution metadata that has no better home.

The ways an output gets a recipient#

What the address book is for#

A contact is a bundle of distribution metadata: an email address, a network folder, a SharePoint folder, a Slack channel, a Teams target, a Google Drive location, plus any custom fields you define. It is not a security boundary and it does not grant anyone access to anything.

The useful part is that once an output is associated with a contact, all of that metadata becomes available on the Distribution step. Destination fields and file names can resolve Contact tokens against it, so one job can write each output to its owner's folder and name the file after them. An output becomes associated with a contact in one of two ways: you pick the contact by hand on a burst set, or contact mapping resolves one at run time.

That association is worth setting up when you need per-recipient destinations. If you do not, skip it.

Assign a contact on a burst set#

Every burst grid has a Contact (optional) column, and how you set it depends on the source:

• Static sets give you an editable Choose a Contact combobox on each row, populated from the address book. Select a contact per set, or clear it to leave the set unassigned.
• Excel Source and SQL Source resolve the contact from the source itself: a Contact column in the workbook, or a matching column in the SQL result. The grid shows the resolved contact name as read-only, or blank if the value matched no contact.
• Import and export carry the contact by name, so burstsets.xlsx writes the contact name and import resolves it back against the address book.

Assignment is per set and always optional.

Let contact mapping resolve the recipient#

Contact mapping resolves a contact at run time by matching a value against a field on your contacts. It is not limited to burst sets: it fills the recipient for any output that does not already have one, so it works equally well for a job that fans out by replication.

1. Go to the Distribution step and open the advanced options (the Job Options sidebar).
2. Turn on Associate Contact with a mapping.
3. Choose a Mapping Field, the contact attribute to match on. The list offers the contact's Name, any custom field you have defined on your contacts, and each enabled distributor's destination fields.
4. Build the Mapping Value, the expression that resolves to the value to match. It is usually the parameter that the job fans out on. It can also read a value from a cell in the report, which is how a lookup on a worksheet can drive the routing.

At run time Reportworq resolves the Mapping Value, finds the contact whose Mapping Field equals it, and uses that contact as the recipient.

Field lookups are case-insensitive. The Mapping Value is matched against the contact field with both sides lowercased, so NORTH, North, and north all resolve to the same contact. Casing differences never cause a miss.

Which one wins#

When both are in play, precedence is settled:

• A contact assigned on the burst set wins. Contact mapping only fills an output whose contact is empty, so it is strictly a fallback and never overrides an assigned contact.
• If the Mapping Value matches several contacts, the first is used.
• If it matches none, the output keeps no recipient. It is still produced, any Contact token in the file name or destination fields resolves empty for that output, and delivery falls to the job's own destinations.

Once a contact is resolved, its attributes feed the destination and Contact tokens in the file name resolve against it. See Name and organize output files.

Use cases#

• Owner routing from a custom field. A job fans out on Cost Center, contacts carry a custom Cost Center field, and mapping pairs each statement with its owner without a single hand assignment.
• Recipients maintained with the list. An entity master workbook pairs each entity with a contact in a Contact column, so Excel Source produces both the roster and the routing in one place.
• A curated roster. Twelve static sets, each with its recipient picked by hand, because the pairing is stable and there is no system of record for it.
• Per-recipient folders instead of email. Each contact's Network Folder attribute directs that recipient's output to their own file share, with no email involved.
• One recipient does not fit. Most sets take the mapped owner, and one set overrides it with a named contact because that report goes to a controller instead.

Notes and limits#

• Contacts are distribution metadata, not security. A contact records where and to whom to deliver. It grants no access and gates nothing.
• For mapping to route everyone, every value the Mapping Value can resolve to needs a matching contact, or that output has no recipient.
• The Contact variable type cannot be used inside the Mapping Value, which guards against a circular reference.
• If a newly added custom contact field does not appear in the Mapping Field list, refresh the browser to reload the field set.

Going deeper. A resolved contact's attributes drive where and how each output is delivered, and Contact tokens personalize file names and folder paths. See Destinations, Name and organize output files, and Address book.