External Data

Updated over a week ago

•

5 min read

Overview

The External Data action allows XML formatted metadata created by external services or devices such as MFDs to be used in other Willow360 actions .

For example, Umango, or similar software may perform OCR on an invoice file, extracting useful data e.g. Invoice No, Customer ID, Customer Email, Total Amount etc. storing it in an XML file that accompanies the invoice file. With the new External Data action, Willow360 can read that data and use it when appropriate in subsequent actions.

Basics

  • The third-party software (such as Umango or DocSlide) will provide a pair of a file and its metadata output such as “file.pdf” and “file.xml” (with XML file storing the data about “file.pdf”)
  • These files are uploaded to Willow through Collector. Typically, the third-party software will be configured so it scans to a folder that can be picked up by Collector (and adds metadata XML file next to the scanned file).
  • The XML metadata output of the metadata-producing software has to be configured in a way that Willow understands - metadata inside the Willow360 node
  • User will typically configure metadata-producing software first and then put the example XML output into External Data action configuration. If it's correctly formed XML, the metadata fields will be read on the right side.
  • After the action configuration is done, Willow will be able to receive file + XML metadata pairs of the same structure specified in the uploaded XML example and use that metadata in the workflow.

Rules

  • The action will try to read the necessary data from the XML file and ask the user to fill in the missing data details
  • There can be only one External Data in the workflow. If the action is already added, it will be greyed out in the Add New Action panel
  • Configuration details:
    • The XML data that the workflow expects to get is specified during the action configuration by uploading the example XML file
    • Example XML file has to be configured to have a Willow360 node somewhere in its structure. Typically, this file will be a customised output of software like Umango, Papercut, Drivve or DocSlide.
    • Example document must be a valid XML document. It has to have a single root node and all the elements have to be closed.
    • Node must have the following structure:
<Willow360>
  <Data>
	<Name>Customer ID</Name>
	<Value>353709</Value>
	<Type>Text</Type>
  </Data>
  <Data>
	<Name>Total Amount</Name>
	<Value>158.03</Value>
	<Type>Number</Type>
  </Data>
</Willow360>
  • There is no limit to the number of Data nodes
  • Maximum XML file size is 5MB
  • When the valid example XML file is processed, it displays the metadata on the right side of the action configuration. This becomes the required data for the Example XML Data action.
  • Willow takes the info about the field name and its type
    • Type can be Text, Number and Email
    • The type is used to validate the field values when the metadata is processed.
  • In case there's an error extracting metadata from the XML, the error will be displayed on the right side instead.
  • User(s) who fill in the missing information can also be configured
    • By default, it is the user who added files
    • Information suppliers may be specific users of the organisation or be decided dynamically from the form data (user type)
  • Always manually check data will prompt the user to check the data before submitting even if no data is missing
     
  • Putting the file with XML metadata into Willow:
    • This can be done only through Collector
      • Please note that the user can still just drag&drop or email the files to the workflow, just in that case there will be no XML metadata attached to it
    • Collector knows how to read the XML metadata output of Umango, Papercut and Drivve and to pair a file with its metadata XML file.
    • The pairing is done only if Use Smart Mode is set in the Collector configuration. Once it pairs the files, Collector will send the files to Willow.
    • In Willow, the metadata file won't be visible, but the data from it will be read and stored in the background
  • Reading the metadata in External Data action
    • Willow will try to automatically read all the required data configured in the action configuration (in the above example, it would be Customer ID and Total Amount)
    • If all the information is there (which will typically be the case), the action automatically continues
    • If any field is missing, the user(s) configured in Who supplies the missing information will be notified so they can fill in the missing data in the same way as they fill in the Supply Information form.
      • There can be multiple reasons why data is missing
        • No XML file with metadata exists →  all fields are treated as missing
        • No Willow360 node found → all fields are treated as missing
        • Bad Willow360 node configuration → only correctly structured data is read, the rest is missing
    • The fields that are successfully read from the XML file will be pre-filled in the form
    • All XML metadata fields are validated against their type (specified in the action configuration). If the type is wrong, the notification is thrown and the user is taken to the Supply Information form with the fields with the wrong type info prefilled. If the user tries to submit, it will show a validation error until they put the info in the right format according to its type.
    • If the Always manually check data option is checked, the user will be notified to fill in the form even if all the info is there
    • When a file finishes the External Data action, all the data specified in the action configuration will be there, automatically or manually inserted
    • When the action is done, metadata details will be added to the File History
      • When data is automatically read, the history item will say “External data supplied”, and when the user provides it manually, it will look the same as Supply Information action history item - “Information supplied” (with field values shown in details in both cases)
      • Numbers will be shown in user language in the history item, but when using it as metadata it will be translated into organisational language
  • Using the External XML Data
    • Metadata inputs have the External XML Data option. All the fields specified in the External XML Data action configuration will be listed.
    • Only the actions after the External Data action can use its data.
    • If you want more info on the actions where External XML data can be used in metadata inputs, please check the Metadata Concept chapter (under External XML Data bullet).

Related Articles