+

Search Tips   |   Advanced Search

Parameters the generic XML data sink supports

The generic XML IBM Digital Data Connector data sink supports the parameters listed here.

    ddc.method
    HTTP method to be used for sending the data to the outbound target. Supported values are put, post, and delete.

    ddc.uri.target
    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
    URI that identifies the template XML document required for set, addChild, addPredecessor, and addSuccessor actions. This document is the starting point for creating the final XML document sent to the target service. We can modify the template for starting a specific operation using form post parameters. The URI used in this parameter needs to identify a well-formed XML document.

    ddc.profile.in
    Name of the list-rendering profile to apply to the template XML document. 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
    Name of the list-rendering profile to apply to the data returned by the target service. Use the item attribute definitions and corresponding XPath statements of this profile to extract specific XML fragments of XML documents served in response to the update operation. If we do not set this parameter, the data sink uses the same profile as the one the ddc.profile.in parameter references.

    ddc.itemattribute.value.suffix
    Value to use for modifying the template XML document required for set, addChild, addPredecessor, and addSuccessor actions. The value can come from user input or can be specified through hidden form input field that is filled by IBM WCM tags. For example, such a tag can be the [AttributeResource] tag.

    Depending on the value of the valueType 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 the POC resolver framework can resolve.

    • Plain text representing the item attribute value for the operation.

    The 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 a ddc.itemattribute.value.suffix and ddc.itemattribute.operation.suffix parameter, respectively.

    ddc.itemattribute.template.suffix
    Set 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 related ddc.itemattribute.value.suffix parameter. This step creates the final value to use for modifying the template XML document used for set, addChild, addPredecessor, and addSuccessor actions.

    If the related ddc.itemattribute.value.suffix defines more than one value using a separator specified by the valueSeparator parameter, each individual value is applied to the template.

    Depending on the value of the templateType 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 the POC resolver framework can resolve.

    • Plain text representing the template for the operation.

    The 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 a ddc.itemattribute.value.suffix and ddc.itemattribute.operation.suffix parameter, respectively.

    ddc.itemattribute.operation.suffix
    Set a modification of the template document. The value for this parameter is comma-separated list of name-value pairs. We can specify the following keys:

      action
      Use this key to identify the action 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 attached through the ddc.profile.in parameter. We 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
        Remove the selected node.

      In contrast to the previous actions, the get action is not performed on the template document, but on the resulting XML document the addressed service returns. If we use this action, the node selection is based on the itemAttribtueName value and the list-rendering profile attached through the ddc.profile.out parameter.

        get
        Use this value to add a corresponding entry to the result JSON object 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 associated with this item attribute definition is used to select the target node for this operation. In this context, 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. We can specify the following values:

        text
        If we specify the value text, the value of the ddc.itemattribute.template.suffix parameter is used as a normal string representing the item attribute template. Default template type.

        uri
        If we specify the value uri, the data sink parses the value of the ddc.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 the POC resolver framework can resolve.

      valueType
      Use this key to specify the type of the value of the ddc.itemattribute.value.suffix parameter related to the operation. We can specify one of the following values:

        text
        If we specify the value text, the value of the ddc.itemattribute.value.suffix parameter is used as a normal string. Default value type.

        uri
        If we specify the value uri, the data sink parses value of the ddc.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 the POC resolver framework can resolve.

      valueSeparator
      Use this key to enable the operation to support multiple values. The values are read from a single input parameter, which is the related ddc.itemattribute.value.suffix parameter that is split into multiple values using this separator. 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
    Set a modification of the portlet render state. The value for this parameter is comma-separated list of name-value pairs. We can specify the following keys:

      action
      Use this key to identify the action to be completed on the portlet render state. Use the following values:

        set
        Use this value to set a private render parameter.

        add
        Use this value to add a value to a private render parameter.

        remove
        Remove a private render parameter.

      renderParameterName
      Use this key to specify the name of the private render parameter to modify.

      condition
      Use this key to specify the condition under which we want this operation to be performed. Use the following values:

        success
        If we specify this value, the modification to the portlet render state is performed only if the overall data sink operation succeeded.

        error
        If we 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 we 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
    Specify the value for the state operation as described in the corresponding ddc.state.operation parameter.

    ddc.passback.name
    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 using name as an identifier. Useful for retaining specific state information after the operation is completed, for example when creating a new resource.

    ddc.resultheaders
    Names of HTTP response header fields 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 a resultHeaderData member. Use this parameter to access information from the outbound call the data sink makes.


Example: Create 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 used to create a comment on an IBM 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/[Componentname="yourLibrary/interactiontemplates/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 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 value ddc:operation:blp:ibm.portal.ddc.xml. As a result, the generic XML Digital Data Connector data sink processes the form.

  • The template document representing the blog post comment XML entry is referenced using the ddc.uri.template parameter. In this example, the template document is served from a Web Content Manager HTML component referenced by a corresponding wcmrest URI. For more information about the WCM REST URI format, read REST service for WCM in the WCM 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 using the ddc.profile.in parameter. As the example posts a blog post comment document, the profile ibm.portal.sr.blogs.post.comments is used.

  • The parameters ddc.itemattribute.operation.addComment and ddc.itemattribute.value.addComment define the update of the <content> element in the template document. The operation parameter is set to the value action=set,itemAttributeName=body. As a result, the value the user entered in the ddc.itemattribute.value.addComment text area is used to update the XML node the item attribute named body 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 value post. 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 used to delete a comment from an IBM 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 value ddc:operation:blp:ibm.portal.ddc.xml. As a result, the generic XML IBM Digital Data Connector data sink processes the form.

  • To delete the resource, we do not need to send XML data to the data sink. Therefore, the form does not specify the parameters ddc.uri.template or ddc.profile.in or any of the ddc.itemattribute parameters.

  • To delete the blog post comment, we need to send an HTTP delete request to the blog post edit link. To do so, set the ddc.method parameter to the value delete. To extract the blog post edit link from the current DDC list-rendering context, use the tag [AttributeResource attributeName="rawCommentsEditLink"].


Parent The generic XML Digital Data Connector data sink

Related concepts:

REST service for WCM
Use REST with content items

Related tasks:

Create the HTML form