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
HCL 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 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 – [_]
Because a Service Description ID is a surrogate for the Service
Description itself, this ID does not must be descriptive. Any UUID
is a valid choice for a Service Description ID because it guarantees
uniqueness and contains only characters that are valid in a URL path
component.
- 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 Leap server.
The ID for a Service Transport must be made available by its developer.
- Name and Description
- To help users build Leap
applications with services, each Service Description contains both a name, and
a description. 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 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 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 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 Leap 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 Leap 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.
1: <?xml version="1.0" encoding="UTF-8"?>
2: <serviceDescription>
3: <id>get-content-type</id>
4: <defaultLocale>en-us</defaultLocale>
5: <transportId>HTTPServiceTransport</transportId>
6: <name xml:lang="en-us">Get Content Type</name>
7: <description xml:lang="en-us">
8: Retrieves the content type of the response from an HTTP server for the configured URL.
9: </description>
10: <inbound>
11: <parameters>
12: <parameter>
13: <id>request-url</id>
14: <type>STRING</type>
15: <name xml:lang="en-us">URL</name>
16: <description xml:lang="en-us">URL to request.</description>
17: <mandatory>true</mandatory>
18: </parameter>
19: </parameters>
20: </inbound>
21: <outbound>
22: <parameters>
23: <parameter>
24: <id>response-header-content-type</id>
25: <type>STRING</type>
26: <name xml:lang="en-us">Content Type</name>
27: <description xml:lang="en-us">Content Type of the response.</description>
28: </parameter>
29: </parameters>
30: </outbound>
31: </serviceDescription>
- All Service Descriptions begin with a serviceDescription element,
and in this example, it is defined in line 2. The serviceDescription element
contains all the information that is needed for the Leap server to work with the Service Description. The
unique ID of this Service Description is get-content-type as
defined in line 3. The unique ID is not exposed to a user, but it
must be unique. Line 5 declares the ID of the Service Transport to
use, which is HTTPServiceTransport, and this
is the unique ID of the HTTP Service Transport. Lines 7 and 8 define
the name and description of
the Service Description, which are presented to the user when designing
applications.
Lines 10-20 define the inbound bindings, and lines
21-30 define the outbound bindings. As mentioned previously, the inbound
bindings refer to the parameters that are flowing from the application
to the Service Transport. The outbound bindings refer to the parameters
that are flowing in the opposite direction.
Lines 11-19 contain
all the inbound parameters, of which there is only one.
The
parameter that is defined in lines 12-18 represents the URL to which
a request is made. According to the HTTP Service Transport documentation,
the parameter that contains the URL to which the request is made must
be called request-url.
Line 13 defines
the id of the parameter so that it matches the
expectations of the HTTP Service Transport.
The name and description are
defined in lines 15 and 16, and line 17 specifies that this parameter
must be supplied in order for this Service Description to operate.
Lines
21-30 define the outbound parameters for the Service Description.
In this case, there is only one output parameter: the content type
of the response. The HTTP Service Transport dynamically creates new
parameters that are based on the information that is returned in the
HTTP response. In particular, response headers are converted to lowercase
and are prefixed with response-header-. Since
this Service Description is interested in the Content-Type header,
the outbound parameter response-header-content-type is
created in lines 23-28 to contain this data.
- 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 Leap application to supply the URL. Instead, the URL is
declared using a constant, and mapped into the inbound parameters
for the Service Transport.
1: <?xml version="1.0" encoding="UTF-8"?>
2: <serviceDescription>
3: <id>get-content-type-with-constant</id>
4: <defaultLocale>en-us</defaultLocale>
5: <transportId>HTTPServiceTransport</transportId>
6: <name xml:lang="en-us">Get Content Type with Constant</name>
7: <description xml:lang="en-us">
8: Retreives the content type of the response from an HTTP server.
9: </description>
10: <inbound>
11: <serviceMapping>
12: <constants>
13: <constant>
14: <id>url-to-request</id>
15: <value>http://www.ibm.com</value>
16: </constant>
17: </constants>
18: <mapping>
19: <mapping source="constant:url-to-request" sourceType="string" target="transport:request-url" targetType="string"/>
20: </mapping>
21: </serviceMapping>
22: </inbound>
23: <outbound>
24: <parameters>
25: <parameter>
26: <id>response-header-content-type</id>
27: <type>STRING</type>
28: <name xml:lang="en-us">Content Type</name>
29: <description xml:lang="en-us">Content Type of the response.</description>
30: </parameter>
31: </parameters>
32: </outbound>
33: </serviceDescription>
- Like Example 1, the Service Description makes a request to an
HTTP server and returns the content type of the response. However,
this Service Description differs from the Example 1 because there
are no input parameters to this service. The request-url HTTP
Service Transport parameter is mapped into the transport via a constant.
Lines
12-17 define the constants section. There is
a single constant that is defined in lines 13-16. This constant has
an id of url-to-request specified
in line 14, and a value of http://www.ibm.com,
specified in line 15. The id of the constant
is used when creating the parameter structure that is passed to the
Service Transport. This constant is referenced in line 19 within the mapping section.
Lines
18-20 contain the mapping information. Since there is only one parameter
to be sent, there is only one mapping, which is defined in line 19.
This mapping specifies that the value of the Service Transport parameter
named request-url is specified by the value of
the constant named url-to-request.
- 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 Leap. This example describes how to specify a region
and return a list of the names of countries within that region.
1: <?xml version="1.0" encoding="UTF-8"?>
2: <serviceDescription>
3: <id>countries-by-region</id>
4: <defaultLocale>en-us</defaultLocale>
5: <transportId>4647b8cf-093f-11e0-89dd-001e4cf83606</transportId>
6: <name xml:lang="en-us">
7: Countries by Region using Service Description
8: </name>
9: <description xml:lang="en-us">
10: Given a region, return a list of country information in that region.
11: </description>
12: <inbound>
13: <parameters>
14: <parameter>
15: <id>region</id>
16: <type>STRING</type>
17: <name xml:lang="en-us">Region</name>
18: <description xml:lang="en-us">
19: One of "Africa", "America, North", "America, South", "Asia", "Europe", or "Oceania"
20: </description>
21: <mandatory>true</mandatory>
22: </parameter>
23: </parameters>
24: </inbound>
25: <outbound>
26: <parameters>
27: <parameter>
28: <id>countries</id>
29: <type>LIST</type>
30: <name xml:lang="en-us">Countries"</name>
31: <description xml:lang="en-us">List of country information</description>
32: <parameters>
33: <parameter>
34: <id>name</id>
35: <type>STRING</type>
36: <name xml:lang="en-us">Name</name>
37: <description xml:lang="en-us">Name of Country</description>
38: </parameter>
39: </parameters>
40: </parameter>
41: </parameters>
42: </outbound>
43: </serviceDescription>
- As with the other Service Description examples, this Service Description
has its own unique ID, defined in line 3, a name, which is defined
in lines 6-8, and a description, which is defined in lines 9-11. This
Service Description uses the sample Countries by Region Service
Transport, which is shipped with the Leap , and is identified by its id in
line 5.
Because this Service Description has a single inbound parameter,
the parameters element, in lines 13-23, of the inbound bindings
in lines 12-24. parameters contains only a single
parameter, which is defined in lines 14-22. The id of
this parameter is region, which is what is expected
by the Countries by Region Service Transport.
Since
there can be multiple countries within a region, the outbound bindings,
which are defined in lines 25-42, must contain a list parameter to
contain all the information for each country. The outbound structure
for this Service Description consists of a parameter that is called countries that
contains a list of maps. Each of the maps that are contained within
the countries list consists of a single name key
that contains the name of a country. This structure is defined within
the parameters element, which is defined in lines
26-41, of the outbound bindings section. The top-level parameter, countries,
is defined between lines 27 and 40. Since the countries parameter
contains other parameters, its type is set as LIST in
line 29. All the parameters of the list entries are defined within
the parameters element inside the countries parameter
that is defined in lines 32-39. The single name subparameter
is defined in lines 33-38.
Since the inbound and outbound bindings
directly match what is returned by the Countries by Region Service
Transport, there is no need for any mapping information. This service
can be set up such that the name subparameter
is mapped to list-like items such as drop-down options or an item
in a table.
- 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.
1: <?xml version="1.0" encoding="UTF-8"?>
2: <serviceDescription>
3: <id>address-lookup</id>
4: <defaultLocale>en-us</defaultLocale>
5: <transportId>HTTPServiceTransport</transportId>
6: <name xml:lang="en-us">Address Lookup</name>
7: <description xml:lang="en-us">Returns information related to a postal code or address.</description>
8: <inbound>
9: <parameters>
10: <parameter>
11: <id>address</id>
12: <type>STRING</type>
13: <name xml:lang="en-us">Address or Postal Code</name>
14: <description xml:lang="en-us"></description>
15: <mandatory>true</mandatory>
16: </parameter>
17: </parameters>
18: <serviceMapping>
19: <constants>
20: <constant>
21: <id>request-url</id>
22: <value>http://maps.googleapis.com/maps/api/geocode/xml</value>
23: </constant>
24: <constant>
25: <id>false-constant</id>
26: <value>false</value>
27: </constant>
28: <constant>
29: <id>request-method</id>
30: <value>GET</value>
31: </constant>
32: </constants>
33: <mapping>
34: <mapping target="transport:request-url" source="constant:request-url"/>
35: <mapping target="transport:request-method" source="constant:request-method"/>
36: <mapping target="transport:request-query-address" source="parameter:address"/>
37: <mapping target="transport:request-query-sensor" source="constant:false-constant"/>
38: </mapping>
39: </serviceMapping>
40: </inbound>
41: <outbound>
42: <parameters>
43: <parameter>
44: <id>latitude</id>
45: <type>STRING</type>
46: <name xml:lang="en-us">Latitude</name>
47: <description xml:lang="en-us"></description>
48: </parameter>
49: <parameter>
50: <id>longitude</id>
51: <type>STRING</type>
52: <name xml:lang="en-us">Longitude</name>
53: <description xml:lang="en-us"></description>
54: </parameter>
55: <parameter>
56: <id>address-information</id>
57: <type>LIST</type>
58: <name xml:lang="en-us">Address Information</name>
59: <description xml:lang="en-us"></description>
60: <parameters>
61: <parameter>
62: <id>long-name</id>
63: <type>STRING</type>
64: <name xml:lang="en-us">Long Name</name>
65: <description xml:lang="en-us"></description>
66: </parameter>
67: <parameter>
68: <id>short-name</id>
69: <type>STRING</type>
70: <name xml:lang="en-us">Short Name</name>
71: <description xml:lang="en-us"></description>
72: </parameter>
73: <parameter>
74: <id>type-1</id>
75: <type>STRING</type>
76: <name xml:lang="en-us">Type</name>
77: <description xml:lang="en-us"></description>
78: </parameter>
79: <parameter>
80: <id>type-2</id>
81: <type>STRING</type>
82: <name xml:lang="en-us">Type(2)</name>
83: <description xml:lang="en-us"></description>
84: </parameter>
85: </parameters>
86: </parameter>
87: </parameters>
88: <serviceMapping>
89: <mapping>
90: <mapping source="transport:response-entity"
91: sourceRef="GeocodeResponse/result[1]/geometry/location/lat"
92: sourceType="xml"
93: target="parameter:latitude"/>
94: <mapping source="transport:response-entity"
95: sourceRef="GeocodeResponse/result[1]/geometry/location/lng"
96: sourceType="xml"
97: target="parameter:longitude"/>
98: <mapping source="transport:response-entity"
99: sourceRef="GeocodeResponse/result[1]/address_component"
100: sourceType="xml"
101: target="parameter:address-information">
102: <mapping sourceRef="long_name" target="parameter:long-name"/>
103: <mapping sourceRef="short_name" target="parameter:short-name"/>
104: <mapping sourceRef="type[1]" target="parameter:type-1"/>
105: <mapping sourceRef="type[2]" target="parameter:type-2"/>
106: </mapping>
107: </mapping>
108: </serviceMapping>
109: </outbound>
110: </serviceDescription>
- This Service Description performs a reverse address lookup using
a free Google web service. As with the other Service Description examples,
the standard prologue of id, transportId, name,
and description is specified in lines 3-7. This
service has a single parameter, address, that
can be assigned by an application, as specified in lines 10-16. Since
this parameter is required to perform the address look-up, it is marked
as mandatory in line 15.
Since this Service Description uses the
HTTP Service Transport, a request-url must be
specified. The URL used in this request takes the form http://maps.googleapis.com/maps/api/geocode/xml?address=[address]&sensor=[true|false].
Because there are query parameters that must be sent, this Service
Description uses the HTTP Service Transport support for query parameters
by prefixing the name of the parameter with request-query-.
However, because some of these query parameters are not exposed to
the user, you must create a mapping section to map some constant values.
The inbound binding constant section, in lines 19-32, defines the
three constants that are used: request-url, lines
20-23, false-constant, lines 24-27, and request-method,
lines 28-31. These constants contain the URL to which to request is
made, a constant string value false for the
sensor query parameter, and the request method. While some of these
constants, including request-url and request-method,
match the name of the parameter to which they are applied, there is
no requirement that they match. Parameter names that match do not
automatically get a constant value if it has the same name. All mapping
must be explicitly defined.
In lines 33-38, the mapping section
of the inbound binding maps the constants and Service Description
parameters to the Service Transport parameters. Each of the mapping
elements is fairly self-explanatory: the request-url constant
is mapped to the request-url transport parameter;
the request-method constant is mapped to the request-method transport
parameter; the address parameter is mapped to
the request-query-address transport parameter;
and the constant false-constant is mapped to
the sensor transport parameter.
The HTTP
Service Transport then builds a URL out of the request-url,request-query-address,
and request-query-sensor parameters, and makes
a request to that URL using the HTTP method given in the request-method parameter.
The response body that is returned by this request is placed in the response-entity transport
parameter, which is then taken apart by the mapping section of the
outbound bindings.
This service expects the
response-entity to
be similar to the following:
1: <?xml version="1.0" encoding="UTF-8"?>
2: <GeocodeResponse>
3: <status>OK</status>
4: <result>
5: <type>street_address</type>
6: <formatted_address>1 New Orchard Rd, Armonk, NY, USA</formatted_address>
7: <address_component>
8: <long_name>1</long_name>
9: <short_name>1</short_name>
10: <type>street_number</type>
11: </address_component>
12: <address_component>
13: <long_name>New Orchard Rd</long_name>
14: <short_name>New Orchard Rd</short_name>
15: <type>route</type>
16: </address_component>
17: <address_component>
18: <long_name>Armonk</long_name>
19: <short_name>Armonk</short_name>
20: <type>locality</type>
21: <type>political</type>
22: </address_component>
23: <address_component>
24: <long_name>Westchester</long_name>
25: <short_name>Westchester</short_name>
26: <type>administrative_area_level_2</type>
27: <type>political</type>
28: </address_component>
29: <address_component>
30: <long_name>New York</long_name>
31: <short_name>NY</short_name>
32: <type>administrative_area_level_1</type>
33: <type>political</type>
34: </address_component>
35: <address_component>
36: <long_name>United States</long_name>
37: <short_name>US</short_name>
38: <type>country</type>
39: <type>political</type>
40: </address_component>
41: <geometry>
42: <location>
43: <lat>41.1083018</lat>
44: <lng>-73.7204677</lng>
45: </location>
46: <location_type>ROOFTOP</location_type>
47: <viewport>
48: <southwest>
49: <lat>41.1051542</lat>
50: <lng>-73.7236153</lng>
51: </southwest>
52: <northeast>
53: <lat>41.1114494</lat>
54: <lng>-73.7173201</lng>
55: </northeast>
56: </viewport>
57: </geometry>
58: </result>
59: </GeocodeResponse>
- There is much data in this response, but only some of it is needed
for this Service Description. The latitude, longitude, and a list
of the address information from the first result is required. To get
only the required information, the Service Description outlines the
parameters that it expects to return in the parameters section,
in lines 42-87. The Service Description then uses the mapping section,
in lines 88-108, to extract the required data from the response-entity transport
parameter. Each of the parameters in the parameters section
is self-explanatory. Latitude and longitude are top-level parameters
because there is only one of each of them in a single result. However,
there are several address_component elements,
each of which are returned. Therefore, the address-information parameter
is a list parameter that contains subparameters, one for each of the
pieces of information in an address_component that
the Service Description wants to make available.
In lines 88-108,
the service mapping section defines all the mapping that must be performed
to extract the data from the XML response. Latitude, which is specified
in lines 90-93, and longitude, which is specified in lines 94-97,
each extract the data using a single XPath expression. The source
type for each is set to XML. Mapping of a repeating structure is accomplished
in a similar fashion. Lines 98-101 define the mapping for the address-information parameter.
The XPath expression for address-information returns
a nodeset as there are several nodes that match the expression GeocodeResponse/result/address_component.
For each node that is returned, a new structure is created to contain
the result of each of the submappings. Each of the submappings places
its target into the newly created structure. Since the source of each
of the submappings is one of the matched nodes, the mapping elements
do not specify a source. It is assumed to be the inherited context.
Similarly, the reference is evaluated within the context of the source,
which is inherited. After each of the submappings is evaluated for
a single source, the structure is added to a running list and the
submappings are evaluated again for the next result in the source
list. When all the sources are processed, the list that was collecting
the results of the map is assigned to the address-information parameter.
Appendix A - Service Description
schema