Using Data Sources

Overview

By default, a Box Doc Gen template can use the fields on the record you generate from, fields on its parent (lookup) records, and its child records through nested tables.

Data sources let you bring additional data into a template, for example:

• The results of a SOQL query, including records that aren't directly related to the starting record
• Images stored in the Box folder of the record, or of a parent or child record
• Image files attached to the Salesforce record
• Data returned by a custom Apex class or a Salesforce Flow

Each data source has an alias, which is the name you use to reference its data in your template tags. Once a data source is active, its tags appear in the Doc Gen Template Tagger, and its data appears in the template's Preview Payload.

Before you start, make sure you've completed Setting up Box Doc Gen in Salesforce and created at least one Box Doc Gen template.

Data source types

Creating a data source

Important: The instructions below may vary depending on changes made to the Salesforce interface, which is outside of Box's control.

1. From the App Launcher, search for and navigate to Box Doc Gen Data Sources. The list shows all data sources in your org. Each data source is given an automatically generated name (for example, DS-00000120).

   
    

2. Click New.
3. In the Alias & Type section:
   • In Doc Gen Template, search for and select the template this data source belongs to.
   • In Alias, enter the name you'll use to reference this data in your template tags (for example, account_contacts). The alias:
     • Can contain letters, numbers, and underscores, and must start with a letter.
     • Must be unique among the active data sources on the template (not case-sensitive).
     • Must match the alias used in your template tags exactly.
   • In Type, select the data source type. The Type Settings section updates to show the settings for that type.
4. Complete the Type Settings section. See the instructions for each type below.
5. In the Details section:
   • Execution Order — if the template has more than one data source, enter a number to set the order in which they run.
   • Is Active — selected by default. Clear this checkbox to turn off the data source without deleting it.
   • Description — optionally, describe what the data source is used for.
6. Click Save.

Note: Changing a data source's alias after you've used it in a template will break any tags that reference the old alias. Update your template tags if you change it.
 

Setting up a SOQL data source

1. In Type, select SOQL.
2. Under Build a query, select an Object. Your query appears in Generated SOQL.
3. In your query, you can use these values to filter results:
   • :recordIds — the full list of records in the document generation job
   • :userId — the current user
   • :orgId — the current org
   • :record.FieldName — a field on the record, for example :record.StageName
4. Under Matching Criteria, define how query results are matched back to the records in the job:
   • Row Match Field Type — what each row is matched to (for example, recordId)
   • Row Match Mode — how the match is made (for example, Field Path)
   • Row Match Field — the field in your query results that holds the matching value
5. Click Validate query to check your query.
6. Click Save.

Example: A SOQL data source with the alias opportunity_contacts is referenced in a template as {{opportunity_contacts.Name}}.

Setting up a Box Record-Folder Images data source

Use this type to include images that are already stored in Box, in the Box for Salesforce folder of a record.

1. In Type, select Box Record-Folder Images.
2. Under Where to look, in Look in the Box folder of, select which Box folder to use:
   • This record
   • A parent record
   • Child records
3. Under What to find, in How to find images, select one of the following:
   • Search record folders
   • Regex record folder — match file names against a pattern
     • To check your pattern, enter example file names in Sample filenames box, one per line. Matching names are highlighted.
   • Record subfolder — look in a specific subfolder of the record's folder
   • Metadata filter on record folder — filter files by Box metadata
4. Under File types, select the image types to include. PNG, JPG, JPEG, and GIF are selected by default.
5. Click Save.

Setting up Apex and Flow data sources

Apex and Flow data sources run logic your team builds in Salesforce. Work with your Salesforce admin or developer to create the Apex class or Flow first, then select it in the data source.

• Apex — select Apex in Type, then select the Apex class. The class must be built to work as a Box Doc Gen data source.
• Flow — select Flow in Type, then select an active, autolaunched Flow.

Previewing your data

You can check the data a template will use before generating a document:

• Preview Payload on a data source — on the data source record, open the Preview Payload tab to see the data returned by that data source alone.
• Preview Payload on a template — on the Box Doc Gen Template record, open the Preview Payload tab, select a Sample record, and click Preview payload. This runs every active data source on the template against that record, using the same merge path as document generation, and shows the resulting JSON.

Using data source tags in your template

Data source tags appear in the Doc Gen Template Tagger on the template's Tags tab:

1. On the Box Doc Gen Template record, go to the Tags tab.
2. In Sample record, select a record and click Generate data source tags.
3. On the Tags tab of the Tagger, under Show, select Data sources to see only data source tags, or All to see them alongside the record's fields.
4. Select a tag to copy it, then paste it into your template.

Note: The tags shown are based on the data returned for the sample record you selected. Because data source results can change from record to record, other records may include tags that aren't shown for your sample record.

Adding images to your template

Box Doc Gen reads image tags from a picture's alt text in Word, not from text in the body of the document. To show images in a generated document, you insert a placeholder image tag in your template and put the image tag in that picture's alt text. When the document is generated, the placeholder is replaced with the real image.

Add a set of images from a data source

Use this for Box Record-Folder Images data source, which can return several images per record.

1. In your Word template, add a loop for the data source, with the loop's opening and closing tags on separate lines:

Example of the generated tag:

{{ for img in Opportunity.opportunity_onsite_photo }}
Add image placeholder
{ "image-path": "img.image", "alt-text": "" }
{{ endfor }}

img is the name you give each image in the loop, and Opportunity.opportunity_onsite_photo is where the data source adds its images (shown in the data source's settings and in Preview Payload).

2. Replace “Add image placeholder” by inserting any picture as a placeholder: Insert > Pictures > Picture from File (or Stock Images).
3. Resize the placeholder to the size you want the images to appear. Generated images usually take on the placeholder's size.
4. Right-click the placeholder and select View Alt Text (on a Mac, this may be Edit Alt Text).
5. Replace anything Word added automatically with the following example from the generated tag, then close the alt text pane:

{ "image-path": "img.image", "alt-text": "" }

6. Make sure Mark as decorative is not selected. If it is, Word removes the alt text and the image won't be generated.
7. Save your template.

Template example once set up:

Add a single image

To add one image that isn't part of a loop, insert a placeholder picture as above and set its alt text to point directly at the field that holds the image. For example, for a URL stored in a field named Logo_URL on the Opportunity:

{ "image-path": "Opportunity.Logo_URL" }

Tips

• Every image loop needs its own placeholder picture with its own alt text, and its own closing {{ endfor }} tag. A loop without a closing {{ endfor }} causes document generation to fail.
• Use the template's Preview Payload tab to check the path to your images before you set the alt text.

Related Articles

• Setting up Box Doc Gen in Salesforce
• Box Doc Gen in Salesforce - FAQ