Creating Custom Services

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

GoogleGeoCodeLookup_json.xml

Zippopotumus Zipcode Look-up

zippopotamus.nitro_s

ZippopotumasZipCodeLookup_json.xml

Get Record Count (of submitted records for a specific App/Form)