Versions Compared

Version Old Version 1 New Version Current
Changes made by

Former user

Former user

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Here are the guidelines and recommendations to design, develop, test, and deploy WSO2 integration solutions:

...

  • When you create an artifact, use the proper naming convention from the start.
  • If an ESB project contains many artifacts related to multiple use cases, name the artifacts by prefixing or post fixing the use case name. 
  • Create specific ESB projects for specific use cases. This makes it easy to manage the code/project.
  • Design the ESB logic into highly cohesive and loosely coupled modules.
  • Avoid creating large, complex mediation code as much as possible. Always follow the separation of concerns design principle and split lengthy logic into separate mediation components.
  • When you have a common set of code, implement it in a sequence or a template that can be reused. For more information, see Sequence Template.
  • Externalize endpoint and policy references using the Registry. For more information, see Managing ESB projects across environments. 
  • Hide sensitive information such as passwords in configuration files using Secure Vault.

...

A Proxy service or REST API resource has a InSequence to handle the request message flow and has an OutSequence to handle the response message flow. Therefore, the In mediator and Out mediator should not be used in proxy services or REST API resources. However, you should use the In mediator and Out mediator in the main sequence.

Using the ForEach/wiki/spaces/EI6xx/pages/49612877 mediator

Insert excerpt
EI6xx:ForEach Mediator
EI6xx:ForEach Mediator
nopaneltrue

Using the Clone /wiki/spaces/EI6xx/pages/49612608 mediator

When using a Clone mediator, use a Call mediator in the target sequence to bring the responses back into the In-Sequence. This continues the mediation since the Continuation Stack gets pushed into the Synapse Message Context via the handleMessage method in the SynapseCallbackReceiver class.

Otherwise, the Continuation Stack becomes empty in the Synapse Message Context if you do not use a Call mediator in the target sequence.

Using the Loopback  mediator

Do not include the Loopback mediator in the OutSequence.

...

  • You should not specify any mediator after the Send Mediator  or the  Respond Mediator .

    A message flow must end from these two mediators. Here, the message flow does not mean the current sequence. If you have these two mediators in a sub-sequence that gets called from a parent sequence, then once the message returns from the sub-sequence to the parent, the parent sequence should not include any mediator after the call to the sub-sequence. If you include a mediator after these two mediators, it can cause unusual behaviour in the message flow.

    The following diagram illustrates an incorrect use of the Send mediator:

    Image Modified

    The following diagram illustrates the correct use of the Send mediator:

...

General mediator best practices

  • Use the Iterate /wiki/spaces/EI6xx/pages/49612680 mediator in association with the Aggregate /wiki/spaces/EI6xx/pages/49612670 mediator.

  • Do not do any configuration after the Send mediator.

  • Do proper error handling to handle mediation errors as well as endpoint errors.

  • Use appropriate intervals for tasks.

  • Use the ForEach mediator only for message transformations. If you need to make back-end calls from each iteration, then use the iterate mediator.

  • Do not use the DB mediators (DBReport and DBLookup) with complex SQL queries or in scenarios where you need to simultaneously retrieve multiple rows. Instead, use the data services functionality of WSO2 Enterprise Integrator. For information on how to use the data services functionality, see the Tutorials.

  • Use dollar context (i.e., $ctx) instead of get-property(). This is because the get - property  methods search even in Registry if the value is not available in the message context. Thus, it affects performance as Registry search is an expensive operation. However, $ ctx  only checks in the message context. 
    If you need to retrieve a property that you have set on a message, use the predefined XPath variables such as $ctx instead of the get-property() function for better performance. For example, use $ctx: proxy.name instead of get-property(' proxy.name ').
    For more information on the predefined XPath variables that you can use to retrieve a property, and for examples of XPath variable usage, see Synapse XPath Variables.

    Note
    titleNote

    The use of the get-property() function can have a lower performance because it does a registry lookup when the value is not available in the message context. Therefore, the recommended approach is to use predefined XPath variables when you need to retrieve a property.

    You will encounter this performance issue only if you are using WSO2 ESB 4.9.0 or below.

  • Reusing a defined sequence
    If you want to repeatedly use the same mediation sequence, you can define it and save it either in the Synapse configuration or in the Registry, with a unique name. Then you can call the mediation sequence from the main sequence as well as from multiple proxy services and REST APIs. The saved sequence can be called via the Sequence mediator or can be selected as the InSequence, OutSequence, or FaultSequence when you define a proxy service or a REST API.

    The following diagram illustrates how a saved sequence can be called using the Sequence mediator:

...

  • Use meaningful resource names to clarify what a given request does. A RESTful URI should refer to a resource that is a thing instead of an action. The name and structure of URIs should convey meaning to those consumers.
  • Use plurals in node names to keep your API URIs consistent across all HTTP methods.
  • Use HTTP methods appropriately. Use POST, GET, PUT, DELETE, OPTIONS and HEAD in requests to clarify the purpose of the request. The POST, GET, PUT and DELETE methods map to the CRUD methods Create, Read, Update, and Delete, respectively. Each resource should have at least one method.
  • Create at most only one default resource (a resource with neither a uri-template nor a url-mapping) for each API.
  • Offer both XML and JSON whenever possible.
  • Use abstraction when it's helpful. The API implementation does not need to mimic the underlying implementation. 
  • Implement resource discoverability through links (HATEOAS). As mentioned in the previous section, the application state should be communicated via hypertext. The API should be usable and understandable given an initial URI without prior knowledge or out-of-band information.
  • Version your APIs as early as possible in the development cycle. At present, the ESB profile identifies each API by its unique context name. If you introduce a version in the API context (e.g., /Service/1.0.0), you can update it when you upgrade the same API (e.g., /Service/1.0.1).
  • Secure your services using OAuth2, OpenID, or another authentication/authorization mechanism. See also Securing APIs /wiki/spaces/EI6xx/pages/49613389.

Working with endpoints

  • Do not use anonymous endpoints. Always use named endpoints. As anynymous endpoints have auto-generated names in the synapse configuration, it is difficult to identify which endpoint is causing the error in case of an error.

  • Configure timeout settings appropriately. Timeout configurations are required before you go into production with the system.

    The diagram below illustrates the typical message flow when a proxy service is involved in a client-server communication. The two connectores, Client to Proxy connection and Proxy to Backend connection , are two separate connections that do not depend on each other. Even if one connections times out, the other is unaffected.

    Here are the important timeout parameters you should configure before going into production:

    ParameterDescriptionConfiguration FileDefault ValueRecommended Value
    http.socket.timeout The socket timeout of the Passthrough http/https transport sender and listener. You can find the passthru-http.properties file in the <EI_HOME>/conf directory.passthru-http.properties180000180000
    Endpoint timeout

    The timeout parameter that you should configure at the endpoint level. You can configure timeout values as required for specific endpoints.

    Here's a sample endpoint configuration that is configured with timeout parameters. Here, <duration> is the timeout value, and <responseAction> is the action to be taken on timeout. In this example, it is invoking the FaultSequence.

    Code Block
    <endpoint>
   <address uri="http://localhost:8281/services/SimpleStockQuoteService">
       <timeout>
          <duration>120000</duration>
          <responseAction>fault</responseAction>
       </timeout>
   </address>
 </endpoint>
    Tip

    Follow the formula Socket Timeout > max(Global endpoint timeout, Timeout of individual endpoints), and make sure that you set the  http.socket.timeout to a value higher than all other endpoint timeout values.

    		Endpoint configuration filessynapse.global_timeout_intervalDepends on the use case, Typically 120000
    synapse.global_timeout_interval

    Global timeout value for endpoints. Can be overwritten by individual endpoint timeout values.

    Synapse, which is the underlying mediation engine of WSO2 Enterprise Integrator, is a complete asynchronous messaging engine that does not block its worker threads on network I/O. Instead, it registers a call-back for a particular request and returns the threads without waiting for a response. When a response is available, the registered call-back is used to correlate it with the relevant request so that further processing can be done.
    If the backend server does not respond, it is required to clear the registered call-backs after a particular duration to prevent possible memory leaks. This duration is set via a timer task called TimeoutHandler. The synapse.global_timeout_interval parameter represents the duration that a call-back should be kept in the call-back store. 

    Tip

    If you have configured a timeout value at the endpoint level, the global timeout value is not taken into consideration for that endpoint. For all the other endpoints that do not have a timeout value configured, the global value is considered as the timeout value.

    You can configure the synapse.global_timeout_interval parameter in the <EI_HOME>/conf/synapse.properties file. The default value is 120 seconds. If you want to support endpoint timeout values that are greater than 120 seconds, set the synapse.global_timeout_interval to a value more than 120 seconds. However, the need to set such large timeout values for endpoints is extremely unlikely.

    		synapse.properties120000120000
    synapse.timeout_handler_intervalDuration between two TimeoutHandler executions.The TimeoutHandler is executed every 15 seconds by default. Therefore, the time that call-backs get cleared can deviate up to 15 seconds from the configured value. 
    You can configure the TimeoutHandler execution interval by specifying a required value for synapse.timeout_handler_interval in the <EI_HOME>/conf/synapse.properties file.    		synapse.properties1500015000
  • Set the socket timeout value and individual endpoint timeout values appropriately. Use this formula to set timeout values:

    Socket Timeout > max(Global endpoint timeout, Timeout of individual endpoints)

  • Be sure to set proper values to advanced configuration parameters, although they are optional.
    The happy path should work with the default values, but you might encounter issues in production when the system does not follow the happy path. For example, if you use the default configurations and as an error occurs in your sequence, the endpoint gets suspended immediately and subsequent messages to that endpoint get rejected without being sent to the backend service. This might not be the expected behaviour in every use case. Therefore, it is important to perform endpoint error handling based on the use case.

  • Use the HTTP endpoint for RESTful service invocations. The HTTP endpoint is especially designed to make RESTful service integration easy. For example, it supports url-templates, which is an option to set the http method.

  • For RESTful service integration, use either REST APIs or HTTP endpoints. You can use REST APIs to expose an integration solution as a RESTful service, and use HTTP endpoints to logically represent a RESTful backend service.

...

For a complete guide on troubleshooting issues that you may come across when working with enterprise service bus capabilities, see the Enterprise Service Bus Troubleshoot Guide. For troubleshooting with tooling, see Troubleshooting WSO2 Integration Studio /wiki/spaces/EI6xx/pages/49615315.

Testing

  • Define a test strategy to plan what should be tested in a specific project.
  • Create a test plan covering all functional scenarios and performance tests.
  • Write Jmeter, SoapUI test cases. If applicable always write automation tests.
  • Write java integration tests whenever applicable to automate the test scenarios.
  • Automate web application testing using Selenium.
  • If you have an integration solution, isolate test scenarios of each product as much as possible and test the scenarios as separate units. Then you can write integration tests for the integration scenarios including one or more products using java tools such as Jmeter and Soap UI.
  • For an application development project, you should perform tests throughout the Software Development Life Cycle (SDLC). Make sure that your testing environment is identical to the production environment when you execute test plans. (For example, resource allocation, VM sizes, VMs used for DBs, DB performance tuning, network resources etc in the production environment should be identical in the test environment)
  • Do not rely on test results of a single node test.
  • Test all custom solutions and artifacts that you develop. Never use default ports of the servers when testing custom features.
  • Before you move into production, run load tests on the development and test environments using samples that replicate the production use case.
  • Before you move into production, run a penetration test on the production setup. You need to suggest this to the customer and make arrangements for it beforehand.
  • Run a round of User Acceptance Tests (UAT) against the requirements to ensure that the system satisfies the customer's acceptance criteria. 

  • Document all functional test results and performance test results. Create a document explaining the steps followed, samples used, and the outcome of the tests for both functional test results as well as performance test results. Create a separate document including the summary of all the test results (e.g number of test cases that you executed, observations, summary etc). 
    Following is a sample template for functional test results:

    Test Case IDFunction
    Description
    Test Steps
    Expected Results
    Actual Results
    Status
    Comments

    Following is a sample template for performance test results:

    Test Case IDFunction
    Description
    Test Steps
    Expected Results
    Actual Results
    Duration
    CPU Usage
    Memory Usage
    Status
    Comments
  • Never test on a single node.
  • Conduct proper developer tests.
  • Test use cases with all possible scenarios.
  • It is not sufficient to test only the happy path.
  • Do performance tests.

...

...