Managing XML Transformation Jobs

8.1 Configuring XML Transformation Jobs

You can create an XML transformation job to transform an XML file into a desired output.

Note:

Before you start creating a new XML transformation job, first configure a JMS Queue.

To configure a JMS Queue for a single server:
1. Log in to Oracle Weblogic server. Click Home and then select JMS Modules.
2. On the Summary of JMS Modules page, click the capture-jms-module from the list.
3. On the Settings for capture-jms-module page, click the New button on the Summary of Resource table.
4. On the Create a New JMS System Module Resource page, select Queue and then click Next.
5. Enter the following values in the respective fields:
  - Name: capture-xsltprocessor-queue
  - JNDI Name: jms/capture-xsltprocessor-queue
  Click Next.
6. On the Create a New JMS System Module Resource page, select CaptureSubDeployment from the Subdeployments drop-down menu. The JMS Server will be displayed. Click Finish.
7. Now, you can see a new queue capture-xsltprocessor-queue is added.
To configure a JMS Queue for cluster environment:
1. Log in to Oracle Weblogic server. Click Home and then select JMS Modules.
2. On the Summary of JMS Modules page, click the capture-jms-module from the list.
3. On the Settings for capture-jms-module page, click the New button on the Summary of Resource table.
4. On the Create a New JMS System Module Resource page, select Distributed Queue and then click Next.
5. Enter the following values in the respective fields:
  - Name: capture-xsltprocessor-queue
  - JNDI Name: jms/capture-xsltprocessor-queue
  Click Next.
6. Now, you can see a new distributed queue capture-xsltprocessor-queue is added.

To verify whether the JMS Queue is configured, go to the Domain Structure on the left and then select Deployments. If the JMS Queue is not configured, the Health column of the Deployments table will show Warning, otherwise, it will show OK.

You can create an XML transformation job to transform an XML file into a desired output, as well as assign Capture metadata fields values from the XML. You can do this by configuring the supported combinations of XSLT processor definitions and supplying your custom XSLT file. Additionally, an XPath expression can be mapped to Capture metadata fields. The converted XML file can then be used by third-party applications to suit the other parties’ business needs.

In the procedures pane on the left, select your procedure.
The configuration pages for the selected procedure appear on the right.
Open the Processing tab.
In the XML Transformation Jobs table, click , or to edit an existing job, click .

You can also copy an XML transformation job by selecting it, clicking , and entering a new name when prompted. Copying a job allows you to quickly duplicate and modify it.
On the Document Selection page:
1. In the Document Selection section, do the following:
  - Enter a name and description for the job.
  - Select the Process Documents check box if applicable to the choices you made in the previous steps.
    
    Note:
    The Document Destination section is enabled on the Output page only if this check box is selected.
  - To process the XML transformation job for specific document profiles, select one or more document profiles listed in the Restrict to Document Profiles field, or select All to process documents for all defined document profiles.
2. In the Attachment Selection section:
  - Select the Process Attachments check box if applicable to the choices you made in the previous steps.
    
    Note:
    The Attachment Destination section is enabled on the Output page only if this check box is selected.
  - Restrict to the required attachment types by selecting the check boxes for the available attachment types. You can also select all of them.
On the Transformation Definition page:
1. If the Perform XML Transformation check box is not selected already, select it to enable editing of the field values on this page.
  Note:
  - Deselecting this check box disables editing while retaining the last saved values in the fields. You can deselect this check box when XML transformation is not required.
  - The Perform XML Transformation check box must be selected to enable the Output page.
2. In the Transformation Engine section:
  - Select compatible XSLT Version, Processor, and Processor Version. Either choose system defaults or choose from the available XSLT versions compatible with Xalan and Saxon-HE processors and their versions.
  - Specify an Output File Extension such as XML, HTML, JSON, text.
    
    Note:
    If the output file extension doesn't equate to XML, the Field Mapping page is disabled.
3. To perform a transformation, upload or type in the XSLT in the XML Stylesheet section.
4. Parameters you included in your XSLT should be defined in the Parameters table. To do this:
  1. In the Parameters table, click .
  2. In the Add XSLT Parameters dialog, add the parameter name and assign it a value. You can add a text value or assemble a metadata value for your parameters.
  3. Repeat steps i and ii to define the required parameters.
    
    Note:
    If you don't assign values to parameters that are defined in XSLT, or if you assign values to those parameters that do not exist in the XSLT, you won't be able to save your XML transformation job and notified of the same when you try to save the transformation job.
5. In the Transformation Testing section, upload and test the transformed XML to confirm that it is generated correctly and then click Next. You can also preview the content in this section by clicking Preview on the top right side of this section.
The Output page is enabled if you selected the Perform XML Transformation check box on the Transformation Definition page. On the Output page, in the Document Destination section (this section is enabled if you selected the Process Documents check box in the Document Processing section):
1. In the Transformation Output Destination drop-down list, select from the following:
  - Document: Replaces the original document with the transformation results. You can also change the document profile if desired in the New Document Profile drop-down list.
  - Attachment: Stores the results of the transformation as an attachment. You must select an attachment type from the New Attachment Type drop-down list.
  - Capture Field: Stores the results of the transformation in a Capture field. You must select Text Field from the Capture Field drop-down list.
2. In the New Document Profile drop-down list, select the required profile.
3. The New Attachment Type drop-down list is enabled only if you selected the Attachment option in the Transformation Output Destination field. If applicable, select the relevant type.
4. The Capture Field drop-down list is enabled only if you selected the Capture Field option in the Transformation Output Destination field. If applicable, selected a field from the available options.
On the Output page, in the Attachment Destination section (this section is enabled if you selected the Process Attachments check box in the Attachment Processing section):
1. In the Transformation Output Destination drop-down list, select from the following:
  - New Attachment Type: You have the option of changing the attachment type.
  - Capture Field: You must select Text Field or XML Field.
2. The New Attachment Type drop-down list is enabled only if you selected the Attachment option in the Transformation Output Destination field. If applicable, select the relevant type.
3. The Capture Field drop-down list is enabled only if you selected the Capture Field option in the Transformation Output Destination field. If applicable, selected a field from the available options.
On the Field Mapping page, define the navigation to specific elements or attributes so that users can extract their values from the XML document:
1. Select the Perform XPath Field Mapping check box to enable editing of the XPath Field Mapping table. If you deselect this check box, you won't be able to edit the table. However, the last saved values are retained.
2. Select the Fail Batch on Parsing Errors check box if the parsing format that you will select in the next step must be adhered to strictly.
3. On the top right of the XPath Field Mapping table, click
4. In the Edit XPath Field Mapping dialog:
  1. In the XPath Expression field, specify the XPath expression for the selected metadata data field and select the parsing format.
    The XPath expression is evaluated on the output of the transformation if there is one. If a transformation is not performed, XPath expression is evaluated on the document or attachment.
  2. In the Date Parsing Format drop-down list, select the parsing format. If the Capture field is a number, you will see a Number Parsing Format drop-down list instead. If necessary, a custom parsing format may be selected in the drop-down list.
  3. Click OK.
    The value that is added to the XPath Expression column of the XPath Field Mapping table is parsed to a date in the format you selected.
5. Click OK.
On the Post-Processing page, specify based on the following what happens after an XML transformation job completes:
- No system error situations are cases in which all the criteria on the previous page were met. A successful transformation can flow to commit.
- System errors are any cases in which the transformation fails: no records found, too many records found, and so on. For unsuccessful transformations, the batch returns to the Capture client for repair.
See Configuring Post-Processing and Monitoring of an XML Transformation Job.
Review settings on the Summary page and click Submit to save the job.
Configure how batches flow to XML transformation jobs. See Configuring Batch Flow to an XML Transformation Job.
Test the XML transformation job you created.

8.2 Configuring Post-Processing and Monitoring of an XML Transformation Job

Use post-processing options of an XML transformation job to specify what happens after processing completes.

To configure post-processing and monitoring of an XML transformation job:

In the procedures pane on the left, select your procedure.
The configuration pages for the selected procedure appear on the right.
Open the Processor tab.
In the XML Transformation Jobs table, add or edit an XML transformation job.
Click the Post-Processing page to display the processing options for successful processing (no system errors) and unsuccessful processing (one or more system errors). The next steps apply to both sections: When there is no system error and When there are system errors.
In the Batch Processor and Batch Processor Job fields, specify which processing step, if any, occurs after the XML transformation job completes. You can choose from None (no processing occurs), Commit Processor, Recognition Processor, Document Conversion Processor or XML Transformation Processor.
In the email address field, optionally enter an address to which to send an email after processing completes successfully or fails. While configuring and testing an XML transformation job, you might set yourself to receive email notifications upon system errors, then later automatically alert an administrator of processing errors.
In the remaining fields, specify how to change processed batches.
- Rename batches by adding a prefix. For example, rename batches that were unsuccessful with the prefix ERR for follow-up.
- Change batch status or priority. For example, you might change the status of batches with system errors, then create a client profile with batch filtering set to this status to allow qualified users to manually edit and complete batches that encountered errors.
Click Submit to save the job.

8.3 Configuring Batch Flow to an XML Transformation Job

To run an XML transformation job, you must configure batches to flow to the job for processing. You do this by setting the XML transformation job as a post-processing step in a client profile.

You can configure batch flows from the following:

A client profile, see Configuring a Client Profile's Post-Processing.
An Import Processor job, see Configuring Post-Processing.
A Document Conversion Processor job, see Configuring Post-Processing and Monitoring.
A Recognition Processor job, see Configuring Post-Processing and Monitoring.

8.4 Deactivating or Deleting an XML Transformation Job

When you delete an XML transformation job, it no longer remains available for batches for which it is set as a post-processing step. If a job specified for post-processing is not available, an error results for the batch. You may want to change a job to offline for a time before deleting it, allowing you to resolve unexpected issues with its deletion. Online XML transformation jobs run when they are selected in a client profile or on the Post-Processing page of a processor job. You can temporarily stop a job (take it offline) or change a deactivated job to run again. You cannot delete batch processing jobs if they are configured as a post processing job in another batch processor.

To deactivate or delete an XML transformation job:

In the procedures pane on the left, select your procedure.
The configuration pages for the selected procedure are displayed on the right.
Open the Processing tab.
To deactivate a job, select it in the XML Transformation Jobs table and click .

You can also deactivate or activate an XML transformation job by selecting or deselecting the Online field on the Document Selection page.
Select the deactivated job in the XML Transformation Jobs table and click .
When prompted, click Yes to confirm that you want to delete this job.