Service Description
A Service Description provides a specific interface to a Service Transport. The Service Description describes the inputs and outputs when you configure services within the Domino Leap mapping user interface.
Elements of a Service Description
A Service Description is represented as an XML document that follows an XML schema. This single XML document contains all the information for a single Service Description: name, description, input and output parameters, and input and output mapping. For a full listing of the XML schema, refer to Appendix A - Service Description schema. The top-level element in a Service Description is the serviceDescription element. This element, and all of its childs, must be in the XML namespace with a URI of http://www.ibm.com/xmlns/prod/forms/services/serviceDescription/1.0.
- ID
- Each Service Description must contain a unique id that identifies it to the
Domino Leap server. The id can contain any characters
that are valid as a component of a URL path. These characters include:
- Alphabetical letters – [A-Z], and [a-z]
- Numerals – [0-9]
- Hyphens – [-]
- Underscore – [_]
- Transport ID
- A Service Description must reference a Service Transport to perform its underlying operation. Each Service Transport has its own unique transportId that uniquely identifies it to the Domino Leap server. The ID for a Service Transport must be made available by its developer.
- Name and Description
- To help users build Domino Leap applications with services, each Service Description contains both a name, and a description.The name and description elements allow you to localize a Domino Leap Service Description in multiple languages using duplicate elements, each with a different xml:lang attribute and contents. See Localizing Service Descriptions for information about how to provide names and descriptions in multiple languages.
- Default Locale
- If the Service Description is not localized in the language of a particular user, the defaultLocale contains the locale in which the name and description must be presented. For example, if a user asks for the Service Description in French, but the Service Description has only English and Spanish strings, the English is returned if en is set as the defaultLocale.
- Credentials
- The credentials contains the configuration
for a Credentials Provider. The ID of the credentials provider is
specified in the providerId attribute. The credentials element
can contain zero or more property elements to
configure the properties of the specified Credentials Provider. Each property element
must contain a name attribute whose value is
the name of the property being configured, and a value attribute
that contains the value of the property.
Not all Credentials Providers are applicable to all Service Transports. Therefore, the documentation for each Service Transport must be consulted before you configure the credentials element. If the configured Service Transport does not understand the provider that is specified by providerId, the Service Description is not available.
- Bindings
- Every Service Description must specify its input and output structures. These structures outline
the ID, name, description, and type of each parameter and any subparameters.
In addition to the parameter structure, bindings might also contain a
section that declares how data going into the Service Transport is mapped
from the input structure and how data coming from the Service Transport is
mapped to the output structure.
There are two top-level elements for bindings: inbound, and outbound. Inbound defines the binding for data coming into the Service Description from the Builder Application. Outbound defines the data going to the Domino Leap application from the Service Description. Only one of each of these elements can be present within a single Service Description, and each must be placed as a child of the serviceDescription element.
Directly underneath inbound and outbound are two elements that define the main components of a binding: parameters and serviceMapping. The parameters element contains all the information that is related to the parameters. The contents of the serviceMapping element instructs Domino Leap how to map data coming from the parameters into data for the transport and vice versa.
- Parameters
- The parameters element contains zero or more parameter
elements. Each parameter element defines a single
parameter coming into or being returned from the Service Description. Each
parameter element must have an
id, type,
name, and description. The
id element uniquely identifies the parameter within
the binding. The type element specifies the type of
data that is expected to be contained within the parameter. The following
data types are supported: STRING,
BOOLEAN, DECIMAL,
FLOAT, DOUBLE,
INTEGER, DATETIME,
TIME, DATE, and
LIST.
As with the name and description child elements of the serviceDescription element, these childs of parameter specify the name and description of the parameter that is used in HCL Domino Leap. These elements can also be localized using the xml:lang attribute.
Optionally, the mandatory element can be included for inbound bindings to specify whether the parameter must be bound before starting the Service Description. Valid values for this element are true and false, with the latter being the default.
Each parameter element can have a child element that is called parameters which is a container for child parameters. The contents of the parameters element is one or more parameter elements. If a parameter contains subparameters, its type is set to LIST. At run time, the parameter contains a list of structures with each of the subparameters.
- Service Mapping
- The serviceMapping element contains all the information that is needed for the Domino Leap Builder Server server to map data between the Service Description parameters, and the Service Transport. For more information, see Mapping Data for a Service Description.
XML Namespaces
XML namespace declarations must be defined on the serviceMapping element or higher.
Sample Service Descriptions
Each example in this section includes a list of the Service Descriptions and a discussion of how each Service Description operates. The Service Descriptions in this section rely solely on the Service Transports that are shipped with the Domino Leap Builder Server server. Where applicable, sample and setup instructions are included.
- Example 1: Simple Mapping
- The following Service Description uses the HTTP Service Transport to make a request to a web
server and return the content type of the response. In this example, the URL to which the
request is made comes as an inbound parameter from the Builder
application.
<?xml version="1.0" encoding="UTF-8"?> <serviceDescription> <id>get-content-type</id> <defaultLocale>en-us</defaultLocale> <transportId>HTTPServiceTransport</transportId> <name xml:lang="en-us">Get Content Type</name> <description xml:lang="en-us"> Retrieves the content type of the response from an HTTP server for the configured URL. </description> <inbound> <parameters> <parameter> <id>request-url</id> <type>STRING</type> <name xml:lang="en-us">URL</name> <description xml:lang="en-us">URL to request.</description> <mandatory>true</mandatory> </parameter> </parameters> </inbound> <outbound> <parameters> <parameter> <id>response-header-content-type</id> <type>STRING</type> <name xml:lang="en-us">Content Type</name> <description xml:lang="en-us">Content Type of the response.</description> </parameter> </parameters> </outbound> </serviceDescription>
- Example 2: Augmenting Parameters with Constants
- The following Service Description returns the same information as Example 1. However, in this
case, we do not want the Domino Leap application to supply the URL. Instead,
the URL is declared using a constant, and mapped into the inbound parameters
for the Service
Transport.
<?xml version="1.0" encoding="UTF-8"?> <serviceDescription> <id>get-content-type-with-constant</id> <defaultLocale>en-us</defaultLocale> <transportId>HTTPServiceTransport</transportId> <name xml:lang="en-us">Get Content Type with Constant</name> <description xml:lang="en-us"> Retreives the content type of the response from an HTTP server. </description> <inbound> <serviceMapping> <constants> <constant> <id>url-to-request</id> <value>http://www.ibm.com</value> </constant> </constants> <mapping> <mapping source="constant:url-to-request" sourceType="string" target="transport:request-url" targetType="string"/> </mapping> </serviceMapping> </inbound> <outbound> <parameters> <parameter> <id>response-header-content-type</id> <type>STRING</type> <name xml:lang="en-us">Content Type</name> <description xml:lang="en-us">Content Type of the response.</description> </parameter> </parameters> </outbound> </serviceDescription>
- Example 3: Lists of Data
- The following Service Description demonstrates the use of nested parameters. This example is the
same as the Service Description used for the Countries by Region service
that is shipped with Domino Leap Builder Server. This example describes how
to specify a region and return a list of the names of countries within that
region.
<?xml version="1.0" encoding="UTF-8"?> <serviceDescription> <id>countries-by-region</id> <defaultLocale>en-us</defaultLocale> <transportId>4647b8cf-093f-11e0-89dd-001e4cf83606</transportId> <name xml:lang="en-us"> Countries by Region using Service Description </name> <description xml:lang="en-us"> Given a region, return a list of country information in that region. </description> <inbound> <parameters> <parameter> <id>region</id> <type>STRING</type> <name xml:lang="en-us">Region</name> <description xml:lang="en-us"> One of "Africa", "America, North", "America, South", "Asia", "Europe", or "Oceania" </description> <mandatory>true</mandatory> </parameter> </parameters> </inbound> <outbound> <parameters> <parameter> <id>countries</id> <type>LIST</type> <name xml:lang="en-us">Countries"</name> <description xml:lang="en-us">List of country information</description> <parameters> <parameter> <id>name</id> <type>STRING</type> <name xml:lang="en-us">Name</name> <description xml:lang="en-us">Name of Country</description> </parameter> </parameters> </parameter> </parameters> </outbound> </serviceDescription>
- Example 4: Mapping XML into Parameters
- The following Service Description extracts data from an XML document that is returned from an
HTTP request using the HTTP Service
Transport.
<?xml version="1.0" encoding="UTF-8"?> <serviceDescription> <id>address-lookup</id> <defaultLocale>en-us</defaultLocale> <transportId>HTTPServiceTransport</transportId> <name xml:lang="en-us">Address Lookup</name> <description xml:lang="en-us">Returns information related to a postal code or address.</description> <inbound> <parameters> <parameter> <id>address</id> <type>STRING</type> <name xml:lang="en-us">Address or Postal Code</name> <description xml:lang="en-us"></description> <mandatory>true</mandatory> </parameter> </parameters> <serviceMapping> <constants> <constant> <id>request-url</id> <value>http://maps.googleapis.com/maps/api/geocode/xml</value> </constant> <constant> <id>false-constant</id> <value>false</value> </constant> <constant> <id>request-method</id> <value>GET</value> </constant> </constants> <mapping> <mapping target="transport:request-url" source="constant:request-url"/> <mapping target="transport:request-method" source="constant:request-method"/> <mapping target="transport:request-query-address" source="parameter:address"/> <mapping target="transport:request-query-sensor" source="constant:false-constant"/> </mapping> </serviceMapping> </inbound> <outbound> <parameters> <parameter> <id>latitude</id> <type>STRING</type> <name xml:lang="en-us">Latitude</name> <description xml:lang="en-us"></description> </parameter> <parameter> <id>longitude</id> <type>STRING</type> <name xml:lang="en-us">Longitude</name> <description xml:lang="en-us"></description> </parameter> <parameter> <id>address-information</id> <type>LIST</type> <name xml:lang="en-us">Address Information</name> <description xml:lang="en-us"></description> <parameters> <parameter> <id>long-name</id> <type>STRING</type> <name xml:lang="en-us">Long Name</name> <description xml:lang="en-us"></description> </parameter> <parameter> <id>short-name</id> <type>STRING</type> <name xml:lang="en-us">Short Name</name> <description xml:lang="en-us"></description> </parameter> <parameter> <id>type-1</id> <type>STRING</type> <name xml:lang="en-us">Type</name> <description xml:lang="en-us"></description> </parameter> <parameter> <id>type-2</id> <type>STRING</type> <name xml:lang="en-us">Type(2)</name> <description xml:lang="en-us"></description> </parameter> </parameters> </parameter> </parameters> <serviceMapping> <mapping> <mapping source="transport:response-entity" sourceRef="GeocodeResponse/result[1]/geometry/location/lat" sourceType="xml" target="parameter:latitude"/> <mapping source="transport:response-entity" sourceRef="GeocodeResponse/result[1]/geometry/location/lng" sourceType="xml" target="parameter:longitude"/> <mapping source="transport:response-entity" sourceRef="GeocodeResponse/result[1]/address_component" sourceType="xml" target="parameter:address-information"> <mapping sourceRef="long_name" target="parameter:long-name"/> <mapping sourceRef="short_name" target="parameter:short-name"/> <mapping sourceRef="type[1]" target="parameter:type-1"/> <mapping sourceRef="type[2]" target="parameter:type-2"/> </mapping> </mapping> </serviceMapping> </outbound> </serviceDescription>
Appendix A - Service Description schema
Provided is the schema definition for the service description XML file. This can be used to better understand the structure and format of the service description XML file.
<?xml version="1.0" encoding="UTF-8"?>
<schema xmlns="http://www.w3.org/2001/XMLSchema" targetNamespace="http://www.ibm.com/xmlns/prod/forms/services/serviceDescription/1.0" xmlns:tns="http://www.ibm.com/xmlns/prod/forms/services/serviceDescription/1.0" elementFormDefault="qualified">
<simpleType name="id">
<annotation>
<documentation>
Represents a unique identifier in its context. IDs must only contain characters that are
valid in a URL. To ensure that the contents are unique and only contain valid URL characters
a UUID (Universally Unique IDentified) should be
used as its contents for any global uses.
</documentation>
</annotation>
<restriction base="string"></restriction>
</simpleType>
<complexType name="localizedType">
<annotation>
<documentation>
Represents a localized string of the Service Description. This type can be used in one of two
ways, controlled by which attributes are present.
If @key is present this element is merely used as a vehicle for a bundle key that resolves
to
the localized information at runtime. Any other attributes and content are ignored. If @key
is present there should be one and only one of the element of this type. For more information
on how to use the localized service descriptions see the
class
documentation for
com.ibm.form.nitro.service.services.IServiceDescriptionBuilder.
If @key is not present this element contains the name of the service description localized to
the locale specified in the @xml:lang attribute. If @key is not
present there should be one
element of this type for each supported locale.
</documentation>
</annotation>
<simpleContent>
<extension base="string">
<attribute name="key" type="string" use="optional">
<annotation>
<documentation>
Java resource bundle key that resolves to the localized string at runtime. See the class
documentation for com.ibm.form.nitro.service.services.IServiceDescriptionBuilder for more
information.
</documentation>
</annotation>
</attribute>
</extension>
</simpleContent>
</complexType>
<element name="serviceDescription">
<annotation>
<documentation>
serviceDescription is the root element for a Service Description document. All Service
Description documents must have one and only one <serviceDescription> element.
</documentation>
</annotation>
<complexType>
<sequence>
<element name="id" type="string" maxOccurs="1" minOccurs="1">
<annotation>
<documentation>
The id that uniquely identifies the Service Description. For information regarding
its contents see the documentation of the <id> element.
</documentation>
</annotation>
</element>
<element name="transportId" type="string" maxOccurs="1" minOccurs="1">
<annotation>
<documentation>
The id that uniquely identifies the Service Transport. For information regarding
its contents see the documentation of the <id> element.
</documentation>
</annotation>
</element>
<element name="defaultLocale" type="string" maxOccurs="1" minOccurs="1">
<annotation>
<documentation>
The default locale for the service description. At runtime values in this locale
will be used if strings for a more specific locale cannot be found.
</documentation>
</annotation>
</element>
<element name="name" type="tns:localizedType" maxOccurs="unbounded" minOccurs="1">
<annotation>
<documentation>
The localized name of the service description. If this element contains @key then
there should be only one <name> element as a child of the
<serviceDescription> element. Otherwise, there should be one for each
locale.
For more information regarding this element see the documentation for
localizedType.
</documentation>
</annotation>
</element>
<element name="description" type="tns:localizedType" maxOccurs="unbounded" minOccurs="1">
<annotation>
<documentation>
The localized description of the service description. If this element contains
@key then there should be only one <description> element as a child of the
<serviceDescription> element. Otherwise, there should be one for
each
locale.
</documentation>
</annotation>
</element>
<element name="inbound" type="tns:bindingType" maxOccurs="1" minOccurs="0">
<annotation>
<documentation>
The inbound binding information for the service description. This binding
describes what data is expected to be given to the service description from a
Nitro form and how the service description will map the incoming data into the
parameters that the underlying service transport expects.
</documentation>
</annotation>
</element>
<element name="outbound" type="tns:bindingType" maxOccurs="1" minOccurs="0">
<annotation>
<documentation>
The outbound binding information for the service description. This binding
describes what data is expected to be returned to the Nitro form from the
service description and how it will map the data coming from the underlying
service transport into that format.
</documentation>
</annotation>
</element>
</sequence>
</complexType>
</element>
<complexType name="bindingType">
<annotation>
<documentation>
A binding contains all of the information about the parameters that are coming into or out
of a service description as well as how data will be mapped from the incoming data to the
transport and vice-versa.
</documentation>
</annotation>
<sequence>
<element name="parameters" type="tns:parametersType" maxOccurs="1" minOccurs="0">
<annotation>
<documentation>
Contains all of the parameter definitions for the binding.
</documentation>
</annotation>
</element>
<element name="serviceMapping" type="tns:serviceMappingType" maxOccurs="1" minOccurs="0">
<annotation>
<documentation>
Contains the service mapping information for the binding.
</documentation>
</annotation>
</element>
</sequence>
</complexType>
<complexType name="parametersType">
<sequence>
<element name="parameter" type="tns:parameterType" maxOccurs="unbounded" minOccurs="0">
<annotation>
<documentation>
A single parameter for the service description. For more information see the
documentation for the parameterType type.
</documentation>
</annotation>
</element>
</sequence>
</complexType>
<complexType name="parameterType">
<sequence>
<element name="id" type="tns:id" maxOccurs="1" minOccurs="1">
<annotation>
<documentation>
The id of the parameter. This value is local to the Service Description and therefore
does not (and should not) be a UUID. For information regarding its contents see the
documentation of the <id> element.
</documentation>
</annotation>
</element>
<element name="name" type="tns:localizedType" maxOccurs="unbounded" minOccurs="1">
<annotation>
<documentation>
The localized name of the Service Parameter. If this element contains @key then there
should be only one <name> element as a child of the <parameter> element.
Otherwise, there should be one for each locale. For more
information regarding this
element see the documentation for localizedType.
</documentation>
</annotation>
</element>
<element name="description" type="tns:localizedType" maxOccurs="unbounded" minOccurs="1">
<annotation>
<documentation>
The localized description of the Service Parameter. If this element contains @key
then there should be only one <name> element as a child of the <parameter>
element. Otherwise, there should be one for each locale. For
more information
regarding this element see the documentation for localizedType.
</documentation>
</annotation>
</element>
<element name="mandatory" type="boolean" maxOccurs="1" minOccurs="1">
<annotation>
<documentation>
Determines if the parameter is mandatory. The value of this element is ignored if
<incoming> is false.
</documentation>
</annotation>
</element>
<element name="type" type="tns:typeType" maxOccurs="1" minOccurs="1">
<annotation>
<documentation>
Determines the type of the data that should be mapped to the parameter. For more
information see the documentation for the typeType type.
</documentation>
</annotation>
</element>
<element name="advanced" type="boolean" maxOccurs="1" minOccurs="0">
<annotation>
<documentation>
If provided, determines if the parameter is presented as 'Advanced',
otherwise assumed false.
</documentation>
</annotation>
</element>
</sequence>
</complexType>
<simpleType name="typeType">
<annotation>
<documentation>
Defines the different data types that are supported.
</documentation>
</annotation>
<restriction base="string">
<enumeration value="STRING"></enumeration>
<enumeration value="BOOLEAN"></enumeration>
<enumeration value="DECIMAL"></enumeration>
<enumeration value="INTEGER"></enumeration>
<enumeration value="FLOAT"></enumeration>
<enumeration value="DOUBLE"></enumeration>
<enumeration value="DURATION"></enumeration>
<enumeration value="DATETIME"></enumeration>
<enumeration value="TIME"></enumeration>
<enumeration value="DATE"></enumeration>
<enumeration value="LIST"></enumeration>
</restriction>
</simpleType>
<complexType name="serviceMappingType">
<annotation>
<documentation>
Defines the mapping for a binding. For more information see the mapping documentation.
</documentation>
</annotation>
<sequence>
<element name="constants" type="tns:constantsType" maxOccurs="1" minOccurs="0">
<annotation>
<documentation>
Contains <constant> elements that define any constant values that can be
injected into output of the mapping via a mapping element.
</documentation>
</annotation>
</element>
<element name="mapping" type="tns:topLevelMappingType" maxOccurs="1" minOccurs="0">
<annotation>
<documentation>
Top level mapping element that contains all of the mapping elements for the binding.
</documentation>
</annotation>
</element>
</sequence>
</complexType>
<complexType name="constantsType">
<sequence>
<element name="constant" type="tns:constantType" maxOccurs="unbounded" minOccurs="0">
<annotation>
<documentation>
Defines a constant value for a service mapping.
</documentation>
</annotation>
</element>
</sequence>
</complexType>
<complexType name="constantType">
<annotation>
<documentation>
Defines a constant value for a service mapping.
</documentation>
</annotation>
<sequence>
<element name="id" type="string">
<annotation>
<documentation>
The unique identifier of the constant. This should be a short descriptive string.
</documentation>
</annotation>
</element>
<element name="value" type="string">
<annotation>
<documentation>
The value of the constant. The textual content of this element will be used as the
value for the constant. If you need to have XML as a value that can be injected into
a parameter you must either escape the XML within this element
or wrap the contents in
a CDATA section.
</documentation>
</annotation>
</element>
</sequence>
</complexType>
<complexType name="mappingType">
<annotation>
<documentation>
Defines a mapping from a source to a target. Data will be taken from the source at the
reference specified (if applicable) and applied to the target at the reference specified (if
applicable). Any type conversions will be applied as
needed.
</documentation>
</annotation>
<sequence>
<element name="mapping" type="tns:mappingType" maxOccurs="unbounded" minOccurs="0">
<annotation>
<documentation>
</documentation>
</annotation>
</element>
</sequence>
<attribute name="source" type="tns:mappingSchemeType">
<annotation>
<documentation>
Defines the scheme of the source (where to get the data for the mapping from). The
source scheme must be either 'constant' or 'parameter'.
</documentation>
</annotation>
</attribute>
<attribute name="sourceRef" type="string">
<annotation>
<documentation>
Defines the reference to retrieve data from within the value found by the source
attribute. References take the form of a path reference.
</documentation>
</annotation>
</attribute>
<attribute name="sourceType" type="tns:mappingTypeType">
<annotation>
<documentation>
Defines the type of the source value.
</documentation>
</annotation>
</attribute>
<attribute name="target" type="tns:mappingSchemeType">
<annotation>
<documentation>
Defines the scheme of the target (where to get the data for the mapping from). The
source scheme must be 'out'.
</documentation>
</annotation>
</attribute>
<attribute name="targetRef" type="string">
<annotation>
<documentation>
Defines the reference to retrieve data from within the value found by the target
attribute. References take the form of a path reference.
</documentation>
</annotation>
</attribute>
<attribute name="targetType" type="tns:mappingTypeType">
<annotation>
<documentation>
Defines the type of the target value.
</documentation>
</annotation>
</attribute>
</complexType>
<complexType name="topLevelMappingType">
<annotation>
<documentation>
The top level mapping element contains mapping elements.
</documentation>
</annotation>
<sequence>
<element name="mapping" type="tns:mappingType" maxOccurs="unbounded" minOccurs="0"></element>
</sequence>
</complexType>
<simpleType name="mappingTypeType">
<restriction base="string">
<enumeration value="xml"></enumeration>
<enumeration value="string"></enumeration>
</restriction>
</simpleType>
<simpleType name="mappingSchemeType">
<restriction base="string">
<pattern value="^parameter:.*"></pattern>
<pattern value="^out:.*"></pattern>
<pattern value="^constant:.*"></pattern>
</restriction>
</simpleType>
</schema>