std:generate:fill_fields transform step

This file transform step fills in fields in PDF and word processing documents. The information property on the FileTransformResult is used to return information about which fields were filled.

NOTE: This transform is implemented by an optional platform component, and may not be available in your installation.

Creating input documents

Text form fields are filled in when filling a PDF file.

MERGEFIELD fields are filled in when filling a word processing document, and IF fields are used to conditionally include content. A definition should look like "MERGEFIELD FieldName" where FieldName is the name which should be used in the fields property.

Using Microsoft Word

To use Word to insert MERGEFIELD fields into a document without creating a mailmerge, you need to do some one-off setup.

  • In the title bar of any Word document, click down the arrow at the end of the left group of buttons (Customise Quick Access Toolbar)
  • Menu: More commands…
  • Choose commands from: All commands
  • Select: Insert a Field…
  • Click the [ > ] button
  • Click Save

An insert field button will appear in the title bar at the very top of the window:

This setup step only need to be performed once.

MERGEFIELD

A MERGEFIELD will be replaced by the value of the field in the fields property:

  • Click the insert field button in the window title
  • Categories: Mail Merge
  • Field names: MergeField
  • Fill in box so it says: MERGEFIELD Something, where Something is the name of the field
  • Click OK

IF

An IF conditionally includes formatted text, based on the value of a field in the fields property. It’s a little bit more convoluted to set up.

  • Click the insert field button in the window title
  • Categories: Mail Merge
  • Field names: If
  • Fill in the box so it says IF X = "Value" "True" "False", where Value is the value you want to test the field against.
  • Click OK
  • False will appear in your document. Right click it, and choose Toggle field codes.
  • Delete the X from the IF definition, and click the insert field button again. This time, create a MERGEFIELD with the name of the field you want to test (see instructions above).
  • Edit the definition so True is the text you want inserted in the document when the value is equals, and False is the text otherwise. Either of these can be the empty string, "", to insert nothing.
  • You can use formatting on the inserted text, such as bold and italic.

After you have completed entering the field, it will look something like:

You can include line breaks and multiple paragraphs in the conditionally included text, but not the " character. Smart quotes can be used as a workaround.

Tip: Write long text outside the IF field, format it, then cut and paste it into the field.

Information in result

The information property in the FileTransformResult will contain a "std:generate:fill_fields" property. This is an array of objects, one per fill fields transform step.

Each of these objects contains an "filled" property, an array of field names that were filled in, and an "unfilled" property, of those where a value was not specified in the fields property of the specification. If fields are repeated in the input file, these arrays will contain multiple entries for that field.

For example:

{
  "std:generate:fill_fields": [
    {
      "filled": ["Field 1", "Field Two", "Field 1"],
      "unfilled": ["Three"]
    }
  ]
}

Transform specification

property input

Name of the input file. Optional, defaults to "input".

property output

Name of the output file. Optional, defaults to "output".

property mimeType

MIME type of the output file. Optional, defaults to the MIME type of the input file.

This transform step can convert between different formats of word processing documents, and word processing documents to PDF.

property fields

A dictionary of field name to field value, both of which must be strings.