Merge Fields

An invoice number, a customer's name, the total of an order: every single value in a merged document comes from a merge field. A field is found by its name, so the names in the template and in your JSON data have to agree. Read on for how fields get their values, where you insert them, how they format numbers and dates, how to list the fields of a stored template and what happens to fields the data doesn't fill.

The commands below use sample_invoice.tx, the demo template of every trial account, and the invoice data of Merge Data, saved as data.json.

What a Merge Field Is

A merge field is a named placeholder in an MS Word compatible template. Until the template is merged, the field shows a text such as «invoice_no»; during the merge, ReportingCloud replaces it with the value of the same name from the data.

A field has more than a name. The GET /v1/templates/info endpoint reports these properties for each field of a stored template:

Name Fields After the Data

Where a field is in the template decides where its value comes from:

• Top-level fields, outside of any merge block, take the value of the record with the same name. The field invoice_no receives "778723" from data.json.
• Fields inside a merge block take the value of the current element of the block's array. In the block item of the demo template, the field qty receives the qty of each line item in turn, as Merge Blocks explains.
• Fields for a nested object join the name of the object and the name of its value with a dot. In the sales report of Nested Blocks, the field product.name inside the items block receives name from the product object of each item.

The merge matches names without regard to letter case, so the key InvoiceNumber in the data fills a field named invoicenumber. Only the case is ignored: invoice_no and invoiceNo are still different names. Two tools change the case of names:

• The template editor lists the names of a datasource excerpt in lowercase: an excerpt with the key InvoiceNumber offers the field invoicenumber.
• The .NET SDK sends the names of your objects in camel case: the property InvoiceNumber is sent as invoiceNumber, as Merge Data describes.

The demo template uses lowercase names with underscores, such as billto_name and item_total, and its data uses the same names, so they read the same in the data, in the editor and in the request.

Insert Merge Fields

You add fields while you design the template:

• In the template editor of the ReportingCloud portal, open the template with a datasource excerpt, sample JSON data with the structure of your real data, and choose the fields from the Merge Field drop-down on the Reporting tab. Template Editor lists the steps, and Template Design designs an invoice this way.
• In a word processor that saves MS Word formats, insert merge fields with the names of your data and save the template as DOCX, DOC or RTF. Upload it to the template storage or send it with the merge request, as Overview shows.

Format Values

A field can format the value it receives. In the template editor, the options of a merge field have a numeric format, such as C for a currency amount, and the options of a date field list long and short date formats. A merge field stores its formats in the template, as the numericFormat and dateTimeFormat that GET /v1/templates/info reports, so the data contains only the values.

How a formatted value looks also depends on the culture of the merge: with de-DE, the format C adds a euro sign, and with en-US, a dollar sign. Culture shows the field options and sets the culture of a merge.

Check the Field Names of a Template

Before you build data for a template that someone else designed, list its fields. The GET /v1/templates/info endpoint returns the fields and blocks of a template in your template storage:

curl "https://api.reporting.cloud/v1/templates/info?templateName=sample_invoice.tx" \
  -H "Authorization: ReportingCloud-APIKey $REPORTINGCLOUD_API_KEY" \
  -o info.json

# The top-level fields
jq -r '.mergeFields[].name' info.json

The response lists the top-level fields in mergeFields, each with the properties of the table above, and the merge blocks in mergeBlocks. The names in mergeFields are the names your data needs, and a template that isn't in the storage is answered with 400. Managing Templates shows the complete response, and Merge Blocks prints the blocks with their fields.

Remove or Keep Empty Fields

When the data has no value for a field, the field is empty. The removeEmptyFields setting decides what happens to it:

• true, the default, removes empty fields from the merged document.
• false keeps them.

The setting is part of the mergeSettings object of the request body. The following commands merge data.json, which has no billto_city, and keep the empty fields:

jq '{mergeData: ., mergeSettings: {removeEmptyFields: false}}' data.json > merge.json

curl -X POST "https://api.reporting.cloud/v1/document/merge?templateName=sample_invoice.tx&returnFormat=PDF&append=true" \
  -H "Authorization: ReportingCloud-APIKey $REPORTINGCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @merge.json \
  -o result.json

jq -r '.[0]' result.json | base64 -d > invoice.pdf

A second setting removes whole lines: removeEmptyLines, false by default, removes lines that contain only empty fields and no other content, such as an address line for which the data has no value. Merge Settings lists every setting with its default.

Next Steps

• Merge Blocks: repeat fields for each element of an array.
• Culture: format currencies and dates for a country.
• HTML Content: merge formatted text into a field.
• Template Design: insert fields in the template editor.