Form Data Extract Mappings

   Journey Manager (JM) The transaction engine for the platform.  |    Platform Developer |  18.11 This feature was updated in 18.11.

Journey Manager supports a data extract feature to extract form data and store it in the external data elements against form submissions. Whenever a user submits a form with data extracts, this data is stored against each form’s submission as a convenient way of viewing and accessing essential data from within Manager. Data extracts may assist in transaction monitoring and reporting, especially for operational support teams, and are required for supporting collaboration jobs.

Manager allows you to define data extracts mappings for form versions and automatically populates them.

A data extract mapping specifies where to find the data to extract it from the form's XMLXML (Extensible Markup Language) is a markup language that defines a set of rules for encoding documents in a format that is both human-readable and machine-readable., using an XPathXPath (XML Path Language) is a query language for selecting nodes from an XML document. In addition, XPath may be used to compute values (e.g., strings, numbers, or Boolean values) from the content of an XML document. XPath was defined by the World Wide Web Consortium (W3C)., and how to name the extracted value, which will be stored in Manager.

To configure data extract mappings:

1. Select Forms > Forms.
2. Locate a form and click Edit.
3. Select a form version and click Edit Form Data Config.
4. Click the Form Data Extract Mapping tab to see the existing mappings.



Here, the extract field name is FirstName, so the extract reference used in the action property value will be $formDataMap.firstName, and the action property used in the job definition's will be { "name": "Task Subject", "value": "Job Number: <b>$job.referenceNumber</b> $submission.form.formName From $formDataMap.firstName $formDataMap.lastName" }

5. Click New to create a new data extract mapping or click Edit to update the existing one.



6. Edit the label for the extracted, displayed or downloaded data item in the Name field.
7. Edit the XPath location in the formXml where the data item can be found in the XPath field. This is used in the Publish / Subscribe to update the formXml.
8. Select the Searchable Extracted Data checkbox to enable searching on encrypted data. For searching, the user must enter the full string, which is not case sensitive.  |  18.11 This feature was removed in 18.11
   Note

   Manager 18.11+ is able to search encrypted PII data, so you don't need to mark form data manually whether it is as searchable or not.

9. Select the Extract Repeating Data checkbox to automatically extract all repeating XML elements in the form submission data extracts. This is only relevant for a data item extracted from a repeating component.
10. Edit the Sequence, which is the order that the extracted data item will display against the form submission. With the first data extract, it automatically starts at 1 and increments with each new data extract. This may be adjusted but must be a unique value. It is better to reorder using the Reorder icon from the FormData Extract Mapping tab.
11. Select the Publish to Shared Data checkbox to publish shared collaboration job step extract data to other step submissions. This is used by collaboration jobs in conjunction with the Subscribe to Shared Data, which is described below. It is configured in the Job Definition JSON in the Step by setting the shareExtractData attribute to true. Publish Subscribe is an alternative mechanism to share data between tasks in a form bundle's collaboration job step, which is made up of two or more separate tasks (submissions). When one task is submitted, Manager processes all the data extracts marked as Publish and puts the values in a map. It then goes through all the other form tasks in the step. Where the data extract has a value that subscribes, the data extract value will be overwritten with the published value. The formXml on the subscribing form will also be updated.
Note

This is relevant for form bundles.

12. Select the Subscribe to Shared Data checkbox to subscribe to shared collaboration job step extract data changes. This is used by collaboration jobs in conjunction with the Publish to Shared Data configuration, which is described above. The subscribe consumes the corresponding Publish event using the published value. To use Subscribe, the XPath location needs to be set to a single node. You won't be able to use the double slash //FirstName to set the value using XPath. Data extracts specified when designing your form don't have the full XPath location.
Note

This is relevant for form bundles.

13. Select the Encrypt Extracted Data checkbox to automatically encrypt the extracted data. This means that the value is unencrypted when accessed via the Manager console, rest API, as well as from entities within Groovy scripts such as delivery services.  |  17.10 This feature was removed in 17.10
14. Click Save to update the changes.

You can also perform the following actions:

• Delete a data extract mapping.
• Reorder the sequence by moving the mapping up one position.

Collaboration Job Contex

Manager passes a collaboration job's context to a form using the SFMData.SystemProfile.Job XML node. This is done during the form rendering. The snippet below highlights the <Job> XML node:

<?xml version="1.0" encoding="UTF-8"?>
<AvokaSmartForm>
    <SFMData>
        <SystemProfile>
            <DisplayMode>Receipt</DisplayMode>
            <HostContext>Page</HostContext>
            <ReceiptNumber>fct-3097-composer-3</ReceiptNumber>
            <SubmitDateString>12 Feb 2015 5:38:54 PM</SubmitDateString>
            <SubmissionMessage/>
            <FormDataServiceURL>http://localhost:9080/maguire/servlet/FormDynamicDataServlet</FormDataServiceURL>
            <RequestLogKey>9c1b9756b3958671c9b2471e23f91d08</RequestLogKey>
            <TrackingCode>NVKMQ9</TrackingCode>
            <Job>
                <AvailableRoutes/>
                <Assignee/>
                <AssignRepeatIndex/>
                <AssignRepeatItem/>
                <ReferenceNumber/>
                <StepName/>
                <RouteName/>
            </Job>
            <FormCode>fct-3097-composer</FormCode>
....

The <Job> node has the following attributes:

AvailableRoutes

A collaboration job passes the AvailableRoutes property to the tasks created at a particular collaboration job step. The job definition below shows the 2 Step Review Job.

{
  "name": "Initial Review",
  "type": "",
  "actions": [
     {
       "name": "Create Task",
       "type": "Job Task Assign",
       "properties": [
         ...
       ]
     },
     {
       "name": "Handle Submission",
       "type": "Job Task Wait",
     }
  ],
  "routes": [
     { "name": "Approve",  "nextStep": "Application Delivery" },
     { "name": "Decline",  "nextStep": "Applicant Update" },
     { "name": "Exceeds Threshold",  "nextStep": "Additional Review",  "display": "false" },
     { "name": "Terminate",  "nextStep": "Terminated Initial" }
  ]
}

When the collaboration job moves to the Initial Review step, it populates the form data with <AvailableRoutes>Approve|Decline|Terminate</AvailableRoutes>. The Exceeds Threshold route is not included due to the display item. This is used in a form as the read-only value.

ReferenceNumber

A ReferenceNumber is a Job Number field, which is displayed on forms with the Step Number as the heading. This is used in a form as the read-only value. For more information, see Composer documentation.

StepName

A StepName is a name of the current step that the collaboration job is currently at. The form can use this value to hide, show or set editability of fields and form sections. This is used in a form as the read-only value.

RouteName

A form user can set a new route in the form using a dropdown list or a radio button. If this is not set, the collaboration job uses the default route. This attribute is set by a form.

Next, learn how to test a new form data extract mapping.

Last updated on : 18 October 2019