Parameters that the generic XML data sink supports | HCL Digital Experience
The generic XML Digital Data Connector (DDC) for HCL Portal data sink supports the parameters that are listed here.
- ddc.method
- Use this parameter to identify the HTTP method that you want to be used for sending
the data to the outbound target. Supported values are
put
,post
, anddelete
. - ddc.uri.target
- Use this parameter to specify a URI that identifies the target of the outbound request. The target can be an HTTP or HTTPs URL, for example, to a remote REST service.
- ddc.uri.template
- Use this parameter to specify a URI that identifies the template XML document that
is required for
set
,addChild
,addPredecessor
, andaddSuccessor
actions. This document is the starting point for creating the final XML document that is sent to the target service. You can modify the template for starting a specific operation by using form post parameters. The URI used in this parameter needs to identify a well-formed XML document. - ddc.profile.in
- Use this parameter to define the name of the list-rendering profile that you want to apply to the template XML document. You can use the item attribute definitions and corresponding XPath statements of this profile to modify specific fragments of the template XML document. This modification is done before the resulting XML document is sent to the target service.
- ddc.profile.out
- Use this parameter to define the name of the list-rendering profile that you want to
apply to the data returned by the target service. You can use the item attribute
definitions and corresponding XPath statements of this profile to extract specific XML
fragments of XML documents that are served in response to the update operation. If you
do not set this parameter, the data sink uses the same profile as the one that the
ddc.profile.in
parameter references. - ddc.itemattribute.value.suffix
- Use this parameter to specify the value that you want to use for modifying the
template XML document that is required for
set
,addChild
,addPredecessor
, andaddSuccessor
actions. The value can come from user input or can be specified through hidden form input field that is filled by HCL Web Content Manager tags. For example, such a tag can be the[AttributeResource]
tag.Depending on the value of thevalueType
definition of the related operation, specify one of the following values:- A URI that identifies the item attribute value for the operation. This URI must be a URI that the POC resolver framework can resolve.
- Plain text that represents the item attribute value for the operation.
suffix
value does not imply any semantics. Use it to correlate this attribute value specification with an item attribute operation specification. Both specifications must be represented by addc.itemattribute.value.suffix
andddc.itemattribute.operation.suffix
parameter, respectively. For example, the following attribute value specification is correlated with the following item attribute operation specification by using the common suffixxyz
:addc.itemattribute.value.xyz
andddc.itemattribute.operation.xyz
. - ddc.itemattribute.template.suffix
- Use this parameter to specify an optional item attribute value template. The generic
XML DDC data sink data sink replaces all occurrences of the
${value}
string in the template with the value of the relatedddc.itemattribute.value.suffix
parameter. This step creates the final value to use for modifying the template XML document that is used forset
,addChild
,addPredecessor
, andaddSuccessor
actions.If the related
ddc.itemattribute.value.suffix
defines more than one value by using a separator specified by thevalueSeparator
parameter, the generic data sink applies each individual value to the template.Depending on the value of thetemplateType
definition of the related operation, specify one of the following values:- A URI that identifies the item attribute value template for the operation. This URI must be a URI that the POC resolver framework can resolve.
- Plain text that represents the template for the operation.
suffix
value does not imply any semantics. Use it to correlate this attribute value with a corresponding item attribute value specification and item attribute operation specification. Both specifications must be represented by addc.itemattribute.value.suffix
andddc.itemattribute.operation.suffix
parameter, respectively. For example, the following attribute value specification is correlated with the following item attribute operation specification by using the common suffixxyz
:addc.itemattribute.value.xyz
andddc.itemattribute.operation.xyz
. - ddc.itemattribute.operation.suffix
- Use this parameter to specify a modification of the template document. The value for
this parameter is comma-separated list of name-value pairs. You can specify the
following keys:
- action
- Use this key to identify the action that you want to be completed on the
template document. The data sink completes the following actions on the template
XML document. The node selection is based on the
itemAttribtueName
value and the list-rendering profile that is attached through theddc.profile.in
parameter. You can specify the following values:- set
- Use this value to modify the node selected by the
itemAttributeName
value. - addChild
- Use this value to add a child node selected by the
itemAttributeName
value. - addPredecessor
- Use this value to add a predecessor sibling to the node selected by the
itemAttributeName
value. - addSuccessor
- Use this value to add a successor sibling to the node selected by the
itemAttributeName
value. - remove
- Use this value to remove the selected node.
get
action is not performed on the template document, but on the resulting XML document that the addressed service returns. If you use this action, the node selection is based on theitemAttribtueName
value and the list-rendering profile that is attached through theddc.profile.out
parameter.- get
- Use this value to add a corresponding entry to the result JSON object that the data sink generates. The entry holds the string value of the selected node in the result XML document.
- itemAttributeName
- Use this key to reference an individual item attribute definition in the
associated list-rendering profile. The XPath that is associated with this item
attribute definition is used to select the target node for this operation. In
this context, you can use only
ItemAttribute
definitions. The following definitions are not supported:AssociatedItemAttribute
,ComputeItemAttribute
,ConstructedItemAttributes
. - templateType
- Use this key to specify the type of the value of the
ddc.uri.template
parameter that was listed earlier. You can specify the following values:- text
- If you specify the value
text
, the value of theddc.itemattribute.template.suffix
parameter is used as a normal string that represents the item attribute template. This is the default template type. - uri
- If you specify the value
uri
, the data sink parses the value of theddc.itemattribute.template.suffix
parameter as a URI. The data sink determines the actual value by reading the data that is served from this URI. The URI needs to be a URI that the POC resolver framework can resolve.
- valueType
- Use this key to specify the type of the value of the
ddc.itemattribute.value.suffix
parameter that is related to the operation. You can specify one of the following values:- text
- If you specify the value text, the value of the
ddc.itemattribute.value.suffix
parameter is used as a normal string. This is the default value type. - uri
- If you specify the value
uri
, the data sink parses value of theddc.itemattribute.value.suffix
parameter as a URI. The data sink determines the actual value by reading the data that is served from this URI. The URI must be a URI that the POC resolver framework can resolve.
- valueSeparator
- Use this key to enable the operation to support multiple values. The generic
data sink computes the individual values by splitting the correlated parameter
value using the separator that this key specifies. If the separator consists of
multiple characters, each character is treated as a separate separator. Example:
To split an input value on all occurrences of commas (
,
) and semicolons (;
), you combine both separators in the value for this parameter as follows:;,
. The data sink completes the operation for each fragment of the separated value. Use this parameter only for the following actions:addChild
,addPredecessor
,addSuccessor
.
- ddc.state.operation.suffix
- Use this parameter to specify a modification of the portlet render state. The value
for this parameter is comma-separated list of name-value pairs. You can specify the
following keys:
- action
- Use this key to identify the action that you want to be completed on the
portlet render state. You can use the following values:
- set
- Use this value to set a private render parameter.
- add
- Use this value to add a private render parameter.
- remove
- Use this value to remove a private render parameter.
- renderParameterName
- Use this key to specify the name of the private render parameter that you want to modify.
- condition
- Use this key to specify the condition under which you want this operation to
be performed. You can use the following values:
- success
- If you specify this value, the modification to the portlet render state is performed only if the overall data sink operation succeeded.
- error
- If you specify this value, the modification to the portlet render state is performed only if the overall data sink operation resulted in an error.
- always
- If you specify this value, the modification to the portlet render state is performed independent of whether the overall data sink result succeeded or resulted in an error.
- ddc.state.value.suffix
- Use this parameter to specify the value for the state operation as described in the
corresponding
ddc.state.operation
parameter. - ddc.passback.name
- Use this parameter to specify custom pass-back parameters. The generic XML DDC data
sink does not analyze these parameters. It only adds them to the interaction result
JSON object as a
passbackData
member usingname
as an identifier. This parameter can be useful for retaining specific state information after the operation is completed, for example when you create a new resource. - ddc.resultheaders
- Use this parameter to specify the names of HTTP response header fields that you want
to be included in the result object. The HTTP response header fields refer to the
outbound call of the generic XML DDC data sink. To specify more than one header field,
use multiple
ddc.resultheaders
parameters. After processing the response from the remote REST service, the data sink adds the specified header fields from the response to the interaction result JSON object as aresultHeaderData
member. You can use this parameter to access information from the outbound call that the data sink makes.
Example: Creating a resource
Typical XML REST services support the creation of new resources by sending a corresponding
resource XML document to the service. To do so, the client typically uses an HTTP POST
request. The following HTML fragment shows an HTML form that you can use to create a comment
on a HCL Connections blog post:
<form id="[AttributeResource attributeName='id']CreateBlogPostComment"
method="POST" enctype="multipart/form-data"
action="[Plugin:ActionURL copyCurrentParams="true"
param="resultSessionAttribute=myResult" compute="always"]">
<input type="hidden" name="_charset_" value="[Plugin:EvaluateEL
value="${pageContext.response.characterEncoding}" compute="once"]"/>
<input type="hidden" name="action.uri" value="ddc:operation:blp:ibm.portal.ddc.xml"/>
<input type="hidden" name="ddc.uri.template"
value="wcmrest:LibraryHTMLComponent/[Component
name="yourLibrary/interaction
templates/create comment" format="id"]"/>
<input type="hidden" name="ddc.profile.in"
value="ibm.portal.sr.blogs.post.comments"/>
<input type="hidden" name="ddc.itemattribute.operation.addComment"
value="action=set,itemAttributeName=body"/>
<textarea title="Content" name="ddc.itemattribute.value.addComment"
placeholder=" "></textarea>
<input type="hidden" name="ddc.uri.target" value="[AttributeResource
attributeName="rawCommentsEditLink"]"/>
<input type="hidden" name="ddc.method" value="post"/>
<input type="submit" class="lotusBtn" value="Submit" name="submitButton"/>
</form>
The
form sets the action
, method
, and enctype
parameters. The form also
specifies the _charset_
and action.uri
input fields. For more information about these fields, read
Creating the HTML form. Additionally, the form specifies the following behavior:- The form sets the
action.uri
parameter to the valueddc:operation:blp:ibm.portal.ddc.xml
. As a result, the generic XML Digital Data Connector data sink processes the form. - The template document that represents the blog post comment XML entry is referenced by
using the
ddc.uri.template
parameter. In this example, the template document is served from a Web Content Manager HTML component that is referenced by a correspondingwcmrest
URI. For more information about the Web Content Manager REST URI format, read REST service for Web Content Manager in the Web Content Manager documentation. In this example, the referenced HTML component contains the following XML fragment:<?xml version='1.0' encoding='UTF-8'?> <entry xmlns='http://www.w3.org/2005/Atom' xmlns:thr="http://purl.org/syndication/thread/1.0"> <content type='html'> </content> </entry>
- The profile for this template document is identified by using the
ddc.profile.in
parameter. As the example posts a blog post comment document, the profileibm.portal.sr.blogs.post.comments
is used. - The parameters
ddc.itemattribute.operation.addComment
andddc.itemattribute.value.addComment
define the update of the<content>
element in the template document. The operation parameter is set to the valueaction=set,itemAttributeName=body
. As a result, the value that the user entered in theddc.itemattribute.value.addComment
text area is used to update the XML node that the item attribute namedbody
selected. The referenced profile holds the information about where to locate the<content>
element in the template. - To create the blog post comment, the modified template document needs to be sent to
the blog post edit link. To do so, set the
ddc.method
parameter to the valuepost
. To extract the blog post edit link from the current DDC list-rendering context, use the tag[AttributeResource attributeName="rawCommentsEditLink"]
.
Example: Deleting an existing resource
Typical XML REST services support the deletion of existing resources by sending a
corresponding an HTTP DELETE request to the resource URL. The following HTML fragment shows
an HTML form that you can use to delete a comment from an HCL Connections blog
post:
<form id="[AttributeResource attributeName="id"
separator=","]DeleteBlogComment" method="POST"
enctype="multipart/form-data" action="[Plugin:ActionURL
action="post" copyCurrentParams="true"
param="resultSessionAttribute=myResult" compute="always"]">
<input type="hidden" name="_charset_" value="[Plugin:EvaluateEL
value="${pageContext.response.characterEncoding}" compute="once"]"/>
<input type="hidden" name="action.uri"
value="ddc:operation:blp:ibm.portal.ddc.xml"/>
<input type="hidden" name="ddc.method" value="delete"/>
<input type="hidden" name="ddc.uri.target"
value="[AttributeResource attributeName="rawEditLink"
separator=","]" />
</form>
The
form specifies the following behavior:- The form sets the
uri
parameter to the valueddc:operation:blp:ibm.portal.ddc.xml
. As a result, the generic XML Digital Data Connector (DDC) for HCL Portal data sink processes the form. - To delete the resource, you do not need to send XML data to the data sink. Therefore,
the form does not specify the parameters
ddc.uri.template
orddc.profile.in
or any of theddc.itemattribute
parameters. - To delete the blog post comment, you need to send an HTTP delete request to the blog
post edit link. To do so, set the
ddc.method
parameter to the valuedelete
. To extract the blog post edit link from the current DDC list-rendering context, use the tag[AttributeResource attributeName="rawCommentsEditLink"]
.