...

Introduction

Mapping two values to one output parameter

Splitting One Response Value Into Two Parameters

Localizing a Service Description

Sending an XML Instance as Request Body

...

I decided to create this page as a place where I can place notes and comments about building service description XML files.  If you know nothing about this topic then there are a few other resources that you might want to check out first:

Documentation on Service Descriptions. This content will describe the different parts of a service description.

...

Mapping two values to one output parameter

...

This is a use case that was just brought to my attention.  Let's say that you have a service that returns several values and within your FEB application you want to present those values as a single field.  We can combine response values from your service call directly in the service description xml file.  In this example I created a service that returns information about a person and we want to surface the address information as an address block that can be rendered in a single multi-line field.  There are other ways that this can be accomplished, for example using JavaScript within your form but that would require that code to be used in every application that uses the service.  The technique I am proposing here is better because the solution is implemented once.

...

When you inspect this you will see that the sourceRef is the attribute that is doing the heavy lifting.  The sourceRef and targetRef attributes support XPath queries.  This means that we can inject smart processing into our service descriptions to massage the result data before passing it back to our FEB application.  In this case I use the concat function to build the "addressBlock" with all the related fields from my service response.  The string '
' is used to inject a new line into our content.

...

The serviceDescription is attached to this article, the service that it calls does not exist, but you can use it as a reference for using this technique in your own service descriptions.

...

Splitting One Response Value Into Two Parameters

...

This example uses a similar technique to the first but we are doing the opposite action.  Let's say for example that your service returns a value that you want to break out into more then one parameter:

...

As you can start to see there is a lot of flexibility in the service description xml to introduce some intelligence when manipulating results that get returned from a service.  Sometimes it will make sense to place this logic in the service description xml file, but there may be other times where you should accomplish your "logic" in the FEB app that consumes the service.Keep in mind that any logic in the service description xml file will affect every time it is called.

If you have a use case that requires more complex logic you can always review the documented XPath functions and use them to accomplish your task.  It is unclear to me at this time if the service description mechanism supports all of these functions, but the basic list can be viewed at w3schools. As more use cases become available I will add to this article.

...

Localizing a Service Description

You can create localized strings for your custom service descriptions.

...

Additional details can be found in the HCL Leap documentation.

...

Sending an XML Instance as Request Body

Some services require a specific input instance to interact with them.  It is possible within a service description xml file to define a prototypical instance and then dynamically insert inbound parameters or constants using service mappings. 

...

<a:entry xmlns:a="http://www.w3.org/2005/Atom"><a:title type="text">This is a sample blog post from a FEBan app!</a:title><a:content type="html">This is a sample blog post from a FEBan app!</a:content><a:category term="sample"/><a:category term="rest_api"/><a:category term="awesome"/></a:entry>

...