Merge tags overview

Merge tags make document, configuration and other automation possible.

Definitions

For the purpose of the tag syntax description, the following characters have a special purpose: 

• Square brackets [] enclose optional text. The word [optional] is optional.
• Angled brackets <> enclose mandatory text. The word <mandatory> is mandatory.
• Pipe characters | separate optional values. The color is red|green|blue could mean that either red, green or blue could be the correct color.

The general syntax for all merge tags is the same: an opening delimiter followed by the tag definition followed by a closing delimiter. Fields in a merge tag are separated by a field delimiter. For version 16 and greater, the delimiters are double square brackets [[]] and the field delimiter is a pipe character |.  [[sys|document-name]] is an example of a complete merge tag. This example would produce the value for the document name of the document it is included inside.

In order to avoid confusion between the default delimiter values and the special purpose characters used to explain the syntax, the delimiters will be referred to using OD, CD and FD for opening delimiter, closing delimiter and field delimiter respectively. The example above could be restated with these generic delimiters as <OD>sys<FD>document-name<CD>. Outside of the syntax definition, merge tag examples below will always use the default product delimiters.

It is possible to change the merge tag field delimiters, but we suggest avoiding this where possible to simplify reading this documentation and requesting support. A good reason for changing these delimiters is when they conflict with the normal content of your documents, metadata field names, etc. Versions prior to 16 defaulted to use curly braces as delimiters instead of square brackets. The defaults can be adjusted in workflow settings and assemble document settings.

Syntax overview

All merge tags follow the same basic syntax.

<OD><tag-type><FD><tag-object>[<FD>[tag-format][<FD><null-replacement>]]<CD>For example, [[md|Invoice date|yyyy-MM-dd|No invoice date field]]. In this example, the tag-type is md (metadata field). The tag-object is "Invoice date" (the metadata field name). For metadata fields, the tag-format is used to specify the dot net custom date and time format string. And, if there is no invoice date field defined in the context of the input document, the absolute text "No invoice date field" will be inserted as the null-replacement.

Tag types

There are six tag types:

• sys - System tags provide values intrinsic to the system like document names and can provide compound values like a workflow signoff sheet.
• md - Metadata tags are used to insert the values of metadata fields.
• link - Document links are associated with specific documents or document versions and can be configured by library administrators. This type of tag will insert an URL hyperlink into the output.

Your system must be configured for the end user of the output file to be able to access the hyperlink in the same way as links generally. For example, if you include an FDA link, the user must have the FDA configured on their workstation. If it is a web client link and the user is not within your local network, your FileHold server must be accessible on the internet.

• embed - PDF files can be compound files containing other files. Embed allows the designer to insert an entire file into the output.
• expand - It may be desirable to build a single file from the contents of many files. Expand will take the contents of a file and insert that content into the output. Unlike link or embed, the result in the output will not necessary reveal the source of the content.
• replace - The replace tag can be used when regular expression processing is used on the input source. It can insert content captured by the regular expression into the output.

Tag objects

Different tag types have different syntax for the tag object.

1. For system or metadata tag types:

<object-name>|<function>(<object-name>[,<parameter-list>])

Object name is the metadata field or system field name. For example, [[sys|signoff-sheet]] or [[md|DateOffset(Termination date,0,-1,0)]]. For system tags, the name may be for a compound object instead of a simple field.

2. For link, embed or expand tag types:

<document-id>[.<version>][,<comments>]

Every document in FileHold has a unique document id that can be used to refer to the current version of the document or the version can be added to refer to a specific document version. For example, [[link|4.2,Project evaluation report]. Optional comments are available to include things like the document name or other descriptive information about the tag. The comment has no impact on the output of the tag.

3. For the replace tag:
   <regex-replace-value>[,last|Index(<position-list>)|all[,<length>]]This tag is only used in conjunction with regular expression processing on the input. It makes it possible to use any data captured in the regular expression. For example, assume that drawer names are being set in an auto-filing template. Customer names are in a metadata field, last name first. The customer name is being processed with a regular expression to get the first capitalized letter of the last name: (?<FirstLetter>[A-Z]).*. This will provide a capture group that we can use with the replace tag. We can get the first letter to use in the drawer name with a replace tag like the following: [[replace|${FirstLetter}]].
   
   The tag object has an optional parameter that can be used when more than one value is captured. You can choose the last captured value, a specific captured value with index or all captured values. When you choose all you can also choose to limit the total number of characters returned with length. For example, if the input is ABCD and the regular expression is ([A-Z]) then [[replace|${1},all,4]] produces A, B and [[replace|${1},last]] produces D.

Tag format

Like tag objects, different tag types have different options for the tag format.

1. For date, number, or number system or metadata tag types you can use Microsoft dot NET numeric and date time format strings. For example, yyyy-MM-dd for a year, hyphen, month, hyphen, day. Or, 00000 to include leading zeros for a five digit number. 
2. Signoff sheet, link, embed, expand and replace tags use format codes and modifier functions that are specific to each tag type. For example, [[sys|signoff-sheet|horizontal,Column(comment)]] to show the horizontal table format for the signoff sheet with the comment column. Or, [[link|44312|Link(FDA),Text()]] to show the document name as a hyperlink to the document in the FDA. The specific details for the tag format are included with the detailed descriptions below.

Tag null replacement

By default, if the tag value is not available for any reason in the given context, nothing is added to the output. The null replacement field is a value to use when there is no output. This value is simply literal text.