Merge tags reference

Some merge tags are based on your metadata configuration and many are built-in. The merge tag reference is a complete list of the types, objects available and specific options available.

Features and merge tags matrix

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

TypeFieldAvailable
since
WorkflowAssembleViewer
annotations
WatermarksAuto-filing
templates
Office
Properties
syssignoff-sheet15.2XX    
sysapproval-date15.2XXXXXX
sysworkflow-name15.2XXXXXX
sysworkflow-template15.2XXXXXX
sysfilehold-id15.2XXXXXX
sysdocument-version15.2XXXXXX
sysversion-control-no15.2XXXXXX
sysdocument-control-no15.2XXXXXX
sysworkflow-initiator-name15.2XXXXXX
sysdocument-owner-name15.2XXXXXX
sysdocument-name15.2XXXXXX
sysnow16.1XXXXXX
sysfull-name16.1 XXXXX
sysuser-id16.1 XXXXX
sysclient-internal-address16.2 XXXXX
sysclient-external-address16.2 XXXXX
sysclient-hostname16.2 XXXXX
sysserver-external-address16.2XXXXXX
sysserver-hostname16.2XXXXXX
syspage-number16.2  XX  
systotal-pages16.2  XX  
sysdocument-schema16.2XXXXXX
md<any>15.2XXXXXX
replace<na>16.2    X 
link<id>16.2XX    
embed<id>16.2XX    
expand<id>16.2XX    

 

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

Sheet types:

  • horizontal – similar to the standard signoff sheet available in the client application.
  • vertical – a vertically oriented version of the signoff sheet in the client application.
  • list – a list of participants. By default, each item in the list includes the participant name or delegated participant name, participant title from the contact information, and the task completion date. Each task is separated from the one before by a blank line. If the title field is blank in the contact details, no title line is output. Column headings are not used with the list type.

Modifiers include:

  • all – the signoff sheet includes all workflows for the document version instead of just the current one.
  • IncludeReviewers – includes review participants. When this modifier is present, some column headings are changed from the default.**
  • ClearFields – disables all currently enabled columns. For example, Column(participant),ClearFields effectively disables participant.**
  • Column(<column-name>[,<true>|<false>) – allows a user to specify if specific columns are displayed in the sign-off sheet. True causes the field to be included and false causes the field to be suppressed. If neither is specified, true is assumed. 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. This modifier will set the format for the default date or a manually enabled date that occurs after the modifier. 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 headingColumn nameSupported sheet types
Signer name or Participant name (IncludeReviewers)participantvertical, horizontal, list
On behalf ofon-behalf-ofvertical, horizontal, list
 participant-titlelist
Approval date or Date (IncludeReviewers)datevertical, horizontal, list
Document namedocument-namevertical, horizontal
Workflow nameworkflow-namevertical, horizontal
Participant typeparticipant-typevertical, horizontal
Commentcommentvertical, 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 nameDateParticipant typeComment
April Ludgate7/22/2019ReviewerNo comment.
Leslie Knope7/23/2019ApproverI took your idea and made it better.
Ron Swanson7/24/2019ApproverThe 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 typeComment
ReviewerNo comment.
ApproverI took your idea and made it better.
ApproverThe 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:

Expands to 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 location where the field is used. Date and numeric fields can utilitize the field format options. Check box fields return values of True and False.

For example:

[[md|Invoice Number]]

 

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 icon for merge tags (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".

Merge tag functions

Merge functions can change the normal value of a merge tag.

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. It works with system or metadata date fields.

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.

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]]