Endpoints

Introduction

A message exit point or an endpoint defines an external destination for a message. Typically, this is the address of a proxy service that acts as the front end to the actual service. You can configure the endpoint artifacts with any attributes or semantics needed for communicating with that service. An endpoint could represent a URL, a mailbox, a JMS queue, a TCP socket, etc. along with the settings needed for the connection.

For example, the endpoint for the simple stock quote sample is http://localhost:9000/services/SimpleStockQuoteService.

Endpoints are independent of transports, which allows you to use the same endpoint with multiple transports. When you configure a message mediation sequence or a proxy service to handle the incoming message, you can specify which transport to use and the endpoint to which the message is sent.

Classification of Endpoints

Named Endpoints

A named endpoint can be any one of the listed endpoints. You can reuse these endpoints by referencing them in another endpoint by name using the key attribute. For example, if you have an address endpoint named foo, you can reference the foo endpoint in an indirect using the key attribute: <endpoint key="foo">

Indirect Endpoints

Indirect endpoints are endpoint configurations that refer named endpoints using a key. The key attribute calls the named endpoint at runtime and delegates the message sending to the called endpoint.

<endpoint name="address">
   <address uri="http://localhost:9000/services/SimpleStockQuoteService" format="soap11"/>
</endpoint>
<endpoint key="address">

Indirect endpoints are useful when the actual endpoints are stored in the registry.

Resolving Endpoints

The resolving endpoint refers to an actual endpoint using a dynamic key (which is an XPath expression). The XPath expression dynamically calls another endpoint at runtime. The XPath is evaluated against the current message and the key-expression is calculated at runtime. The resolving endpoint then fetches the actual endpoint using the calculated key and delegates the message sending to the actual endpoint. Shown below is an example of a resolving endpoint.

<send>
  <endpoint key-expression="get-property('Mail')"/>
</send>

List of Endpoints

You can configure the following endpoint types.

Endpoint Description
Address Endpoint Specifies the address URL or EPR (Endpoint Reference) and other attributes of the configuration.
Default Endpoint Defined for adding QoS and other configurations to the endpoint that is resolved by the To address of the message context. All the configurations such as the message format for the endpoint, the method to optimize attachments, and security policies for the endpoint can be specified as in the Address Endpoint. This endpoint differs from the address endpoint because the URI property is not present in the default endpoint.
HTTP Endpoint Allows you to define REST endpoints using URI templates similar to the REST API. The URI templates allow a RESTful URI to contain variables that can be populated during mediation runtime using property values with the uri.var. prefix. An HTTP endpoint can also define the particular HTTP method to use in the RESTful invocation.
Failover Endpoint If an error occurs in an endpoint during message transmission, the message will be lost. The failed message will not be retried again. With some applications, these message losses are acceptable. However, if even rare message failures are not acceptable, use the Failover endpoint.

A Failover Group is a list of leaf endpoints grouped together for the purpose of passing an incoming message from one to another when a failover occurs. The first endpoint in the failover group is considered the primary endpoint. An incoming message is first directed to the primary endpoint, and all other endpoints in the group serve as backups.

If the primary endpoint fails, the next active endpoint is selected as the primary endpoint, and the failed endpoint is marked as inactive. Thus, failover group ensures that a message is delivered as long as there is at least one active endpoint among the listed endpoints. The Micro Integrator switches back to the primary endpoint as soon as it becomes available. This behaviour is known as dynamic failover.

Note: An endpoint failure occurs when an endpoint is unable to invoke a service. An endpoint, which responds with an error is not considered a failed endpoint.
Dynamic Load-Balance Endpoint This endpoint distributes its messages (load) among application members by evaluating the load-balancing policy and any other relevant parameters.

These application members will be discovered using the membershipHandler class, which generally uses a group communication mechanism to discover the application members. The class attribute of the membershipHandler element should be an implementation of org.apache.synapse.core.LoadBalanceMembershipHandler. You can specify membershipHandler properties using the property elements. The policy attribute of the dynamicLoadbalance element specifies the load-balancing policy (algorithm) to be used for selecting the next member that will receive the message.

Note: Currently only the roundRobin policy is supported. The failover attribute determines if the next member should be selected once the currently selected member has failed and defaults to true.
Template Endpoint Template endpoints are created based on predefined Endpoint Templates. Parameters of the endpoint template used as the target are copied to the endpoint configuration. However, you can make modifications by removing some of the copied parameters and/or adding new parameters.
WSDL Endpoint This definition is based on a specified WSDL document. The WSDL document can be specified in 2 ways:
  • As a URI.
  • As an inline definition within the endpoint configuration.
Recepient List Endpoint This endpoint contains multiple child endpoints or member elements. It routes cloned copies of messages to each child recipient. This will assume that all immediate child endpoints are identical in state (state is replicated) or state is not maintained at those endpoints.

Properties

See the topics given below for the list of properties that can be configured for an Endpoint artifact.

Basic Properties

Listed below are the basic properties that used to define an endpoint artifact.

Property Description
Name The name of the endpoint property.
Format The message format for the endpoint. The available values are as follows.
  • Leave As-Is: If this is selected, no transformation is done to the outgoing message.
  • SOAP 1.1: If this is selected the message is transformed to SOAP 1.1.
  • SOAP 1.2: If this is selected the message is transformed to SOAP 1.2.
  • Plain Old XML (POX): If this is selected the message is transformed to plain old XML format.
  • Representational State Transfer (REST): If this is selected, the message is transformed to REST.
  • GET: If this is selected, the message is transformed to a HTTP Get request.
Trace Enabled This enables tracing for the endpoint. You can use trace logs to debug mediation errors.
Statistics Enabled This enables statistics for the endpoint.
Build Message This property only applies to the Failover Endpoint and LoadBalance Endpoint.
Algorithm The algorithm on which the load balancing is based. Round Robin is the default algorithm. You can also load a custom algorithm. Instructions for creating a custom algorithm are included in this article. The policy attribute of the load balance element specifies the load balance policy (algorithm) to be used for selecting the target endpoint or static member.
Note: Currently only the Round Robin policy is supported.
Failover The property determines whether the next endpoint or static member should be selected once the currently selected endpoint or static member has failed and defaults to true.
The failover property is not applicable for session affinity based endpoints and it is always considered as set to false. If it is required to have failover behavior in session affinity based load balance endpoints, list failover endpoints as the target endpoints.
Endpoints Click Endpoints to start adding the failover/loadbalancing endpoints. In the dialog that opens, you can specify the following values:
  • Endpoint Type: The set of endpoints or static members among which the load has to be distributed. These endpoints can belong to any endpoint type. For example, Failover Endpoints can be listed inside the Load-balance endpoint to load balance between failover groups etc.
  • Endpoint Value: The synapse configuration of the endpoint artifact.

Given below are the basic properties for the Template Endpoint:

Property Description
Available Templates Select one of the available templates.
Target Template The endpoint template which should be used to define the endpoint. This is specified by selecting one of the existing templates from the Available Templates list. The parameters to be included in the endpoint you are defining will be copied from the target template. The values for these parameters can be entered in the Template Endpoint Parameters section shown below. Click Delete Parameter to remove a parameter fetched from the target template.
Parameters The parameters of the endpoint. For example, you can add name to add the parameter name, and uri to add the address etc.

Session Management Properties

The following properties only apply to the LoadBalance endpoint:

Property Description
Session Management A session management method from the load balancing group. This element makes the endpoint a session affinity-based load balancing endpoint. If it is specified, sessions are bound to endpoints in the first message and all successive messages for those sessions are directed to their associated endpoints. The possible values are as follows.
  • None: If this is selected, session management is not used.
  • Transport: If this is selected, session management is done on the transport level using HTTP cookies.
  • SOAP: If this is selected, session management is done using SOAP sessions.
  • Client ID: If this is selected, session management is done using an ID sent by the client.
Note: Currently there are two types of sessions supported in SAL endpoints. Namely the HTTP transport based session which identifies the sessions based on HTTP cookies and the client session which identifies the session by looking at a SOAP header sent by the client with the QName "[http://ws.apache.org/ns/synapse]ClientID".
Session Timeout The number of milliseconds after which the session would time out.

Miscellaneous Properties

Property Description
URI EPR of the target endpoint. Following are the sample address URI definitions.
  • HTTP: http://localhost:9000/services/SimpleStockQuoteService
  • JMS: jms:/SimpleStockQuoteService?transport.jms.ConnectionFactoryJNDIName=QueueConnectionFactory&java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory&java.naming.provider.url=tcp://localhost:61616&transport.jms.DestinationType=topic
  • Mail: guest@host
  • VFS: vfs:file:///home/user/directory\ vfs:">file:///home/user/file\ vfs:
  • FIX: fix://host:port?BeginString=FIX4.4&SenderCompID=WSO2&TargetCompID=APACHE
If you want, you can also define the URL with environment properties. Here VAR is the url you need to set as an environment property. This is useful when you need to deploy the endpoint in a container.
Optimize Optimization for the message, which transfers binary data. The available values are as follows.
  • Leave As-Is: If this is selected, there will be no special optimization. The original message will be kept.
  • SwA: If this is selected, the message is optimized as a SwA (SOAP with Attachment) message.
  • MTOM: If this is selected, the message is optimized using a MTOM (message transmission optimization mechanism).
Description
uri-template The URI template that constructs the RESTful endpoint URL at runtime. Insert uri.var. before each variable.
Notes:
  1. If the endpoint URL is an encoded URL, then you need to add legacy-encoding: when defining the uri-template.

    Example:

                                  <http uri-template="legacy-encoding:{uri.var.APIurl}" method="get">
  2. If you add a / between {uri.var.context2}{uri.var.postfix}, it is evaluated as an invalid invocation because {uri.var.postfix} contains a / at the start.

    Example:

                                  <http uri-template="http://{uri.var.host}:{uri.var.port}/{uri.var.context1}/services/{uri.var.context2}{uri.var.postfix}" method="get">
HTTP Method

The HTTP method to use during the invocation of the endpoint. Supported methods are as follows.

  • Get
  • Post
  • Patch
  • Put
  • Delete
  • Options
  • Head
  • Leave-as-is
WSDL URI The URI of the WSDL.
Service The service selected from the available services for the WSDL.
The service and port name containing the target EPR has to be specified with the service and port (or endpoint) properties respectively.
Port The port selected for the service specified in the Service parameter. In a WSDL, an endpoint is bound to each port inside each service.
Add Properties Click Add Property to open the Properties tab and add the required properties.
  • Name: The name of the endpoint property.
  • Value: The value of the endpoint property.
  • Scope: The scope of the property. Possible values are as follows.
    • Default
    • Transport
    • Axis2
    • axis2-client

Basic Auth Properties

The following properties only apply to HTTP endpoint.

The basicAuth element contains the following parameters that are used to configure basic authentication for the endpoint.

Property Description
username User's username to invoke the defined endpoint.
password User's password to invoke the defined endpoint.

The following is an HTTP endpoint configured with basic authentication.

<endpoint name="FoodEP" xmlns="http://ws.apache.org/ns/synapse">
    <http method="get" uri-template="http://localhost:9192/service/foodservice">
        <authentication>
            <basicAuth>
                  <username>admin</username>
                  <password>admin</password>
            </basicAuth>
        </authentication>
    </http>
</endpoint>

OAuth Properties

The following properties only apply to HTTP endpoint.

Note

  1. You can also use environment variables for these parameters. For more information, see Injecting Parameters.
  2. You can use dynamic values for OAuth configurations such as XPATH, JSON expressions or vault-lookup. For more information, see Define dynamic expressions.
  3. You can send additional parameters as well in the OAuth request body. For more information, see Send additional parameters in the OAuth request body.

Tip

You can configure the OAuth cache timeout (in seconds) by setting the following property in the <MI_HOME>/conf/synapse.properties file. The default timeout will be 3000 seconds. synapse.endpoint.http.oauth.cache.timeout=500

Authorization Code/Refresh Token grant type

The authorizationCode element contains the following parameters that are used to configure OAuth for the endpoint.

Property Description Required
clientId Client ID that is provided by the third-party service when you registered your application. Yes
clientSecret Client Secret that is provided by the third-party service when you registered your application. Yes
refreshToken Refresh token obtained from the third-party service by using Authorization Code grant flow. Yes
tokenUrl Token endpoint provided by the third-party service to obtain access tokens. Yes
authMode Indicate how the client credentials are passed to the token endpoint. If the authMode is payload they are passed in the request payload. If the authMode is header the client credentials are passed in the authentication header, which is the default. Optional

The following is an HTTP endpoint configured with refresh token grant type.

<endpoint name="FoodEP" xmlns="http://ws.apache.org/ns/synapse">
    <http method="get" uri-template="http://localhost:9192/service/foodservice">
        <authentication>
            <oauth>
                <authorizationCode>
                    <clientId>K2RbnGP7VS</clientId>
                    <clientSecret>9zLrZAYR5b</clientSecret>
                    <refreshToken>y2Ne4Fccrj</refreshToken>
                    <tokenUrl>http://localhost:8678/token</tokenUrl>
                </authorizationCode>
            </oauth>
        </authentication>
    </http>
</endpoint>

Client Credentials grant type

The clientCredentials element contains the following parameters that are used to configure OAuth for the endpoint.

Property Description Required
clientId Client ID provided by the third-party service when you registered your application. Yes
clientSecret Client Secret provided by the third-party service when you registered your application. Yes
tokenUrl Token endpoint provided by the third-party service to obtain access tokens. Yes
authMode Indicate how the client credentials are passed to the token endpoint. If the authMode is payload they are passed in the request payload. If the authMode is header the client credentials are passed in the authentication header, which is the default. Optional

The following is an HTTP endpoint configured with the client credentials grant type.

<endpoint name="FoodEP" xmlns="http://ws.apache.org/ns/synapse">
    <http method="get" uri-template="http://localhost:9192/service/foodservice">
        <authentication>
            <oauth>
                <clientCredentials>
                    <clientId>K2RbnGP7VS</clientId>
                    <clientSecret>9zLrZAYR5b</clientSecret>
                    <tokenUrl>http://localhost:8678/token</tokenUrl>
                </clientCredentials>
            </oauth>
        </authentication>
    </http>
</endpoint>

Password grant type

The passwordCredentials element contains the following parameters that are used to configure OAuth for the endpoint.

Property Description Required
clientId Client ID provided by the third-party service when you registered your application. Yes
clientSecret Client Secret provided by the third-party service when you registered your application. Yes
username Username of the user. Yes
password Password of the user. Yes
tokenUrl Token endpoint provided by the third-party service to obtain access tokens. Yes
authMode Indicate how the client credentials are passed to the token endpoint. If the authMode is payload they are passed in the request payload. If the authMode is header the client credentials are passed in the authentication header, which is the default. Optional

The following is an HTTP endpoint configured with the password grant type.

<endpoint name="FoodEP" xmlns="http://ws.apache.org/ns/synapse">
    <http method="get" uri-template="http://localhost:9192/service/foodservice">
        <authentication>
            <oauth>
                <passwordCredentials>
                    <clientId>K2RbnGP7VS</clientId>
                    <clientSecret>9zLrZAYR5b</clientSecret>
                    <username>internal-user</username>
                    <password>abc@123</password>
                    <tokenUrl>http://localhost:8678/token</tokenUrl>
                </passwordCredentials>
            </oauth>
        </authentication>
    </http>
</endpoint>

Send additional parameters in the OAuth request body

By default the grant_type, client_id, and client_secret parameters are sent in the OAuth request body. To send additional parameters you can define them as a list of parameters under the requestParameters tag as shown in the example below.

<endpoint name="FoodEP" xmlns="http://ws.apache.org/ns/synapse">
    <http method="get" uri-template="http://localhost:9192/service/foodservice">
        <authentication>
            <oauth>
                <clientCredentials>
                    <clientId>K2RbnGP7VS</clientId>
                    <clientSecret>9zLrZAYR5b</clientSecret>
                    <tokenUrl>http://localhost:8678/token</tokenUrl>
                    <requestParameters>
                        <parameter name="scope">read_only</parameter>
                        <parameter name="user_role">tester</parameter>
                    </requestParameters>
                </clientCredentials>
            </oauth>
        </authentication>
    </http>
</endpoint>

Define dynamic expressions

You can use dynamic values for OAuth configurations such as XPATH, JSON expressions or vault-lookup to get data from a secure vault. Make sure you define the elements within curly brackets.

<endpoint name="FoodEP" xmlns="http://ws.apache.org/ns/synapse">
    <http method="get" uri-template="http://localhost:9192/service/foodservice">
        <authentication>
            <oauth>
                <clientCredentials>
                    <clientId>K2RbnGP7VS</clientId>
                    <clientSecret>{hashicorp:vault-lookup('secret/hello', 'clientSecret')}</clientSecret>
                    <tokenUrl>http://localhost:8678/token</tokenUrl>
                    <requestParameters>
                        <parameter name="scope">{ctx:oauth_scope}</parameter>
                    </requestParameters>
                </clientCredentials>
            </oauth>
        </authentication>
    </http>
</endpoint>

Quality of Service Properties

QoS (Quality of Service) aspects such as WS-Security and WS-Addressing may be enabled on messages sent to an endpoint using enableSec and enableAddressing elements. Optionally, the WS-Security policies could be specified using the policy attribute.

Property Description
enableSec [policy="key"] This enables WS-Security for the message which is sent to the endpoint. The optional policy attribute specifies the WS-Security policy.
enableAddressing [version="final | submission"] [seperateListener=" true | false"] This enables WS-Addressing for the message that is sent to the endpoint. User can have a separate listener with version final or submission.

Endpoint Error Handling Properties

Errors that can occur at endpoints can be specifically configured using the endpoint error handling properties.

The last step of message mediation is to send the message to a service provider through a listening service endpoint. During this process, transport errors can occur. For example, the connection might time out, or it might be closed by the actual service. Therefore, endpoint error handling is a key part of any successful Micro Integrator deployment.

Messages can fail or be lost due to various reasons in a real TCP network. When an endpoint error occurs, if the Micro Integrator is not configured to accept the error, it will mark the endpoint as failed, which leads to a message failure. By default, the endpoint is marked as failed for quite a long time, which can result in severe message loss.

To avoid message loss, you configure error handling at the endpoint level. You should also run a few long-running load tests to discover errors and fine-tune the endpoint configurations for errors that can occur intermittently due to various reasons.

At any given time, the state of the endpoint can be one of the following. During an endpoint error, the endpoint will transition between these states and, if required, will initiate a fault sequence.

State Description
Active Endpoint is running and handling requests.

When the Micro Integrator starts, endpoints are in "Active" state until the user sets it to OFF state, or until an error occurs.

In the endpoint error handling configuration, error codes are allocated to a particular endpoint state. Therefore, when the error occurs, the endpoint will either remain in Active state or change to Timeout or Suspended depending on the error code. The endpoint first checks whether the error is a Timeout error, and if not, it checks whether it is a suspended error. If the error is not defined for either "Timeout" or "Suspended," the error will be ignored and the endpoint will remain active.
Timeout Endpoint encountered an error but can still send and receive messages. If it continues to encounter errors, it will be suspended.

When an endpoint is in the Timeout state, it will continue to attempt to receive messages until one message succeeds or the maximum retry setting has been reached. If the maximum is reached at which point, the endpoint is marked as Suspended. If one message succeeds, the endpoint is marked as Active.

For example, let's assume the number of retries is set to 3. When an error occurs and the endpoint is set to the "Timeout" state, the Micro Integrator can try to send up to three more messages to the endpoint. If the next three messages sent to this endpoint result in an error, the endpoint is put in the Suspended state. If one of the messages succeeds before the retry maximum is met, the endpoint will be marked as Active.
Suspended Endpoint encountered errors and cannot send or receive messages. Incoming messages to a suspended endpoint result in a fault.

When an endpoint is put into this state, the Micro Integrator waits until after an initial duration has elapsed (default is 30 seconds) before attempting to send messages to this endpoint again. If the message succeeds, the endpoint is marked as Active. If the next message fails, the endpoint is marked as Suspended or Timeout depending on the error, and the Micro Integrator waits before retrying messages using the following formula: Min(current suspension duration * progressionFactor, maximumDuration).

You configure the initial suspension duration, progression factor, and maximum duration as part of the suspendOnFailure settings. On each retry, the suspension duration increases, up to the maximum duration.
OFF Endpoint is not active. To put an endpoint into the OFF state, or to move it from OFF to Active, you must use JMX.

The following is the configuration for the address endpoint. Note that you can apply the same configuration for WSDL endpoints to create error configurations as well. The error handling configuration are as follows:

  • timeout
  • markForSuspension
  • suspendOnFailure

<address uri="endpoint address" [format="soap11|soap12|pox|get"]
    [optimize="mtom|swa"] [encoding="charset encoding"]
    [statistics="enable|disable"] [trace="enable|disable"]>
    <enableRM [policy="key"]/>?
        <enableSec [policy="key"]/>?
        <enableAddressing [version="final|submission"] [separateListener="true|false"]/>?

        <timeout>
                <duration>timeout duration in seconds</duration>
                <responseAction>discard|fault|never</responseAction>
        </timeout>?

        <markForSuspension>
                [<errorCodes>xxx,yyy</errorCodes>]
                <retriesBeforeSuspension>m</retriesBeforeSuspension>
                <retryDelay>d</retryDelay>
        </markForSuspension>

        <suspendOnFailure>
            [<errorCodes>xxx,yyy</errorCodes>]
                <initialDuration>n</initialDuration>
                <progressionFactor>r</progressionFactor>
                <maximumDuration>l</maximumDuration>
        </suspendOnFailure>
</address>

Timeout Properties

The timeout element contains the following parameters that are used to consider an endpoint as "timeout" by not being responsive for a specified time duration.

Property

Description

Timeout Duration

 Connection timeout interval. If the remote endpoint does not respond in this time, it will be marked as "Timeout." This can be defined as a static value or as a dynamic value.
Specify the value in miliseconds or an XPATH expression. Default value is 60000 milliseconds.

Timeout Action (responseAction)

When a response comes to a timed out request, this property specifies whether to discard it or invoke the fault handler. If you select "never", the endpoint remains in the "Active" state. This parameter is used to specify the action to perform once an endpoint has timed out. The available options are as follows:

  • Never: The endpoint will never time out. This is the default setting.
  • Discard: If this is selected, the responses which arrive after the endpoint has timed out will be discarded.
  • Fault: If this is selected, a fault sequence is triggered when the endpoint is timed out.
Note: You can specify a value that is 1 millisecond less than the time duration you specify for the endpoint time out for the synapse.timeout_handler_interval property in the MI_Home/conf/ei.toml file. This would minimise the number of late responses from the backend.

MarkForSuspension Properties

The markForSuspension element contains the following parameters that are used to mark an endpoint as "suspended" after the time out duration is reached.

Property

Description

Retry Error codes (errorCodes)

 A (comma-separated) list of error codes. If these error codes are received from the endpoint, the request will be subjected to a timeout.
The defined error codes move the endpoint into the "Timeout" state, thereby marking it for suspension. After the number of defined retriesBeforeSuspension exceeds, the endpoint will be suspended.
Default: 101504, 101505.
See the SynpaseConstant class for a list of available error codes.

Retry Count (retriesBeforeSuspension)

 The number of times the endpoint should be allowed to retry sending the response before it is marked for suspension. In the "Timeout" state, this number of requests minus one can be tried and failed before the endpoint is marked as "Suspended". This setting is per endpoint (not per message), so several messages can be tried in parallel and failed and the remaining retries for that endpoint will be reduced. Default: 0.
Note: If you do not specify these error codes, or if you do not specify any error codes under suspendOnFailure, by default, the "HTTP Connection Closed" (i.e., 101504) and "HTTP Connection Timeout" (i.e., 101505) errors act as "Timeout" errors, and all other errors will move the endpoint into the "Suspended" state after retrying.

Retry Delay (retryDelay)

 The time to wait between the last retry attempt and the next retry. Default: 0.

SuspendOnFailure Properties

Leaf endpoints (Address and WSDL) can be suspended if they are detected as failed endpoints. When an endpoint is in suspended state for a specified time duration following a failure, it cannot process any new messages. The following formula determines the wait time before the next attempt.

next suspension time period = Max (Initial Suspension duration * (progression factor* try count *), Maximum Duration)

All the variables in the above formula are configuration values used to calculate the try count. Try count is the number of tries carried out after the endpoint is suspended. The increase in the try count causes an increase in the next suspension time period. This time period is bound to a maximum duration.

Property

Description

Suspend Error Codes (errorCodes)

 Comma-separated list of error codes. This parameter allows you to select one or more error codes from the list of values. If any of the selected errors are received from the endpoint, the endpoint will be suspended.
Only these defined error codes will directly send the endpoint into the "Suspended" state. Any other error code, which is not specified under MarkForSuspension, will keep the endpoint in the "Active" state without suspending.
If you do not specify these error codes, by default, all the errors except the errors specified in markForSuspension will suspend the endpoint.

Suspend Initial Duration (initialDuration)

 The time duration (in miliseconds) for which the endpoint will be suspended when one or more suspend error codes are received from it for the first time. After an endpoint gets "Suspended", it will wait for this amount of time before trying to send the messages coming to it. All the messages coming during this time period will result in fault sequence activation.
Default: 30000.

Suspend Maximum Duration

The maximum time duration (in miliseconds) for which the endpoint is suspended when the suspend error codes are received.

Suspend Progression Factor (progressionFactor)

 The progression factor for the geometric series. The duration to suspend can vary from the first time suspension to the subsequent time. The factor value decides the suspend duration variance between subsequent suspensions.
The endpoint will try to send the messages after the initialDuration. If it still fails, the next duration is calculated as:Min(current suspension duration * progressionFactor, maximumDuration).
Default: 1.
Sample Configuration:
<endpoint name="Sample_First" statistics="enable" >
    <address uri="http://localhost:8280/myendpoint" statistics="enable" trace="disable">
        <timeout>
            <duration>60000</duration>
        </timeout>

        <markForSuspension>
            <errorCodes>101504, 101505</errorCodes>
            <retriesBeforeSuspension>3</retriesBeforeSuspension>
            <retryDelay>1</retryDelay>
        </markForSuspension>

        <suspendOnFailure>
            <errorCodes>101500, 101501, 101506, 101507, 101508</errorCodes>
            <initialDuration>1000</initialDuration>
            <progressionFactor>2</progressionFactor>
            <maximumDuration>60000</maximumDuration>
        </suspendOnFailure>

    </address>
</endpoint>

In this example, 101504 and 101505 errors move the endpoint into the "Timeout" state. At that point, three requests can fail for one of these errors before the endpoint is moved into the "Suspended" state. Additionally, 101500, 101501, 101506, 101507, and 101508 errors will move the endpoint directly into the "Suspended" state. If a 101503 error occurs, the endpoint will remain in the "Active" state as you have not specified it under suspendOnFailure. The default setting to suspend the endpoint for all error codes, except the ones specified under markForSuspension, will apply only if you do not specify error codes under suspendOnFailure.

When the endpoint is first suspended, the retry happens after one second. Because the progression factor is 2, the next suspension duration before retry is two seconds, then four seconds, then eight, and so on until it gets to sixty seconds, which is the maximum duration we have configured. At this point, all subsequent suspension periods will be sixty seconds until the endpoint succeeds and is back in the Active state, at which point the initial duration will be used on subsequent suspensions.

WS Addressing Properties

Property

Description

WS-Addressing

Adds WS-Addressing headers to the endpoint.

Separate Listener

The listener to the response will be a separate transport stream from the caller.

WS-Security

Adds WS-Security features as described in a policy key (referring to a registry location).
Non Retry Error Codes

When a child endpoint of a failover endpoint or load-balance endpoint fails for one of the error codes specified here, the child endpoint will be marked for suspension and the request will not be sent to the next endpoint in the group.
Retry Error Codes When adding a child endpoint to a failover endpoint or load-balance endpoint, you can specify the error codes that trigger this node to be retried instead of suspended when that error is encountered. This is useful when you know that certain errors are transient and that the node will become available again shortly. Note that if you specify an error code as a Retry code on one node in the group but specify that same code as a Non Retry error code on another node in the group, it will be treated as a Non Retry error code for all nodes in the group.
Top