Copy Adapter Examples
Copying
from a field to a document
Copying
from a document to a field
Copying
from one document to another document
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.
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><b>b1</b></thing><thing> <a>a2</a><b>b2</b></thing></things></docroot>';
update XMLEXAMPLE; call XMLEXAMPLE
'copy1'; |
fields.SRC1.value
= "<docroot><things><thing><a>a1</a><b>b1</b></thing> <thing><a>a2</a><b>b2</b></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.
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.
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(); |
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.
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>
<level1>
<level2>
<things>
<things>
<thing>
<a>a1</a>
<b>b1</b>
</thing>
<thing>
<a>a2</a>
<b>b2</b>
</thing>
</things>
</things>
</level2>
</level1>
</root>