Webservice Behaviour

A webservice behaviour provides the means group together specific attributes of webservices. A behaviour is usually associated with a website or web application, since most services from a particular site will act similarly.

Webservice behaviours presently allow you to specify:

  • Base Url
  • Additional Request Headers
  • Authentication
  • Request Throttling
  • Request Pagination
  • Tracing

ID

The ID of the webservice behaviour.

Description

A friendly name.

Base Url

The base Url. This value is combined with the URL of a Reader, Writer or Lookup, providing a central place to define the site to query or post.

This value is optional and the full Url may be individually specified.

Error Message Path

If a webservice responds with an error, the value specified here should point to a node or array containing any error messages.

The value specified here, should be in either JPath or XPath form, dependent on the expected format of a response following an error. I.e. If the webservice is JSON based, the value should be a JPath, otherwise if the webservice is Xml, the value should be XPath.

If this value is left empty, the error message will use the entire response (per the steps below).

General Error Handling

The following steps are taken whenever an erroneous response is returned from a webservice.

  • If the webservice responds with an application/data related error (e.g. a request to update an invalid customer, or invalid item) then the following steps for extracting the error are performed:
    • The response from an erroneous webservice call will be parsed to determine whether the response is either JSON or Xml.
    • If the response is either JSON or Xml, the response will stripped the response from any JSON or Xml specific syntax and a formatted textual response comprising of the node names and values will be constructed.
    • If an error message path has been specified, but the node(s)/array cannot be found from the response, the formatted error message will be made from the entire response.
    • If the response is neither JSON nor Xml, the entire response from the webservice will be the error message.
  • If the error is a transient or network error e.g. the service is down, cannot be reached, invalid URL, then the error will made from the error returned by windows.

Http Headers

Http Headers to be sent with every request associated with this behaviour can be defined here.

Authentication Type

  • None
    • No authentication will be made.
  • Basic Authentication
    • Uses basic authentication.
  • OAuth
    • Use OAuth 2.0 authentication.

Authentication Id

Select authentication to use for the site. When authentication type is ‘None’ this drop down will be empty.

Request Throttling

  • None
    • Requests will be made synchronously as fast as possible. I.e. One request will be made immediately after the reply is received from the previous request.
  • Leaky Bucket

    • Requests will be made synchronously as fast as possible until a reply is received from the server indicating that too many requests have been made in a single period.

      When this threshold has been reached, IMan will throttle/limit the number of requests to a specified number per second.

      The leaky bucket makes requests and up to the maximum requests per second. The number of requests which can be made is released from the bucket at a set rate i.e. the requests per second. When the bucket runs out of requests, the leaking stops, and requests can be made as quickly as possible until the bucket fills. Once full subsequent requests can be mode once the bucket has begin to empty i.e. as space becomes available for further requests.

      It is important to note the throttling is isolated to the integration which is presently running. IMan does not keep a track of the number of requests across separate integrations. E.g. IMan would not be able to throttle requests to X per day if an integration was run more than once per day.

Throttling Http Status Code

This is the HTTP status code returned by the server once a limit has been reached.

The standard is to return a 429 'Too Many Requests'.

When no throttling has been selected this field is not present.

Throttling Request Per Second

This is the number of requests per second IMan will to the webservice once the limit has been reached i.e. once a request has failed where the http status on the response is the ttrottling status code.

When no throttling has been selected this field is not present.

PAGING

See Paging section.

Trace

When enabled all requests and responses will be logged to a file in \IMan\Debug\WSTRACE-<ID>.log where the <ID> is replaced with the Behaviour Id.