WSDL is often used in the context of Web Services, in order to define interfaces implemented by a Web Service. Usually, a SOAP binding is used to specify the concrete realization of the interface by a Web Service which supports the SOAP protocol. The WSDL syntax used in files created by the Property Broker Editor in Domino Designer is similar to the one supported in WebSphere Portal.

Note For more complete information on the use of WSDL files in Portal, refer to the WebSphere Portal documentation.

To store a copy of the WSDL file within the NSF-based composite application, open the application in IBM® Lotus® Domino(TM) Designer and navigate to Composite Applications-Wiring Properties in the design pane. Use the Import WSDL button to select the WSDL file from disk and create a "Wiring Properties" design element. This design element can be stored and inherited from templates, or protected from template refresh, just like any other type of Notes design element.

You can also create your own WSDL files "from scratch" by using the Property Broker Editor. Refer to "Using the Property Broker Editor in Domino Designer" for more information.

The following sections of this topic provide more information on the syntax of the WSDL files used in Domino Designer and WebSphere Portal. Specifically, this example shows how Click-to-Action between portlets uses some of the elements in the WSDL document. The extensions to the <binding> element are described and the complete schema for WSDL Extensions is provided.

WSDL syntax

The following provides specific information on the syntax used in WSDL files by Domino Designer and WebSphere Portal.

<types>

For composite application components, this declares the data type of the data to be transferred. The data type is declared using XML Schema Datatypes (XSD, see the XSD specification). There may be multiple types defined in the WSDL document. The following shows a sample declaration for an example data type called TrackingIDType:

<types>

     <xsd:simpleType name="TrackingIDType">

        <xsd:restriction base="xsd:string">

        </xsd:restriction>

      </xsd:simpleType>

</types>

<message>

Input messages can contain only one part.

<operation>

Provides an abstract definition of a Click-to-Action operation. Note the restriction on input messages above.

<portType>

Defines an abstract collection of operations. The operations must be defined in the document. One operation corresponds to each action on the Click-to-Action enabled portlet. Only actions that are to be enabled for Click-to-Action should be declared.

<binding>

The binding element is extended to associate portlet actions with operations. For each operation, the portlet action name must be provided. The portlet action name may be specified using the name attribute of the action tag in the binding section of the WSDL file. If it is omitted, the name attribute from the operation tag is used as the portlet action name. For each operation parameter, the action parameter name must be provided. The portlet parameter name may be specified using the name attribute of the param tag in the binding section of the WSDL file. If it is omitted, the name attribute of the part tag associated with the param tag is used as the portlet parameter name.

Further, the boundTo attribute may be used to specify where the parameter will be bound. Choices are request-parameter, request-attribute, session-attribute, or action-attribute.

The <binding> element includes cooperative portlet extensions, which are described in Extensions to the <binding> element. shown in the WSDL Example.

If you are familiar with WSDL, you might notice that the service section (enclosed by the <service> element in WSDL) is not used in the example declaration file. This is because the file is associated with a specific portlet implementing the operations defined in the file through external means (an entry in the portlet.xml file associated with the portlet).

Extensions to the <binding> element

The <binding> element has been extended to support cooperative components and portlets. The examples below refer to usage with portlets.

Each extension element is prefixed with "portlet:", which refers to the C2A (Click-to-Action) namespace, http://www.ibm.com/wps/c2a. The "portlet:" prefix is used to identify the extension elements in this section, but a different name may be used for the prefix as long as it refers to the C2A namespace. The elements are described below. Refer also to WSDL Extension Schema information provided further in this topic.

<portlet:binding>

This must be the first child element of the WSDL <binding> element. Its presence identifies the section as a C2A binding extension for portlet action invocation. The element has the following attribute.

• style

  Deprecated. Specifying style="struts" indicates that Struts actions are being declared. Instead, you should use type=struts on the <portlet:action> element for this purpose.

This must be the first child element of any WSDL <operation> element in the binding section. It contains the following attributes:

• name

  the portlet action name. If this is omitted, the name of the associated operation element is used as the portlet action name.

• caption

  a short string about the action suitable for displaying in the portlet user interface. For translated captions, indicate in dotted format the name of the key in the resource bundles from which the caption is to be obtained. See Internationalization support for more information.

• type

  Indicates one of the following values:

  • default -- indicates a DefaultPortletAction object is used. This object is deprecated but still supportedfor migration purposes.
  • simple -- indicates a simple portlet action String is used.
  • struts -- indicates a Struts action is used.
• description

  a text description of the action. For translated descriptions, indicate in dotted format the name of the key in the resource bundles from which the description is to be obtained.

• activeOnStartup

  Indicate either "true" or "false". If false, the action must be programmatically activated in each session. If true (default), the action is active as soon as the portlet is initialized.

• selectOnMultipleMatch

  In the case that multiple actions match based on the data type for the portlet, this attribute can be used to indicate which action to trigger. Multiple matching actions can occur when a user broadcasts an action on a source. If not specified, the default is false. In the case where no single action is set to true, the data is not delivered to the target. In the following example, There are two actions declared: trackingDetails and routingDetails. selectOnMultipleMatch is used to indicate that the trackingDetails should be used in the case of a multiple match.

      <portlet:binding/>

      <operation name="trackingDetails">

        <portlet:action caption="Tracking Details"

               description="Get tracking details for

               specifiedtracking id"

               selectOnMultipleMatch="true"/>

        <input>

          <portlet:param name="trackingId" partname="trackingId"/>

        </input>

        <output>

          <portlet:param name="customerName" partname="custName" boundTo="session"/>

        </output>

      </operation>

      <operation name="routingDetails">

        <portlet:action caption="Routing Details"

                        description="Get routing details for specified tracking id"/>

        <input>

          <portlet:param name="trackingId" partname="trackingId"/>

        </input>

      </operation>

</binding>

<portlet:param>

This must appear as a child element in the <input> or <output> subelements of the <operation> element in the binding. It specifies the parameters consumed (if enclosed in the <input> element) or produced (if enclosed in the <output> element) by the portlet action. At present, we restrict the number of parameters consumed to at most one. The number of parameters produced can be any number. It has the following attributes:

• name

  the name of the parameter. If omitted, the name attribute value of the part element is used as the parameter name.

• partname

  refers to a part element of the input or output for the operation. It may be omitted if the input or output has a single part.

• boundTo

  specifies where the parameter value is bound. Currently, this attribute can specify one of the following values only:

  • request-parameter -- This specifies that the value is bound as a parameter in the PortletRequest object. This is the default value if the boundTo attribute is omitted. Note that for output parameters, a different value should usually be specified as the default PortletRequest implementation provided by WebSphere Portal does not allow parameters to be set during action processing.
  • request-attribute : This specifies that the value is bound as an attribute in the PortletRequest object.
  • session -- This specifies that the value is bound to the PortletSession object.
  • action -- This specifies that the value is bound to a portlet action.

The following is the schema for the extensibility elements introduced for the portlet action invocation using Click-to-Action. Lines have been broken to allow viewing on the printed page.

<?xml version="1.0" encoding="UTF-8" ?>

<xsd:schema xmlns="http://www.w3.org/2001/XMLSchema"

     xmlns:xsd="http://www.w3.org/2001/XMLSchema

targetNamespace="http://www.ibm.com/wps/c2a"

xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="http://schemas.xmlsoap.org/wsdl/

    http://schemas.xmlsoap.org/wsdl/

    http://www.w3.org/2001/XMLSchema

    http://www.w3.org/2001/XMLSchema.xsd"

xmlns:portlet="http://www.ibm.com/wps/c2a">

   <!-- The binding element indicates that the binding section contains         custom extensions describing a mapping of operations to portlet
  actions.  This must be placed within a WSDL binding element. -->

   <element name="binding" type="portlet:bindingType"/>

   <complexType name="bindingType">

    <!-- DEPRECATED, retained for compatibility with version 4. Use the type
   attribute with the action element instead.  Set value to be "struts"
   for a portlet implemented using the struts framework. -->

      <attribute name="style" type="string" use="optional"/>

   </complexType>

   <!-- The action element is used to provide all the information about the
  portlet action necessary for the property broker to invoke it. This must
  be placed within an wsdl:operation element in the wsdl:binding
  section. -->

   <complexType name="actionType">

       <sequence>

       <!-- The param element is used to indicate information about the
      input or output property associated with the action and the
      mechanism for passing parameters to or from the action.
      It must be placed within a wsdl:input or wsdl:output element. -->

          <element name="param" type="portlet:paramType"
             minOccurs="0"maxOccurs="unbounded"/>

</sequence>

         <!-- The name of the action. Will be set as the portlet action
        name. If omitted, the name of the corresponding operation
        element will be used as the action name. -->

<attribute name="name" type="string" use="optional"/>

     <!-- default, simple, and struts are currently recognized values
    with default being the default. Is used to specify whether the
    DefaultPortletAction, simple portlet action, or struts action
    mechanism is used to invoke the portlet action. Note that the
    use of DefaultPortletAction is deprecated, and the default is
    set to this value for backwards compatibility.  We encourage setting
    this to simple to avoid future migration issues. -->

     <attribute name="type" type="string" use="optional" default="default"/>

     <!-- A short name for  the action which is displayed to the end-user.
    If a message resource file is provided for the portlet,
    the value is used as a key to retrieve a translated string -->

     <attribute name="caption" type="string" use="optional"/>

     <!-- A description for  the action which is displayed to the end-user.       If a message resource file is provided for the portlet, the value
    is used as a key to retrieve a translated string -->

     <attribute name="description" type="string" use="optional"/>

     <!-- If more than one portlet action can simultaneously process a
    property value, only those with the invokeOnMultipleMatch attribute
    set to true will be invoked -->

      <attribute name="selectOnMultipleMatch" type="boolean"
          use="optional" default="false"/>

      <!-- If the activeOnStartup attribute is true, the action
      may be selected for invocation at any time unless programmatically
      deactivated on a per-session basis.  If the activeOnStartup is
      false, the action may not be selected for invocation,unless
       programmatically activated on a per-session basis -->

       <attribute name="activeOnStartup" type="boolean"
            use="optional" default="true"/>

       <!-- The param element indicates how the parameter is
      to be delivered to the portlet action or retrieved
      from it once the action has executed -->

    </complexType>

    <complexType name="paramType">

        <!-- The name of the parameter which will be used on
        action invocation. If omitted, the partname is used.
        This name will also be set as the name of the corresponding
        property.  See a description of properties in the programming
        model document. -->

        <attribute name="name" type="string" use="optional"/>

        <!-- The name of the corresponding part. May be omitted
       only if there is a single parameter for the action, in
       which case it will be inferred from the associated
       operation definition -->

        <attribute name="partname" type="string" use="optional"/>

        <!-- Where to place the parameter prior to invoking
       the action (in case of in parameters), or where
       to look for it after invoking the action (in case of out
       parameters).request-attribute, request-parameter, session,
       and action are allowed values. -->

        <attribute name="boundTo" type="string"
                    default="request-parameter"/>

        <!-- The java class for the parameter. The default is
       java.lang.String. Currently this is not used, but may be used
       in future for validation -->

       <attribute name="class" type="string" default="java.lang.String"/>

       <!-- A short name for the parameter which is displayed
      to the end-user. If a message resource file is provided
      for the portlet, the value is used as a key to retrieve
      a translated string -->

       <attribute name="caption" type="string" use="optional"/>

       <!-- A description for the parameter which is displayed to the
      end-user. If a message resource file is provided for the portlet,
      the value is used as a key to retrieve a translated string -->

       <attribute name="description" type="string" use="optional"/>

    </complexType>

</xsd:schema>

You can use existing WSDL files as a starting point when building NSF components and Eclipse components. It is recommended, however, that you use the Property Broker Editor when working with them.

WSDL sample for composite applications in Domino Designer

Use this sample syntax and the annotation (in bold) for reference as you create your own sample composite application using Lotus Notes.

<?xml version="1.0" encoding="UTF-8" ?>

<definitions name="Property Broker WSDL"

targetNamespace="http://www.ibm.com/wps/c2a/testwsdl"

xmlns="http://schemas.xmlsoap.org/wsdl/"

xmlns:portlet="http://www.ibm.com/wps/c2a"

xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"

xmlns:tns="http://www.ibm.com/wps/c2a/testwsdl"

xmlns:cus="com.ibm.compositeapps.samples" -this is how you
can add your own sample namespace (1)

xmlns:cut="com.ibm.compositeapps.samples.2" -this is
another sample namespace (2)

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<types>

<xsd:schema targetNamespace="com.ibm.compositeapps.samples">
-this is a custom namespace (1)

<xsd:simpleType name="SubjectType"> -this is the typename

<xsd:restriction base="xsd:string"/>

</xsd:simpleType>

</xsd:schema>

<xsd:schema targetNamespace="com.ibm.compositeapps.samples.2">
this shows another namespace (2)

<xsd:simpleType name="AccountType">

<xsd:restriction base="xsd:string"/>

</xsd:simpleType>

<xsd:simpleType name="IDType">

<xsd:restriction base="xsd:string"/>

</xsd:simpleType>

<xsd:simpleType name="CustomerType">

<xsd:restriction base="xsd:string"/>

</xsd:simpleType>

</xsd:schema>

</types>

<message name="New_Response_Action_Operation_Input">

<part name="SubjectPart" type="cus:SubjectType"/> -note
the "cus" points to your namespace (1) -- this maps from
the property to the type

</message>

<message name="New_Response_Action_Operation_Output">

<part name="AccountPart" type="cut:AccountType"/> -note
the "cut "to point to your namespace (1)

<part name="IDPart" type="cut:IDType"/>

</message>

<message name="OnViewEntrySelectionChange_Property_Operation_Output">

<part name="CustomerPart" type="cut:CustomerType"/>

</message>

<portType name="NotesDB_Operations"> - this section is required as part of the WSDL standard

<operation name="New_Response_Action_Operation">

<input message="tns:New_Response_Action_Operation_Input"/>

<output message="tns:New_Response_Action_Operation_Output"/>

</operation>

<operation name="OnViewEntrySelectionChange_Property_Operation">

<output message="tns:OnViewEntrySelectionChange_Property_Operation_Output"/>

</operation>

</portType>

<binding name="Notes_Binding" type="tns:NotesDB_Operations">

<portlet:binding/>

<operation name="New_Response_Action_Operation"> -this is
an action with one input and two output properties. See the note below.

<portlet:action name="New Response Action"
caption="NewResponseCaption" -this name is the name that shows up in Domino Designer user interface in action infobox
 description="NewResponseDesc.id"/>

<input>

<portlet:param name="Subject" -this name is
the property name and it must be unique within one wsdl file
partname="SubjectPart" -partname is used to
map to the "part name=" under <message> caption="subjectCaption"
description="subjectDesc.id"/>

</input>

<output> -you can have 0-N output properties in an action

<portlet:param name="Account" partname="AccountPart" caption="accountCaption" description="accountDesc.id"/>

<portlet:param name="ID" partname="IDPart" caption="id" description="idDesc.id"/>

</output>

</operation>

<operation name="OnViewEntrySelectionChange_Property_Operation"> -this is an output property

<portlet:action name="OnDocSelectionChange"
-this name doesn't matter, but must be unique within one wsdl file
caption="DocSelectionCaption" description="DocSelectionDesc.id"/>

<output>

<portlet:param name="Customer" partname="CustomerPart" caption="customer" description="customer.id"/>

</output>

</operation>

</binding>

</definitions>

Guidelines for WSDL files

Use the following guidelines when creating your WSDL files:

• Overall syntax -- The WSDL syntax used for composite applications is similar to the one supported in WebSphere Portal. For more complete information on the use of WSDL files in WebSphere Portal, refer to the Portal documentation.
• Namespaces -- It is recommended that you define what namespace(s) you are going to use for your own development. If you have many divisions in your company, you might choose one for each division. However, you may want to interrelate components between divisions, or with 3rd party components, or with some of the reusable components from the provided samples. In these cases the data types will come from different namespaces.

• String type -- For this release, only the string type is currently supported and the type name is the only means provided for establishing a type you can use to relate components.

Using the Property Broker Editor feature in Domino Designer
Using data types in composite applications
Working with composite applications in Domino Designer
Working with the Applications design element in Domino Designer
Working with the Wiring Properties design element in Domino Designer

Glossary