Simple Integration Solutions for common SOA requirements

Executive Summary

Over the years of providing integration solutions to various customers, some common integration scenarios have emerged. Neuron ESB now provides a zero-code solution for implementing these scenarios using a new feature of Neuron ESB client connectors called Service Routing Tables.

You can find ways to implement these common scenarios in this white paper.

1. Authorization and Access Control
2. Dynamic Routing
3. Message format conversion
4. Stubbing / Mocking or Service virtualization
5. Protocol Conversion
6. Service Availability and Policy
7. Blue-Green Deployment and Testing
8. Message Enrichment / Content Masking
9. Request Filtering
10. URL Rewriting
11. Message Transformation

Note that the pass-thru routing functionality is designed to be simple and low latency. It provides for many real-life use cases but not everything. Therefore, you may find that it may not suit your exact needs for the above cases. In that case, configuring your client connector with a business process and implementing the exact logic that you need in the business process is your best option. The business process gives you ultimate flexibility to manipulate the message and header with various useful steps, including custom C# code.

Authorization and Access Control

Problem:
You need the consumer applications of your client connector to be served by different service endpoints depending on the scope of their authorization.

Recipe:
You can implement this with OAuth using Neuron ESB and the Peregrine Management suite. To do this, follow the steps below. This assumes that Peregrine Management Suite Environment is configured to connect to the Neuron Instance running your solution. Refer to Peregrine MS documentation on how to do this.

Select Peregrine Connect on a Client Connector in Neuron solution as shown below.

Click Apply and Save.

Open Peregrine Management Suite.

Create a new API resource under API management.

Enter resource name, description, and other fields

Create two or more scopes depending on the granularity of access control you need

Select the Client Connector to be secured under this API resource.

Under API, Consumers create two consumers. Each consumer should have one of the scopes you defined above.

Generate consumer secrets for each consumer Id, and send them to the application owners that call the Neuron Client Connector.

The calling applications can generate the OAuth token using the Peregrine MS token endpoint and passing grant type client_credentials, consumer id and consumer secret as form parameters.

Each calling app will get a signed token that contains the scope assigned to them.

Calling application will attach the signed token to the HTTP Authorization header with calling the Neuron Client Connector.

In the Neuron Solution, create a routing table and two entries that point to the services that are do be delivered to consumers with scope A and consumers with scope B, respectively.

Note that these two may point to the same service with different a HTTP header, query string, or body associated with them depending on scope as shown in the next steps.

For the first entry, define a business condition with HTTPHeader: Token contains “Scope1”

For the second entry, define a business condition with HTTPHeader: Token contains “Scope2”

Configure the Body, Header, and URL parameters for each entry in the routing table.

Associate the newly defined routing table with the Client Connector.

Click, Apply, Save and restart the client connector.

Now when the calling application with Scope1 token or Scope 2 token call the client connector, they will be served according the configuration you defined in the routing table.

Dynamic Routing

Problem:
You need the consumer applications of your client connector to be served by different service endpoints depending on some content in the incoming request.

Recipe:
In the Neuron Solution, create a routing table and two entries that point to the services that are to be delivered to consumers with service endpoint A and service endpoint B, respectively.

Note that these two may point to the same service with a different HTTP header, query string, or body associated with them depending on scope as shown in the next steps.

For the first entry, define a business condition with Body contains text “service1”.

For the second entry, define a business condition with Body contains text “service2”.

Configure the Body, Header, and URL parameters for each entry in the routing table.

Associate the newly defined routing table with the Client Connector.

Click, Apply, Save and restart the client connector.

When the calling application calls the client connector, with requests that match conditions you configured, they will be served according to the configuration you defined in the routing table.

Message format conversion

Problem:
You need the consumer applications of your client connector to use REST protocol and JSON format to invoke legacy WCF soap services that use XML format.

Recipe:
In the Neuron solution, create a service endpoint to connect to the WCF/SOAP service using appropriate WCF binding such as basichttpbinding or ws-http binding.

Create a routing table that points to the service endpoint above. In the configure endpoint section, map the HTTP body to the soap envelope and soap body per the service wsdl. The soap body can contain portions of the JSON pay load expected from the consumer application. You can use Jobject.<propertyname> notation to include Json path of the payload which you want to pass along. An example of such mapping is shown below.

Once configured, associate this routing table to a Client Connector with REST binding. Now the consumer application can post JSON data such as

{ 
“ordereId” : 1, 
“amount” : 1123.45 
}

The service will be called with the SOAP Envelope and Body as specified in the routing table while substituting the values for orderId and amount as above.

Stubbing/Mocking or Service Virtualization

Problem:
You need to provide a client connector to consumer applications that connects to a back-end service that is not yet ready.

Recipe:
In the Neuron solution, create a service endpoint as a placeholder for the service that is not yet ready. The physical URL of this service endpoint can be any valid URL that may or may not have been implemented. This is because this service endpoint will never really be called by the routing table when it is configured, as shown below. The binding for this service endpoint also can be any binding that the actual service will require when it is ready.

Create a routing table that points to the service endpoint above. Configure the service endpoint in the routing table to return a test response, as shown below.

Associate the above routing table to your client connector configured with pass thru mode.

Now when the consumer application calls the client connector, a test response will be returned.

Protocol conversion

Problem:
You need to provide a REST-based endpoint that connects to a legacy WCF / SOAP service. Modern web applications using JavaScript clients usually require REST based endpoints.

Recipe:
In the Neuron solution, create a service endpoint for the WCF/SOAP service with appropriate binding such as basichttp or WS-Http.

Create a routing table that points to the service endpoint above. Configure the service endpoint to construct soap message using JSON properties of the incoming message or URL parameters of incoming messages. The SOAP message body usually looks like below. Configure also the SOAP action that is specified by the WSDL of the WCF/SOAP service. In the SOAP body use the token substitution to take values from the incoming message body and map to corresponding values in the request body.

Create a client connector with REST binding and associate the above routing table with it in pass thru mode.

When the client connector is invoked by the calling application using the HTTP client and post method with a JSON payload, it will call the SOAP service.

Service availability and policy

Problem:
You have configured a client connector that points to an external service for consumption by one application. Now another application needs access to that external service via the client connector, but it needs to be restricted to daytime use only, and some of the response codes from the downstream service need to be masked to a generic response code.

Recipe:
In the Neuron Solution, create a new policy under connections. In that policy specify the restrictions on availability and REST code mapping as shown below/

Configure the two downstream service endpoints that point to the same URL of the external service. Point one of the connectors to the default policy and another to the newly created policy, as shown below.

Then configure a new routing table that contains the two service endpoints above. Use the business conditions editor on each of the service endpoints to specify the conditions under which the service connector with default policy or the other policy will be called, as shown below.

Blue / Green Deployment and Testing

Problem:
You want to release a new version of service for a limited audience (blue deployment) in production and run it for some time before it is made available to all the consumers. (green deployment).

Recipe:
Follow steps like the scenario of service availability and policy described above and setup two endpoints for the service needing blue/green deployment. In this case the service endpoint policy need not be different, but it can be configured if that is part of the testing plan.

Then configure the routing table with conditions such that some consumers are directed to the new service (this can be a special URL parameter or some HTTP header or some value in the body text). Setup second service endpoint condition such that remaining consumers not meeting the above condition are directed to the old service endpoint.

Associate this routing table with your client connector. When it is time to turn the service green, change the conditions on the routing table so that all consumers are directed to the new service endpoint. The entry for old service endpoint and the old service endpoint itself may be deleted in time when no longer needed.

Message Enrichment / Content Masking

Problem:
You need to alter the return address field on all order requests being forwarded to fulfillment service due to address change. You also want to mask the email address of the customer due to privacy concerns.

Recipe:
In the Neuron solution, create a routing table that points to the service endpoint of the fulfillment service. Configure this endpoint in the routing table such that the message body is rewritten with token substitution {#JObject.Property) for all elements of the incoming JSON message except the email address and hard code the return address fields to your new values (disregarding the return address on the request message). An example is shown below.

Associate this routing table to the client connector in pass thru mode.

Request filtering

Problem:
You need to block certain requests from being forwarded to the downstream service due to objectionable content in the request.

Recipe:
Follow the recipe like the Stubbing/Mocking scenario. Except in this case, the routing table should contain two entries. One entry should be for the actual service endpoint, and another should be a dummy entry. The dummy entry should be configured to return a canned response in the Test mode. The business condition on this entry should be set to match the requests that need to be filtered. For example, if the request body contains certain offensive words then it should return match the test response entry. All other requests go through to the intended service endpoint.

URL Rewriting

Problem:
You need to substitute a simple URL for backend system URLs containing many query strings and nested directory paths.

Recipe:
Define a service routing table and in the URL parameters section, configure the backend service query strings as URL parameters that map to parts of the incoming URL.

In case of a scenario where parts of the incoming URL map to different paths, you may define multiple routing table entries pointing to URLs with different paths specified in the Local Path value of the above routing table and use conditions to for each routing table entry to match the incoming URL Mapping.

Message Transformation

You may route incoming requests to one or more services in the service routing table while applying different Request and Response data maps. This allows you to handle variations in incoming message bodies to make them compatible with the backend service being called.

You can also apply maps conditionally to the same of different service endpoints using conditions in the routing table as shown in the screenshot below.

Conclusion

Neuron ESB is a zero-code solution for many common use cases in the implementation of Service-Oriented Architecture. Neuron ESB features are distilled and tuned from years of experience and customer feedback. Service Routing Tables add brand new capabilities with a few clicks to enable low latency high-performance SOA solutions. Interested? Check out the training/tutorials and documentation at https://www.PeregrineConnect.com.