Configure XML Transformation Jobs

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 and XML elements can be extracted from the primary document based on an XPath expression. The converted XML file can then be used by third-party applications to suit the other parties’ business needs.

Note:

You cannot create XML transformation jobs in Oracle Content Management Starter Edition. To use this feature, you need to upgrade to Oracle Content Management Premium Edition. For more information, see Starter vs. Premium Edition.

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 Job Details section:
  - Enter a name and description for the job.
  - In the Process Actions section, select the Transformation check box to enable transformation of content in to XML.
  - In the Process Actions section, select the Field Mapping check box to enable editing of the XPath Field Mapping table.
  - In the Process Actions section, select the Element Extraction check box to enable element extraction.
2. In the Document Selection section:
  - 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.
3. In the Attachment Selection section:
  1. 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.
  2. 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, 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.
In the XML Stylesheet section:
1. To perform a transformation, upload the XSLT through XML Upload or type in code in the box.
2. In the Parameters table, define the parameters that you included in your XSLT. 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.
3. 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.
On the Output Destination page, in the Document Destination 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.
  - Document, Preserve Copy: Preserves the original copy. You can also choose a document profile if you select this option. However, you must select an attachment type from the Preserve Attachment Type 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, optionally, you can set a new document profile (or retain the current one without setting this field).
3. The Preserve Attachment Type drop-down list is enabled only if you selected the Document, Preserve Copy option in the Transformation Output Destination field. If applicable, select the relevant type. You can select None if you want to opt out of using a specific attachment type from the Classification tab.
4. The New Attachment Type drop-down list is enabled only if you selected the Attachment option in the Transformation Output Destination field. This drop-down list provides those attachment types that you configured in your document profile. If your document profile doesn't include any attachment types, then those that you created on the Classifications tab in the Attachment Types section are available for you to choose from. You can select None if no attachment types should be considered or if none are available. If applicable, select the relevant type.
5. 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 Destination 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. This drop-down list provides those attachment types that you configured in your document profile. If your document profile doesn't include any attachment types, then those that you created on the Classifications tab in the Attachment Types section are available for you to choose from.
  - Preserve Attachment Type: You have the option of selecting the attachment type. But you must select an attachment type from the Preserve Attachment Type drop-down list.
  - 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. This drop-down list provides those attachment types that you configured in your document profile. If your document profile doesn't include any attachment types, then those that you created on the Classifications tab in the Attachment Types section are available for you to choose from. You can select None if no attachment types should be considered or if none are available. If applicable, select the relevant type.
3. The Preserve Attachment Type drop-down list is enabled only if you selected the Document, Preserve Copy option in the Transformation Output Destination field. If applicable, select the relevant type. You can select None if you want to opt out of using a specific attachment type from the Classification tab.
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 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 Fail Batch on Parsing Errors check box if the parsing format that you will select in the next step must be adhered to strictly.
2. On the top right of the XPath Field Mapping table, click
3. 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.
4. Click OK.
On the Element Extraction page, specify the XPath expression to extract XML elements from the primary document and the XML element destination:
1. Optionally, select the Fail Batch when no XML elements found check box to cause a batch failure when no XML elements are found during element extraction.
2. In the XPath Expression field, specify the XPath expression based on which XML element(s) will be extracted from the primary document (see the code sample below). Each element will be saved to the selected destination.
```
<?xml version="1.0" encoding="utf-8" ?>
<invoice>
  <invoicenumber>INT-3343</invoicenumber>
  <invoicedate>2020-01-31</invoicedate>
  <purchaseordernumber>1949/2020</purchaseordernumber>
  <duedate>2020-02-14</duedate>
  <address type="shipto">
    <name>Road Runner</name>
    <street>1 Desert road east</street>
    <zipcode>2014</zipcode>
    <city>SW Am. desert</city>
  </address>
  <address type="billto">
    <name>Wile E. Coyote</name>
    <street>1 Desert road west</street>
    <zipcode>1949</zipcode>
    <city>SW Am. desert</city>
  </address>
  <lineitems>
    <lineitem>
      <quantity>20</quantity>
      <description>Explosive tennis balls</description>
      <unitprice>$5.00</unitprice>
      <amount>$100.00</amount>
    </lineitem>
    <lineitem>
      <quantity>100</quantity>
      <description>Earthquake pills</description>
      <unitprice>$0.50</unitprice>
      <amount>$50.00</amount>
    </lineitem>
  </lineitems>
  <subtotal>$150.00</subtotal>
  <tax>$7.50</tax>
  <total>$157.50</total>
  <terms>15 days</terms>
</invoice>
```
  In the above sample:
  - The /invoice/lineitems/lineitem XPath expression extracts all the lineitem elements:
```
 <lineitems>
    <lineitem>
      <quantity>20</quantity>
      <description>Explosive tennis balls</description>
      <unitprice>$5.00</unitprice>
      <amount>$100.00</amount>
    </lineitem>
    <lineitem>
      <quantity>100</quantity>
      <description>Earthquake pills</description>
      <unitprice>$0.50</unitprice>
      <amount>$50.00</amount>
    </lineitem>
  </lineitems>
```
  - The /invoice/lineitems/lineitem[quantity > 10] XPath expression extracts all the lineitem elements if more than 10 of those items are ordered:
```
 <lineitems>
    <lineitem>
      <quantity>20</quantity>
      <description>Explosive tennis balls</description>
      <unitprice>$5.00</unitprice>
      <amount>$100.00</amount>
    </lineitem>
    <lineitem>
      <quantity>100</quantity>
      <description>Earthquake pills</description>
      <unitprice>$0.50</unitprice>
      <amount>$50.00</amount>
    </lineitem>
  </lineitems>
```
  - The /invoice/address[@type = 'billto'] XPath expression extracts the billing address element:
    <address type="billto"> <name>Wile E. Coyote</name> <street>1 Desert road west</street> <zipcode>1949</zipcode> <city>SW Am. desert</city> </address>
3. In the XML Element Destination field, specify the destination to save the XML elements that were extracted. The options available are:
  1. Document - Selecting this destination will replace the original primary document with the first XML element that matches the XPath expression and subsequent matches will create new documents in the batch with the same metadata fields and values. Optionally, you can set a new document profile in the New Document Profile drop-down list (or retain the current one without setting this field).
  2. Document, Preserve Copy - Select an attachment type for the copy. Selecting this destination will replace the primary document with the first XML element that matches the XPath expression and subsequent matches will create new documents in the batch with the same metadata fields and values. The original primary document will be preserved as an attachment of the selected attachment type. Optionally, you can set a new document profile in the New Document Profile drop-down list (or retain the current one without setting this field).
  3. Attachment - If you selected this option, select a new attachment type in the New Attachment Type drop-down list. This will create an attachment of the selected attachment type for every XML element that matches the XPath expression.
Note:
- When one of the document options is selected, the original primary document is replaced with the first XML element. If the XPath expression yields more than one element, new documents are created and added to the batch. All the resulting documents will have the same metadata fields and values.
- If you performed transformation (using the Transformation page) before this element extraction step, then the transformed output is used during element extraction. If xml is not specified as the file extension in the Output File Extension field on the Transformation page, then, the Field Mapping and Element Extraction pages are disabled as XPath mapping and element extraction can only be performed on XML output. If the destination of transformation is a metadata field or a new attachment, then field mapping and element extraction will use the original document.
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 Content Capture Client for repair.
See Configure 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 Configure Batch Flow to an XML Transformation Job.
Test the XML transformation job you created.

Configure 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. Only those batch processor jobs that you have defined for your procedure are available for selection. For example, if you didn't define a recognition processor job, then the recognition processor option will not be available in the Batch Processor field. If you choose recognition processor or conversions to TIFF/PDF in the Batch Processor field, then specify the corresponding processor job.
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.

Configure 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, an import processor job, or a processing job discussed under processing settings. See the post-processing information for the job or client profile from which you want to configure a batch flow, under Configure Processing Settings or Configure Capture Settings.

Deactivate or Delete 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.