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 HCL Volt 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
HCL Volt 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 HCL Volt server. The ID for a Service Transport must be made available by its developer.
- Name and Description
- To help users build Volt applications with services, each Service Description contains both a name, and a description.The name and description elements allow you to localize a Volt 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 Volt 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 Volt 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 Volt. 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 Volt 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 Volt 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.
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>
- 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 Volt 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>
- 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
Volt Builder Server. 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>
- 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>
Appendix A - Service Description schema