Metadata Scripting

The Metadata Scripting node is an advanced process used to manage metadata associated with files in the workflow. With this node, you can modify, copy, or delete metadata captured from files in the workflow. For example, you can create a rule to remove trailing spaces from metadata. You can also add new metadata.

A metadata script consists of one or more rules you create to manipulate metadata in a workflow. For each rule, you define the type (for example, Modify Metadata or Copy Metadata), then select the metadata key to which you want to apply the rule. You then configure the rule to achieve your desired results. All this is done using the Metadata Rule Builder.

To apply metadata scripting to metadata in a workflow, add a Metadata Scripting process node to the workflow and double-click on it. The Node Configuration window appears:

Use the controls in the upper-left corner of the Node Configuration window to name and enable the node.

• Enabled - To enable this node in the current workflow, check the box at this field. If you leave the box blank, the workflow ignores the node and documents pass through as if the node was not present. Note that a disabled node does not check for logic or error conditions.

• Node Name - The node name defaults to this field. This name appears in the workflow below the node icon. Use this field to specify a meaningful name for the node that indicates its use in the workflow.

• Node Description - Enter an optional description for this node. A description can help you remember the purpose of the node in the workflow or distinguish nodes from each other. If the description is long, you can hover the mouse over the field to read its entire contents.

Buttons

• Help - To access Online Help, click this button.
• Cancel - To exit the window without saving any changes, click this button.
• Save - To preserve your node configuration and exit the window, click this button.

Metadata Rule Builder

Use the Metadata Rule Builder area to create your metadata rules. Do the following:

1. Enable verbose logging for rules - To include more verbose logging messages in the Activity Log for debugging scripts, select this box. Otherwise, clear the box. This box appears below the Metadata Rule Builder area.

2. Add New Rule - Select Add New Rule on the toolbar, and then select one of the following rule types from the drop-down menu that appears:

   • Modify Metadata - Modify existing metadata.

   • Copy Metadata - Copy existing metadata to a new metadata key.

   • Add Metadata - Create new metadata. The value returned will be assigned to the new metadata key that you define in the Output Key field.

   • Delete Metadata - Delete a selected metadata key.

   • Call Function – Perform a function on existing metadata and store the value for use in other function calls.

3. Select Metadata - To choose the metadata key to which to apply the rule, select the Ellipsis button in the Metadata Key column. The Metadata Browser appears, from which you can choose the metadata key.

4. Define Function - To define the function to apply to the rule, select the drop-down menu in the Function column. The Select Function window appears. You can select one of the built-in functions, or select a custom function (if any) from the User Defined Functions field. See the following illustration:

   

   To create your own function, select the Add/Edit Functions button on the top toolbar to open the Lua Script Editor.

   Note: The Delete Metadata option does not require that a function be defined for it.

5. Specify an Output Key – To define a new metadata key for the value that will be returned from the function, use the Output Key column. The Output Key can contain any group name (for example, {myGroup:custom_zone}). Not all rules require an output key.

6. Specify a Range – To define a page and occurrence range for the metadata rule, use the Range column.

   For Pages, your options are:

   • Document – Process metadata found in the entire document.

   • All Pages – Process metadata found on every page.

   • All Even Pages – Process metadata found on all even pages.

   • All Odd Pages – Process metadata found on all odd pages.

   • First Page – Process metadata found on the first page only.

   • Last Page – Process metadata found on the last page only.

   • Custom Range - Process metadata in a custom page range. When you choose this option, an empty field appears in which you can enter the page range. Do the following:

     • Specify a page range by using commas and/or dash signs counting from the start of the document. For example, to process pages 1, 2, 5, 6, and 7, enter:

       	1, 2, 5-7 
       

     • Specify a specific processing sequence within a range of pages by using parentheses. For example, to process every third page from pages 1 to 10, enter:

       	1-10(3) 
       

     • Specify the last page by using ‘end.’ For example, to process pages 15-20 of a 20-page document, enter

       	end(-5) - end 
       

     Other examples include:

     • To process pages 1, 2, 5, 6, 7, and 19 of a 20-page document, enter:

       	1,2,5-7, end(-1)
       

     • To process pages 10-15 of a 20-page document, enter:

       	10-end(-5)
       

     • To process every other page from pages 10-15 of a 20-page document, enter:

       	10-end(-5)(2)
       

     • To process pages 15-20 of a 25-page document, enter:

       	end(-10)-end(-5)
       

     • To process pages 10-20 of a 20-page document, enter:

       	end(-10)-end
       

   For Occurrences, your options are:

   • All Occurrences – Process all occurrences of metadata found.

   • All Even Occurrences – Process all even occurrences of metadata found.

   • All Odd Occurrences – Process all odd occurrences of metadata found.

   • First Occurrence – Process the first occurrence of metadata found.

   • Last Occurrence – Process the last occurrence of metadata found.

   • Custom Range – Process a custom occurrence number for metadata found. When you choose this option, an empty field appears in which you can enter a range. You can specify an occurrence range by using commas and/or dash signs counting from the start of the document. For example, to process metadata occurrences 1 and 2, enter:

     1-2

7. Validate - To check your rules for errors, select the Validate button on the top toolbar. Any rules that do not validate successfully appear in a pop up window along with an error message to help you fix the issues. Run the Validate process until no error messages appear.

Adding/Editing Functions

The Add/Edit Functions button on the top toolbar provides access to a built-in Lua Script Text Editor you can use to create or edit unique Lua functions. The script editor supports full syntax highlighting for Lua scripting. It also provides the built-in function reference library that you can use to copy or insert into the text editor. See the following illustration for an example:

Script Editor Toolbar

The Lua Script Text Editor contains a toolbar with action icons to help you edit your function. See the following illustration:

The icons do the following, from left to right:

• Load contents of external Lua script into editor
• Save the contents of Lua script
• Export the Lua script into a new file
• Cut text
• Copy text
• Paste text
• Undo last action
• Redo last Undo
• Toggle line numbers
• Toggle white spaces/tabs
• Text wrap
• Toggle output / console
• Toggle built-in Function Library

Function Reference Library

The Function Reference option on the top toolbar provides access to the Function Reference Library, a panel listing built-in functions you can use in your rules and rule functions. Select Function Reference on the top toolbar to display the panel. Select it again to hide the panel. The Search option filters the list to display functions whose name matches a specified text string. If you select a function in the panel, a brief description of the function, as well as its definition, displays in the box below. Select Copy to Clipboard to copy the definition to the clipboard.

You can access the Function Reference Library in either of the following ways:

• Metadata Rule Builder - If you access this way, you can view information on a selected function and copy its definition to the clipboard. However, to add a function to a rule, you must use the Function column in the Metadata Rule Builder.

• Lua Script Text Editor - If you access this way, you can paste a selected function into a Lua script. Do the following:

  1. Select a function from the library. The function is displayed in the bottom area. In the following illustration, the “trim” function was selected:

  

  2. To insert the function into the Lua script editor, select the Insert button. The function appears at the bottom of the script editor, as in the following illustration:

  

  3. To copy the function to paste into the Lua script editor or another application, select the Copy to Clipboard button.