Skip to content

Neuron ESB includes a Service Broker that enables organizations to deploy Neuron ESB as a Service Gateway, providing mediation, security, hosting and a number of other services. Service Connectors are essentially registrations within Neuron ESB that point to existing services hosted within an organization, by a partner or in a cloud domain. These services, which can be either SOAP or REST (HTTP) based, can be called either through the Neuron ESB messaging system via a Topic subscription or by using a Service Endpoint Workflow Activity and Process Step. The latter two options can be used with either the Neuron ESB Workflow Designer or the existing Business Process Designer and allows a user to directly call any Service Connector without the need to publish a request to a Topic, eliminating all pub/sub overhead. These are commonly used to create service aggregation and composition solutions.

For calling REST (HTTP) based Service Connectors (endpoints), it’s not uncommon that various pieces of information need to be provided at runtime according to the REST specification. For example, the Method name (e.g. GET, POST, PUT, PATCH, etc.) must be provided. HTTP Headers usually need to be provided (e.g. Content Type, Authorization, Accept, etc.) as well as Query string or URL parameters.

In previous versions of Neuron ESB, this information could be provided by using a C# Code Editor within either the Business Process Designer or Workflow Designer directly preceding the Service Endpoint activity as depicted below:

Opening the C# Code Editor allowed developers to provide the information they needed to initialize the service call at runtime by primarily using the HTTP object of the Neuron ESB Message as shown below.

The information used to initialize these HTTP elements could come from the existing Neuron ESB Message, Neuron ESB Message or context properties or even Neuron ESB Environmental Variables that may have different values at runtime depending on the runtime environment they are deployed to. The example below shows how Query string parameters could be set in a Code Editor in the Workflow Designer.

HTTP (REST) Endpoint Configuration

Rather than requiring that developers use C# to set HTTP properties, CU4 introduces a new tool, the “HTTP Utility”. This utility can be used within the Business Process  or Workflow Designer to do more advanced levels of HTTP configuration. The HTTP Utility is exposed as both a Process Step and Workflow Activity that can be dragged onto either designer. Users can select “Configure” from the context menu to display the main configuration screen of the HTTP Utility as shown below:

For users familiar with tools like “Postman” and the REST client of Chrome, the HTTP Utility will look very similar and they will find it just as easy to configure. The HTTP Utility has built in intelligence and allows users to use Neuron ESB Environmental Variables, Neuron ESB Message properties, Context properties and literal values to configure any Value, Message body or URL as shown below:

Valid HTTP Header options and methods are displayed as drop down boxes, while possible values for the selected HTTP Header “key” also appear as context sensitive drop downs.

Alternatively, Neuron ESB Environmental Variables, properties (context, message, etc.), message body and literals can be used by selecting from the available list. Environmental variables are preceded by the “$”, whereas all others are preceded by “#” as shown below.

The literal values that appear in the list (i.e. by pressing CTRL + SPACE) that can be used are:

  • {#DateTime(local)} – Adds the local date time value with following format: “yyyyMMddHHmmss”
  • {#DateTime(local), ddmmyyyyhhmmss } – Adds the local date time value using the provided format specifier
  • {#DateTime(Utc)} – Adds the UTC date time value with following format: “yyyyMMddHHmmss”
  • {#DateTime(Utc),ddmmyyyyhhmmss} – Adds the UTC date time value using the provided format specifier
  • {#IMF-fixdate} – Adds the RFC 7231 Date/Time Format e.g. ‘Tue, 15 Nov 1994 08:12:31 GMT’”
  • {#GUID} – Adds a unique GUID string value (e.g. 00000000-0000-0000-0000-000000000000)

Values that can be used to access either some part of the body or a custom message property of the ESB Message are:

  • {#<custom>.<property>} – Returns custom message property i.e. context.data.GetProperty(“myPrefix”, “MyProperty”)
  • {#JObject.<property>} – Returns the property from the JSON dynamic object property from the current Neuron ESB Message.

Besides the Method drop down box and the URL text box, the HTTP Utility has 3 primary tabs: Headers, Body and URL Parameters. The Headers tab allows users to specify any HTTP or custom key/value pairs that will appear as HTTP Headers in the final REST service call. A good example of an HTTP Header could be either the Content Type or Authorization header. The Body tab allows users to specify how the body should be encoded and sent to the service as shown below:

Using the settings, Neuron ESB will ensure the proper HTTP Content Type and data are appropriately set and encoded if necessary. Users have additional options like clearing out the underlying Neuron ESB Message body if either Form Body or Form Url Encoded options are chosen.

The URL Parameters tab allows users to enter key/value pairs that will be serialized as URL parameters for the service call. The HTTP Utility removes the need for developers to use C# to set the required HTTP properties for any service call. In the example below, a Salesforce authentication call is made where all the values are using Neuron ESB Environmental Variables, allowing the values to be specific to the actual runtime environment the solution is deployed to:

Swagger Integration

Over the years, Swagger has become a common documentation format for REST (HTTP) based services. As such, the CU4 release introduces a number of new JSON/Swagger features, one of which is the ability to configure the HTTP Utility using Swagger.

For example, CU4 ships a Marketo adapter which is accompanied by its respective Swagger documentation. The Marketo Swagger documentation, as well as any Swagger document registered within the new Neuron ESB Swagger Repository, can be accessed directly within the “Use Swagger document” section of the HTTP Utility.

Swagger documents can be imported in the Neuron ESB Swagger Repository by navigating to Repository->Service Descriptions->Swagger Documents within the Neuron Explorer.

By expanding the “Use Swagger document” section, the Document and Operations drop-down fields will be visible and populated using existing Swagger documents in the Repository. These can be selected to auto configure the HTTP Utility.  If a Swagger document doesn’t exist, one can be imported directly within the UI by selecting the “Import Swagger…” option from the Document drop-down and providing the URL of the Swagger document.

JSON Templates and Data Mapping

JSON has become more prominently used by developers and integrators as organizations move to using more REST (HTTP) based services. CU4 provides new repositories and access methods that make using JSON much easier than in previous releases of Neuron ESB.

In CU4, the ToJObject() has been added to the Neuron ESB Message object. This will return the Neuron ESB Message body as a Newtonsoft.Json.Linq.JObject. This is accessible within either a Workflow or Business Process. It allows users to use .NET’s dynamic object keyword to access data correctly using a hierarchical syntax. For example, a sample json document like the following:

{ 

"message": "Success. Lead Created",

"data": {

"SalesOwnerAccountUserId": "118527",

"AccountUserId": "89027"

}

}

Could then be accessed directly in a Code Editor using C# as shown below:

dynamic jo = context.Data.ToJObject();

var ownerID = jo.data.SalesOwnerAccountUserId;

This makes it much easier for developers to access and modify JSON data within a Business Process or Workflow.

To complement this, a new JSON Repository for storing JSON documents and templates has been introduced which can be located by navigating to Repository->Documents->Json Documents within the Neuron ESB Explorer. Sample JSON documents or templates can be stored and accessed at runtime within any of the Business Process or Workflow environments. Integrators can use JSON templates as a quick, simple way to facilitate data mapping/transformations. JSON templates are nothing more than JSON messages that have format specifiers inserted for their values. For example, if the following template was stored in the repository and named,

AccountUpdateRequest”:

{"salesRepAccountUserID":{0},

"auditAccountUserID":{1}

}

It could then be retrieved in any Business Process or Workflow by using the “JsonFormatString” property of the repository document:

var accountUpdateTemplate =   configuration.JsonDocs["AccountUpdateRequest"].JsonFormatString;

Once the template is retrieved, data mapping can be as easy as this:

Context.Data.Text = string.Format(accountUpdateTemplate,  (string)jo.data.SalesOwnerAccountUserId??string.Empty,  (string)jo.data.accountUserID??string.Empty);