Creating Custom Services
- Marty Lechleider
- Christopher Dawes
What is a Service Description?
A service description is an XML file that describes the input/output parameters and how those map to the transport parameters. There are a few ways that you can setup services:
1. Use the Dynamic Service feature in FEB - this feature added in 8.6.3 can only be used for services that communicate in JSON.
2. Manually create and place XML files in the ServiceCatalog/1 directory on the FEB server.
3. Create an extension that dynamically builds the service description catalogs and service description XML files.
The HTTPServiceTransport
A Transport is an OSGI plugin, written in Java, that knows how to interact with an endpoint. Transports can be used to directly interact with a database or a third-party application, with a transport you could integrate FEB with just about anything.
FEB ships with the HTTPServiceTransport, which is capable of interacting with any public endpoint. For more details on all the different parameters check out our online documentation for the HTTPServiceTransport.
Using the Dynamic Service feature
A guide on using the dynamic service feature.
Manual Creation of a Service Description XML File
If you are going to manually create an XML file, the structure of the service description has been provided below. This would a good starting point, if you want to copy and paste the XML into your own file and then modify from there.
<?xml version="1.0" encoding="utf-8"?> <serviceDescription> <id>theServiceID-mustBeUnique</id> <defaultLocale>en</defaultLocale> <transportId>HTTPServiceTransport</transportId> <name xml:lang="en">Service name that appears in FEB</name> <description xml:lang="en">Service description that appears in FEB</description> <!-- Possible providers are cookie, basic and j2cAlias--> <credentials providerId="cookie"> <property name="cookies" value="LtpaToken,LtpaToken2"/> </credentials> <!-- Inbound Parameters - these are the items that can be mapped to fields in a form --> <inbound> <parameters> <parameter> <id>appid</id> <name>App ID</name> <description>The App ID.</description> <mandatory>true</mandatory> <type>STRING</type> </parameter> <parameter> <id>formid</id> <name>Form ID</name> <description>The Form ID (i.e. F_Form1)</description> <mandatory>true</mandatory> <type>STRING</type> </parameter> </parameters> <serviceMapping> <!-- constants - these are the hard-coded items that can be passed to the transport --> <constants> <constant> <id>url-base</id> <!-- https://<server>/forms-basic/secure/org/data/appid/formid?columns=dummyValue&includeRecordMetadata=true&format=text/xml--> <value>http://localhost:9081/forms-basic/secure/org/data/</value> </constant> <constant> <id>request-method</id> <value>GET</value> </constant> <constant> <id>contentType</id> <value>application/atom+xml</value> </constant> <constant> <id>columns</id> <value>dummyValue</value> </constant> <constant> <id>trueVal</id> <value>true</value> </constant> <constant> <id>falseVal</id> <value>false</value> </constant> <constant> <id>format</id> <value>text/xml</value> </constant> <constant> <id>sep</id> <value>/</value> </constant> </constants> <!-- Inbound mappings - these define HOW the inbound parameters or constants are mapped to the transport parameters --> <mapping> <mapping target="transport:request-url" source="constant:url-base" sourceType="NOOP" targetType="STRING"/> <mapping target="transport:request-url-postfix-0" source="parameter:appid" sourceType="NOOP" targetType="STRING"/> <mapping target="transport:request-url-postfix-0-encoded" source="constant:falseVal" sourceType="NOOP" targetType="STRING"/> <mapping target="transport:request-url-postfix-1" source="constant:sep" sourceType="NOOP" targetType="STRING"/> <mapping target="transport:request-url-postfix-1-encoded" source="constant:trueVal" sourceType="NOOP" targetType="STRING"/> <mapping target="transport:request-url-postfix-2" source="parameter:formid" sourceType="NOOP" targetType="STRING"/> <mapping target="transport:request-url-postfix-2-encoded" source="constant:falseVal" sourceType="NOOP" targetType="STRING"/> <mapping target="transport:request-method" source="constant:request-method" sourceType="NOOP" targetType="STRING"/> <mapping target="transport:request-query-columns" source="constant:columns" sourceType="STRING" targetType="STRING"/> <mapping target="transport:request-query-includeRecordMetadata" source="constant:trueVal" sourceType="STRING" targetType="STRING"/> <mapping target="transport:request-query-format" source="constant:format" sourceType="STRING" targetType="STRING"/> </mapping> </serviceMapping> </inbound> <!-- Outbound Parameters - these are the items that can be mapped to fields in a form --> <outbound> <parameters> <parameter> <id>response</id> <name xml:lang="en">Response</name> <description xml:lang="en"></description> <type>INTEGER</type> </parameter> </parameters> <serviceMapping> <!-- Outbound mappings - these define HOW the transport parameters are mapped to the outbound parameters --> <mapping> <mapping source="transport:response-entity" sourceType="XML" target="parameter:response" targetType="STRING"/> </mapping> </serviceMapping> </outbound> </serviceDescription>
What you need to know
The following articles have been written to help you understand what is possible within a service description XML file. Use these along with the Knowledge Center content to build the exact services that you need within your organization.
Understanding the Service Description XML
Creating Service Description XML that returns JSON
Troubleshooting - Creating Service Description XML
Deploy-able Examples
Service Descriptions for IBM Connections
Google Geocode Service
JSONService-GoogleGeoCode.nitro_s
Zippopotumus Zipcode Look-up
ZippopotumasZipCodeLookup_json.xml
Get Record Count (of submitted records for a specific App/Form)
Get Meta-data for a App/Form