Copy Adapter Examples

Copying from one document to another document 6

The copy adapter copies XML fragments or entire documents from one location to another location. The input and output are both represented by fields in the resource and are mapped via XPath to document locations. Options exist for copying in serialized XML (i.e. a string), creating serialized XML output, and copying portions of XML from one document to another document. In the following examples XML Resources are used, but the functionality applies equally to Web Services Resources and Integration Resources.

Copying from a field to a document

In this example a field containing an XML string will be copied to a document in an XML Resource. We assume that the document structure for the target document already exists in the resource (this is document doc1 in the example below).

In the XML Resource editor:

1. Create a new dummy document: click on documents in the tree panel, then click the add icon at the top of the Documents panel. Add a document called dummy1 (create the document then rename it). Note that it is not necessary to add any nodes to this document.

2. Create a resource field for the copy input: in the Resource Fields panel, click the add icon and add field SRC1. In the field properties panel, set the document dropdown to dummy1, set the XPath to /SRC1.

3. Create a resource field for the copy output: in the Resource Fields panel, click the add icon and add field TGT1. In the field properties panel, set the document dropdown to the target document in your resource, set the XPath to the document location where you want to insert the data (/ to replace the entire document).

4. Create a new copy adapter: click the add icon at the top of the tree panel and create a new adapter named copy1, select Copy Adapter from the dropdown list. Set the source field to SRC1, the destination field to TGT1 and click the Parse Source XML checkbox.

The Parse Source XML option is required because the input in this case is a field containing a serialized XML string.

5. The copy adapter is now ready to be used. In a form, create a character field and map it to resource field SRC1, then call the copy adapter with the call statement e.g.

FPL:

API based language (Javascript):

set SRC1 = '<docroot><things><thing><a>a1</a>b1</thing><thing>

<a>a2</a>b2</thing></things></docroot>';

update XMLEXAMPLE;

call XMLEXAMPLE 'copy1';

fields.SRC1.value = "<docroot><things><thing><a>a1</a>b1</thing>

<thing><a>a2</a>b2</thing></things></docroot>";

resources.XMLEXAMPLE.update();

resources.XMLEXAMPLE.call("copy1");

Note that the FPL update command or API XmlResourceBase.update() method is required to transfer the contents of mapped field SRC1 to the resource.

Common Errors

Message Copy adapter failed No source XML was found issued.

Possible causes include: the FPL update command or API XmlResourceBase.update() method has not been issued prior to the call (see example above), the field containing the XML is not correctly mapped to the resource, the resource input field is not correctly mapped to a dummy document as shown above.

Message Copy adapter failed Cannot find source field issued.

Possible causes include: the source field in the resource is not mapped to a document.

Message Copy adapter failed Cannot find destination field issued.

Possible causes include: the destination field in the resource is not mapped to a document.

Copying from a document to a field

In this example an existing document in an XML Resource will be copied to a field. We assume that the document structure for the target document already exists in the resource. This is the reverse of the first example.

In the XML Resource editor:

1. Create a new dummy document: click on documents in the tree panel, then click the add icon at the top of the Documents panel. Add a document called dummy2 (create the document then rename it). Note that it is not necessary to add any nodes to this document.

2. Create a resource field for the copy input: in the Resource Fields panel, click the add icon and add field SRC2. In the field properties panel, set the document dropdown to the source document in your resource, set the XPath to /docroot. The XPath maps to the root element and indicates that we will copy the entire document.

3. Create a resource field for the copy output: in the Resource Fields panel, click the add icon and add field TGT2. In the field properties panel, set the document dropdown to dummy2, set the XPath to /TGT2.

4. Create a new copy adapter: click the add icon at the top of the tree panel and create a new adapter named copy2, select Copy Adapter from the dropdown list. Set the source field to SRC2, the destination field to TGT2 and click the Escape destination XML into a single text value checkbox.

The Escape destination XML into a single text value option is required because the output in this case is to be serialized into an XML string contained in a field.

5. The copy adapter is now ready to be used. In a form, create a character field and map it to resource field TGT2, then call the copy adapter with the call statement e.g.

FPL:

API based language (Javascript):

call XMLEXAMPLE 'copy2';

fetch XMLEXAMPLE;

resources.XMLEXAMPLE.call("copy2");

resources.XMLEXAMPLE.fetch();

Common Errors

Message Copy adapter failed No source XML was found issued.

Possible causes include: the resource input field is not correctly mapped to the root node of the source document as shown above.

The command appears to work, but XML is not returned to the form.

Possible causes include: The resource output field is not mapped to the form, the FPL fetch command or API XmlResourceBase.fetch() method was not issued after the call (see example above).

Message Copy adapter failed Cannot find source field issued.

Possible causes include: the source field in the resource is not mapped to a document.

Message Copy adapter failed Cannot find destination field issued.

Possible causes include: the destination field in the resource is not mapped to a document.

Copying from one document to another document

In this example a fragment of XML will be copied from one document to another document.

Starting with the XML Resource, created by example 1, we will now extend this to copy the <things> node from doc1 to doc2.

1. Create a new document doc2 and add nodes to create the structure shown below.

Note that doc1 and doc2 do not have exactly the same structure.

2. Create a resource field for the copy input: in the Resource Fields panel, click the add icon and add field SRC3. In the field properties panel, set the document dropdown to doc1, set the XPath to /docroot/things.

3. Create a resource field for the copy output: in the Resource Fields panel, click the add icon and add field TGT3. In the field properties panel, set the document dropdown to doc2, set the XPath to /root/level1/level2/things.

4. Create a new copy adapter: click the add icon at the top of the tree panel and create a new adapter named copy3, select Copy Adapter from the dropdown list. Set the source field to SRC3 and the destination field to TGT3.

5. The copy adapter is now ready to be used. In a form, call the copy adapter with the call statement e.g.

FPL:

API based language (Javascript):

call XMLEXAMPLE 'copy3';

resources.XMLEXAMPLE.call("copy3");

6. To see the result of the copy, add a log adapter log1 to log the contents of document doc2, and call this after the copy with statement:

FPL:

API based language (Javascript):

call XMLEXAMPLE 'log1';

resources.XMLEXAMPLE.call("log1");

You should see the following logged to the execution log (View --> Execution Log):

15:15:13.505 Debug: <root>

<thing>

b1

</thing>

<thing>

b2

</thing>

</things>

</level2>

</level1>

</root>