1.877.833.1202

Merge tags

Merge tags can be used in various areas of FileHold to insert information into documents, configuration, library objects, etc. System information, such as workflow and document information, metadata field values, or entire documents can be linked, embedded, or expanded into source documents. Merge tags can be used with:

  • Workflow - A template designer can enable the convert to PDF option to run at the end of a workflow activity. One of the options in the convert to PDF feature is to append a Microsoft Word document at the end of each main document in the workflow. Merge tags can be included in this appended document.
  • Document assembly – All supported file types being assembled can include merge tags. The supported file types are those that allow the entry of text content including docx, text, html, and other rich document format files.
  • Watermark definitions – Whether creating a watermark template or adding a watermark directly when using assemble, you can use merge tags to form the watermark values.
  • Viewer annotation – Text values in annotations can include merge tags. Pre-defined annotations can "rubber stamp" values generated by merge tags onto documents.
  • Auto-filing – Merge tags can be used in cabinet, drawer, folder group and folder name definitions when building auto-filing templates.
  • Hybrid-SQL - Merge tags can form portions of the hybrid-SQL statements used to configure the optional workflow routing plug-in.

Merge tags

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 ODCD 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.

  1. 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.

  1. 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 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.

Features and merge tags matrix

Some merge tags are universally available and others depend on the specific version and feature area of FileHold.

Type Field Available since Workflow Assemble Viewer annotations Watermarks Auto-filing templates
sys signoff-sheet 15.2 X X      
sys approval-date 15.2 X X X X X
sys workflow-name 15.2 X X X X X
sys workflow-template 15.2 X X X X X
sys filehold-id 15.2 X X X X X
sys document-version 15.2 X X X X X
sys version-control-no 15.2 X X X X X
sys document-control-no 15.2 X X X X X
sys workflow-initiator-name 15.2 X X X X X
sys document-owner-name 15.2 X X X X X
sys document-name 15.2 X X X X X
sys now 16.1 X X X X X
sys full-name 16.1   X X   X
sys user-id 16.1   X X   X
sys client-internal-address 16.2   X X   X
sys client-external-address 16.2   X X   X
sys client-hostname 16.2   X X   X
sys server-external-address 16.2 X X X X X
sys server-hostname 16.2 X X X X X
sys page-number 16.2     X X  
sys total-pages 16.2     X X  
sys document-schema 16.2 X X X X X
md <any> 15.2 X X X X X
replace <na> 16.2         X
link <id> 16.2 X X      
embed <id> 16.2 X X      
expand <id> 16.2 X X      

 

Merge tag descriptions and examples

signoff-sheet

This tag is output as a simple table similar to the signoff sheet available in the FDA or web client, it also offers a vertical format table, and a limited information list format.

The tag format includes three sheet types and several optional modifiers. The tag format must be specified according to the following pattern: <sheet-type>[,<modifier-list>].

  • horizontal – similar to the standard signoff sheet displayed in the client application.
  • vertical – a vertically oriented version of the signoff sheet in the client application.
  • list – a list of participants. Each item in the list includes the participant name, participant title from the contact information, and the task completion date and time displayed in the regional format. Each task is separated from the one before by a blank line. If the title field is blank, no title line is output.

Modifiers include:

  • all – the signoff sheet includes all workflows for the document version instead of just the current one.
  • IncludeReviewers – includes review participants.**
  • ClearFields – makes all the default fields false (do not appear): “Participant”, “Date”, On behalf of”, “Document name”, “Workflow name”.**
  • Column(<true/false>) – allows a user to specify if certain fields are displayed in the sign-off sheet. True causes the field to be included and false causes the field to be suppressed. Several fields are set true by default including participant, date, on-behalf-of, document name and workflow name. The fields appear in the table in the order they are specified in the tag.**
  • DateFormat(<datetime-format>) – allows a user to specify the date format where <datetime-format> can be a dot net date time formatting code. The formatting code will be applied to any date time field in the signoff-sheet. When no format is provided, it will default to MM/dd/yyyy. The full list of standard or custom dot net format strings for numeric, date, and time values are available from Microsoft.**

** These options are available since 16.2.

The columns available in the sign-off sheet include:

Column name Merge tag Sign off sheet
format supported

Participant name

Signer name

participant

vertical

horizontal

list

On behalf of on-behalf-of

vertical

horizontal

list

Company title participant-title list

Date

Approval date

date

vertical

horizontal

list

Document name document-name

vertical

horizontal

Workflow name workflow-name

vertical

horizontal

Participant type

(optional column)

participant-type

vertical

horizontal

Comment

(optional column)

comment

vertical

horizontal

The following example:

[[sys|signoff-sheet|horizontal,IncludeReviewers,Column(on-behalf-of,false),Column(document-name,false),Column(workflow-name,false),Column(participant-type),Column(comment)]]

Will give the following output:

Participant name

Date

Participant type

Comment

April Ludgate

7/22/2019

Reviewer

No comment.

Leslie Knope

7/23/2019

Approver

I took your idea and made it better.

Ron Swanson

7/24/2019

Approver

The less I know about this, the better.

 

The following example:

[[sys|signoff-sheet|horizontal,ClearFields,IncludeReviewers,Column(participant-type),Column(comment)|This value is always inserted]]

Will give the following output:

Participant type

Comment

Reviewer

No comment.

Approver

I took your idea and made it better.

Approver

The less I know about this, the better.

 

 

approval-date

The date and time the document version was given the approved status. Not approved, pending approval, and not submitted for approval status document have no approval date.

For example:

An approval date with a RFC1123 date format with the option to show "No approval" in the event the document has no approval date.

[[sys|approval-date|R|No approval]]

 

workflow-name

The name of the workflow. The workflow could have been manually named or automatically named through a naming pattern.

For example:

[[sys|workflow-name]]

 

workflow-template

Name of the workflow template.

For example:

[[sys|workflow-template]]

 

filehold-id

The internal document id.

For example:

The internal document id formatted as a 7 digit number with leading zeros.

[[sys|filehold-id|0000000]]

 

document-version

User visible automatic document version number. Note that this is the version number of the source document. When the converted document is added, it will have a different version number.

For example:

To match the FileHold ID and version number

[[sys|filehold-id]].[[sys|document-version]]

 

version-control-no

The version control number.

For example:

[[sys|version-control-no]]

 

document-control-no

The document control number.

For example:

[[sys|document-control-no]]

 

workflow-initiator-name

The name of the user who initiated the workflow.

For example:

[[sys|workflow-initiator-name]]

 

document-owner-name

The name of the user who is the owner of the document.

For example:

[[sys|document-owner-name]]

 

document-name

The file name of the document.

For example:

[[sys|document-name]]

 

now

The date and time when the tag value is expanded.

For example:

Shows the current year.

[[sys|now|yyyy]]

 

full-name

The user’s full name.

For example:

[[sys|full-name]]

 

user-id

The user’s login user name.

For example:

[[sys|user-id]]

 

internal-id

The user’s internal id from the user role manager.

For example:

[[sys|internal-id]]

 

client-internal-address

User client internal IP address. This value is taken from the client machine local IP address. In the case of a web client, the internal address should be derived from the browser (if possible). If the address cannot be derived from the browser, it is the client external address. The web client server gets the address from the HTTP connection with the browser.

For example:

[[sys|client-internal-address]]

 

client-external-address

User client external IP address. This value is taken from the server. It will typically be the server’s host name seen by the browser – server DNS name or external IP address. If the user’s machine is connected to local network and server is outside this network, this tag should be replaced with the public IP. If both client and server machines are connected to single network, values for internal and external addresses will be the same.

For example:

[[sys|client-external-address]]

 

client-hostname

User client host name seen by the server when receiving a request.

For example:

[[sys|client-hostname]]

 

server-external-address

Server external IP address or domain used by the client to connect to the server. This relies on the server's URL as browsers do not provide a possibility to obtain public server IP based on its domain name.

For example:

[[|sys|external-address]]

If the FileHold application server URL is http://filehold.com/FH/FileHold/ and it runs on machine with intranet IP 192.168.100.1 and host name FILEHOLD-SERVER, the resulting tag values will be:

  • server-external-address - filehold.com
  • server-hostname - FILEHOLD-SERVER

In another example, if client machine is located in the same network and FH server URL is http://192.168.100.1/FH/FileHold/, both internal and external addresses will equal 192.168.100.1.

 

server-hostname

Server host name taken from its computer configuration.

For example:

[[sys|server-hostname]]

 

document-schema

The document schema name. Ensure that the spelling and capitalization is exactly the same.

For example:

[[sys|document-schema]]

 

metadata field name

Metadata field value.

Ensure that the spelling and capitalization is exactly the same in both the metadata field definition and the Microsoft Word template.

For date fields, the following function is available:

  • DateOffset

A field value modification function that can add a relative number of dates, months, or years to a date field. Negative numbers can also be used to produce dates back in time. Both system and metadata field dates can be used. This function does not change the actual value in the system, it only changes how it is replaced in the template.

The general format of the function: ​DateOffset(<fieldname>,<yearoffset>,<monthoffset>,<dayoffset>)

Where <fieldname> is a date field, <yearoffset> is the number of years to add to the date, <monthoffset> is the number of months to add, and <dayoffset> is the number of days to add. You can subtract values by using negative numbers.

For example:

[[md|Invoice Number]]

Users want to see the renewal date of a contract start 12 months after the  contract start date.

[[md|DateOffset(Contract start,0,12,0)|MMM-dd-yyyy]]

 

page-number

Page number of the current page in the document.

For example:

Page [[sys|page-number]]

 

total-pages

Total number of pages for the current document.

For example:

Page [[sys|page-number]] of [[sys|total-pages]]

The total pages field is not available for all combinations of document merges.

 

link

Inserts a hyperlink to the document in the FileHold library.

This is a link to a document.

Modifiers available with the link tag:

  • Link(<link-name>) – The name of the link as configured in the library manager. If this is not provided the default link is used. See your senior library administrator for details.
  • Text([arbitrary-text]) – The text to display in the link. If the arbitrary text is not provided the document version name will be used. If the text option is not provided, the link name will be used.

For example:

[[link|4.2|Link(Direct access),Text(Click here to get document)|Document unavailable]]

Where:

link is the link tag

4.2 is the document and version number

Link(Direct access) is the link name to apply to the hyperlink. See Document Links for more information.

Text(Click here to get document) is the hyperlink text

Document unavailable is the null-replacement value. In other words, the document link cannot be inserted into the document.

 

embed

Inserts a hyperlink to the document in the FileHold library and embeds the document into the current document. For security reasons, a password can be added to the embedded document. When a user clicks on the icon, they are prompted for a password. See the PDF options tab – “Open password for embed documents” in Assembling Documents for more information.

For example:

Embed tag icon (paperclip icon on page)

For example:

[[embed|18,This is a document that is embedded|Document not available]]

Where:

embed is the embed tag.

18 is the document number. If no version is specified, the latest version is used.

This is a document that is embedded is a comment for the embedded link. It is arbitrary content and is ignored. It can be used for things like the name of the document but it is not be visible in the output. It cannot contain a field delimiter or closing delimiter but all other content is allowed.

Document not available is the null replacement value. In other words, the document link cannot be embedded into the document.

 

expand

Inserts the contents of the document in the current document. The expanded document must be one of the supported file types: .doc, .docx, .dot, .docm, .dotx, .dotm, .html, .rtf, .txt. Tags can also be placed within the expanded document. These are converted during document assembly as well. The user must access to document in order to expand the contents.

Modifiers available with the expand tag:

Format(Merge|Keep|Replace)

The formatting from the expanded document is determined by the option selected:

  • Keep – Keeps the formatting of both the source and expanded document. The drawback of using Keep is that the imported text might look different in the assembled document when comparing to the source document. For example, the "Heading 1" style in the source document uses Arial 16pt font and the "Heading 1" style in the expanded document uses Times New Roman 14pt font. In the assembled document the expanded text section appears as Times New Roman 14pt font. This is the default option and is used if no format is specified.

  • Replace – Uses the formatting in the expanded document. Any required styles are copied to the source document. Using the Replace option ensure the imported text looks in the assembled document exactly like it was in the source document. If a matching style already exists in the source document, the source style is copied and given a unique name by appending a suffix number to it, for example "Normal_0" or "Heading 1_5". The drawback of using Replace is that if you perform several assemblies, you could end up with many styles in the destination document and that could make using consistent style formatting in Microsoft Word difficult for this document.
  • Merge – Merges the formatting of the two documents. Any styles that differ from the source document are copied. Using Merge option allows to reuse expanded document styles if the formatting they provide is identical to the styles in the source document. If the style in the expanded document is different from the source then it is imported.

For example:

[[expand|27|Format(Replace)|Document not available]]

Where:

expand is the expand tag.

27 is the document number. If no version is specified, the latest version is used.

Format(Replace) is the formatting option.

Document not available is the null replacement value. In other words, the document cannot be embedded into the document.

It is recommended that you test the formats with your documents to see which works best.

The current document cannot be expanded into itself.

 

replace

The “replace” merge tag can be used in the Cabinet/Drawer/Folder Group/ Folder Name field in auto-filing templates. It is used in conjunction with the Search and Match fields in the library object definition. It allows for the replacement of a value when the search and match conditions are met. At this time, the replace tag can only be used with auto-filing.

Modifiers available with the replace tag:

  • Separator(<string>) allows the user to specify a replace separator to use between multiple matches. The default is comma then space. A "\)" can be used to escape the closing parenthesis. Separator() means no separator. For example, if the input string is "abc" and the regex is "([abc])" then there will be three matches for $1. If the replace value is set for default results the expanded string will be "a, b, c".
  • Merge(true|false) determine if like values should be merged together. The default is true. For example, if the option to include all values is chosen and there are three matches "apple", "orange", and "apple" and Merge(true) then the two apples will be merged to one value. If the separator is the default the replace value will be "apple, orange". In another example, if the input string is "abcdebc" and the regex is "([cde])" there will be 4 matches for $1, but two of them will be the same values. Given default values for the replace the output will be "c, d, e".

Any captured groups can be used in the <regex-replace-value> where they were found the in corresponding Match field. The context for the Match field and “replace” merge tag must match. A matched group for the cabinet name cannot be used in a replace tag for the drawer name.

For example:

  • [[replace|${term1}-${term2},all|Separator(, ),Merge(false)]] would produce "apple-fruit, orange-fruit, carrot-vegetable" if the matched values for term1 were apple, orange, carrot and the matched values for term2 were fruit, fruit, vegetable. The match term had used the regular expression \G(?:\(\s*(?<term1>\w+)\s*,\s*(?<term2>\w+)\s*\))+,? with the match value of something like "(apple   ,fruit ),( orange,  fruit ),(carrot,vegetable)".
  • In this example, the leaf node from a drilldown menu is being extracted. The menu option chosen is Truck>Wheel>Rim>Nut and we want to use Nut as our replacement. The following regular expression extracts all nodes of the drilldown menu: \G(?<node>\w+\s?\w*)>? and the replace tag should be [[replace|${node},last] to produce the value "Nut". If we wanted the second and third nodes separated by a pair of hyphens, the replace expression is: [[replace|${node},Index(2,3)|Separator(-),Merge(false)|Missing node]] and the value would be Wheel--Rim. If the drilldown value was Truck>Paint, the prior replace tag would give the following result since there is no third node: "Paint--Missing node". If the format option Merge(true) was included, the same input would result in the output "Paint".