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, delete, or add new metadata. For example, this node could be used to remove trailing spaces from metadata.

To open the Metadata Scripting window, add a process node for Metadata Scripting and double-click on it.

• Check the Enabled box when there are multiple processes in a workflow. If unchecked, this process will be ignored. Documents will pass through as if the node was not present. Note that a disabled node will not check for logic or error conditions.

• In the Node Name field, enter a meaningful name for the Metadata Scripting node.

• In the Description field, enter a description for the Metadata Scripting node. Although this is not required, it can be helpful to distinguish multiple processes from each other. If the description is long, you can hover the mouse over the field to read its entire contents.

• Check the Enable verbose logging for rules box to include more verbose logging messages in the Activity Log for debugging scripts.

• Select the Save button to keep your Metadata Scripting definition. You can also select the Help button to access online help and select the Cancel button to exit the window without saving any changes.

Creating Rules

To get started, you must build your metadata rule on the Metadata Rule Builder area of the Metadata Scripting node window. Do the following:

1. Add New Rule - Select the Add New Rule button on the tool bar; then select the rule type from the drop-down palette that appears. The options are:

   • Modify Metadata - This option is used to modify existing metadata.

   • Copy Metadata - This option is used to copy existing metadata to a new metadata key.

   • Add Metadata - This option is used to create new metadata. The value returned will be assigned to the new metadata key that is defined in the Output Key field.

   • Delete Metadata - This option is used to delete the metadata key.

   • Call Function – This option is used to perform a function on existing metadata and store the value for use in other function calls.

2. Define Function - Once you’ve added a rule option, you can specify a function for the metadata under the Function column. You can use predefined functions that are listed in the Function Reference area on the right-hand side of the window or define your own function. Click the arrow next to the field to open up the Select Function palette, which displays the functions that are available for you to choose from, as in the following illustration:

   

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

   Note: The Delete Metadata option does not require a Function defined for it.

3. Specify an Output Key – Under the Output Key column, define a new metadata key for the value that will be returned from the function. The Output Key can contain any group name (e.g., {myGroup:custom_zone}).

4. Specify a Range – Under the Range column, define a page and occurrence range for the metadata rule.

   For Pages, your options are:

   • Document – Process metadata found in 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 custom page range. Once you choose this option, an empty field will appear to 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, enter 1, 2, 5-7 to process pages 1, 2, 5, 6, and 7.

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

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

     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 on the page.

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

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

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

   • Custom Range – Process custom occurrence number for metadata found on the page. Once you choose this option, an empty field will appear to enter the page range. You can specify an occurrence range by using commas and/or dash signs counting from the start of the document. For example, enter 1-2 to process metadata occurrences 1 and 2.

5. Validate - Once you are finished creating your rule, you can validate it by clicking the Validate button on the top tool bar. If the rule(s) do not validate successfully, error messages will display in red at the bottom of the screen.

6. Test – To test your rules, click the Test button on the top tool bar. A Test window will appear, as in the following illustration:

• To run a test on the metadata rule, enter test data in the Sample Data column; then select the Run Test button. The results of your rule will be displayed in green under the Result column, as in the following illustration:

• Once you run a test on a rule, a Show/Hide Test Result icon will appear next to the rule listed in the Metadata Build Area of the node window, as in the following illustration:

If you click on that icon, the results of the test will appear, as in the following illustration. To hide these results, either click on the Show/Hide Test Result icon again or click on the X in the green box.

Adding/Editing Functions

To create or edit unique LUA functions to suit your own business purposes, you can use the built-in Lua Script Text Editor, which is accessible by clicking on the Add/Edit Functions button on the top tool bar. 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:

Using the Tool Bar

The tool bar icons allow you to 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 integrate command shell for testing
• Test functions
• Toggle built-in function library

Using the Function Reference Library

To help you get started, the Metadata Scripting node comes with a function reference library. You can browse through these standard functions and, if desired, copy or insert a specific function into the script editor to modify according to your business requirements.

Do the following:

1. To get started, select a function from the library; the function will then appear in the bottom of the function reference library panel. 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 will appear 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.

Testing Functions

Once you have created/modified a function, you can test it from within the LUA text editor. Do the following:

1. Click on the Test button on the tool bar. A Test pop-up window will appear, similar to the following illustration:

   

2. Click on the down arrow in the Function field to choose the function that you want to test. A drop-down palette will appear displaying all built-in functions that the Metadata Scripting node comes with as well as any custom functions that have been created. See the following illustration for an example:

   

3. Enter sample data to test with in the Sample Data field. You can click on the ellipsis button next to the field to expand this field.

4. Select the Run Test button to begin the test.

5. The command shell will appear at the bottom of the screen, displaying the results of your test. See the following illustration for an example:

   

Example

In the following workflow, the date, invoice number, vendor name, PO number, and invoice amount were extracted from incoming invoices and captured as metadata. All invoices were renamed with the vendor name and processed files and extracted metadata are stored in the OnBase content management system. However, the format of the extracted dates needs to change from mm/dd/yy to yyyy-mm-dd before being sent to OnBase.

Here is a graphical representation of this workflow:

The Metadata Scripting node was used to manipulate the metadata as follows:

• A Modify Metadata rule was created, using the date metadata from the Forms Processing node (in this case, {forms:InvDate}.

• Using the LUA text editor, a user-defined function was created called convert_date that converts the date from mm/dd/yy to yyyy-mm-dd, as follows: