Policies

Implementation details for using WSRR as the Policy Authoring Point and WebSphere® DataPower® as the Policy Enforcement Point when you create mediation policies.

Policies in WSRR

You can use WSRR to create all of the SOA policies, including SLA (Service Level Agreement) policies, mediation policies, monitoring policies, and custom policies. Using the Business Space user interface, you can create, update, or delete a policy document in WSRR. The policy document can contain a policy expression that specifies a number of policies for a particular policy domain. Alternatively you can create a policy document that assembles existing policies from other documents. Individual policies are referred to using policy identifiers, which you specify when you add policies to your document. A policy expression represents the declaration of a policy and is equivalent to a <wsp:Policy> element in a WS-Policy document.

To create a mediation policy in Business Space, see Authoring new mediation policies.

Mediation policy assertions

Service Level Agreements (SLAs) originate from a business requirement that the quality of service that is provided by a service meets a specified standard. As a service is designed, functional requirements are created to guide the logic of what the service does. Non-functional requirements are specified in parallel as part of the analysis and design of that service to designate the quality of service that the service is expected to provide. For example, the business might have a service that supplies information in response to a customer internet query. The target is to return the response within 3 seconds. As part of the engineering of the end-to-end transaction, it is determined that this service must return its information within 2 seconds to meet the business non-functional requirements.

You can write a policy that implements runtime checks on the performance of the service and acts when requirements are met to guarantee that the service meets its SLA. For example, you might have a service primary endpoint that is normally (95% of the time) able to provide service response within two seconds. The SOA architect creates a secondary endpoint on another server that can be used as a hot standby for primary endpoint outages, but is also authorized to be used for overflow traffic when the primary endpoint is not able to keep up with the transaction load. You can write a policy that checks the service response time and reroutes traffic when necessary to meet the SLA.

Another example where SLAs are maintained through runtime policy is a situation where a service is responding to transactions that have various consumers, each with a different level of priority. A simple example might have “gold” and “bronze” customers, where the business guarantees only a specific quality of service for the “gold” customers. In this example, you can check whether the consumer is “gold” and reroute to the secondary endpoint, leaving the “bronze” customer to deal with a slower response time. The business decided because “bronze” customers provide insufficient incremental revenue to justify the expense of engineering a response time to meet the SLA of the “gold” customers.

In a third example, you might have a situation where a service does the best it can, but when it determines that it is under load, queues or even rejects messages from low priority consumer services. One example is when a batch routine floods the system with consumer requests at an unexpected time. To protect the quality of service, you can create a runtime policy that is in effect during business hours only, and that rejects all batch requests during this period.

More generically, mediation policy allows for validation and transformation on the incoming message from the client (consumer) before presentation to the server (provider).

Policies support this type of message validation and transformation. Policies can be specified for a provider service only, for a specific consumer-provider pair, or for Anonymous consumers for a provider service. Policies for Anonymous customers provide a way of defining a default policy that applies only to consumers for which no other policies apply. Using this feature allows policies to be specified for rogue consumers that do not identify themselves. Such consumer services could then have their transactions rejected. This can be useful to prevent denial of service attacks from consumer hackers attempting to flood the system with transactions meant to bring down a provider service.

Mediation policy conditions

Mediation assertions can be made that allow runtime policy to control the SLA of the service, transformation of messages from consumer to provider, or to validate the message schema of the consumer message.

SLA policy conditions, a special type of mediation policy, effectively allows for a classic if-then-else construct with a condition and then a set of actions to be performed depending on how the condition evaluates. Specifying a condition is optional. If no condition is specified, it is equivalent to the logical condition that evaluates to True, and any actions that are specified are enforced accordingly.

The condition, if specified, must consist of a Boolean expression or a schedule specification, or the condition can include both.

Schedule

The schedule, if specified, identifies when the policy is in effect. The date and time are evaluated by the local Policy Enforcement Point and the time zone that is used is that of the Policy Enforcement Point. If no schedule is specified, the policy starts as soon as it is downloaded from the Policy Authoring Point to the Policy Enforcement Point, and continues indefinitely.

The schedule defines an optional start date and an optional stop date, an optional daily timeframe, and an optional list of weekdays. For example, a schedule can be defined as being effective from October 1st 2012 to October 30th 2012, from 8 a.m. to 5 p.m. on Wednesdays and Sundays.

The parameters for the schedule that can be specified are as follows:
  • StartDate - This optional attribute specifies in xs:date format the date at which the schedule becomes effective. StartDate is inclusive and if this attribute is not present, the schedule becomes effective immediately today. (Click the xs:time hyperlink to understand this industry standard).
  • StopDate - This optional attribute specifies in xs:date format the date at which the schedule stops being effective. StopDate is exclusive and the specified date must be after the start date. When the stop date is before or the same as the start date, the schedule is never effective. If this attribute is not present, the schedule is effective indefinitely.
  • Daily - This optional element specifies the daily timeframe during which the schedule is effective. If this element is not present, the schedule is effective all day.
    • StartTime – If Daily is specified, then this attribute is required. It specifies in xs:time format the time at which the schedule starts daily. (Click the xs:time hyperlink to understand this industry standard).
    • StopTime - If Daily is specified, then this attribute is required. It specifies in xs:time format the time at which the schedule stops daily. StopTime is exclusive and if the specified time is earlier than or the same as the daily start time, the schedule stops at the specified stop time on the next day.
  • Weekdays - This optional element specifies the days of the week included in the schedule. If this element is not present, every day of the week is included in the schedule. This element affects only the start of the daily timeframe, as schedules are allowed to run past midnight. For example, if a schedule is set to start at 11 p.m. and run for 2 hours on Wednesdays, the schedule effectively ends on Thursday at 1 a.m.
    • Days - If Weekdays is specified, then this attribute is required. It lists the weekdays included in the schedule, as a list of names separated with the plus sign ('+'); for example, “Monday+Tuesday+Wednesday+Thursday+Friday+Saturday+Sunday”.

Mediation policy condition expression

The condition expression, if specified, is a non-repeating element that specifies a Boolean expression.

The expression comprises three parameters: Attribute, Operator, and Value, plus optional Interval and Limit parameters. If the application of the Operator on the Attribute and the Value, plus the Interval and Limit when appropriate, evaluates to True, the expression evaluates to True. The Limit element is only used with the HighLow and TokenBucket operators. If not specified, the value of Limit is 0. If Interval is not specified, the default is 60 seconds.

The parameters for Expression that can be specified are as follows:
  • Attribute - The following table summarizes the defined attributes and their type.
    Table 1. Defined attributes
    Attribute Description and Type
    ErrorCount The number of faults that are observed during this monitoring interval.
    MessageCount The number of actual messages that are intercepted during the monitoring interval.
    InternalLatency The internal latency (processing time) in seconds.
    BackendLatency The appliance-to-server latency in seconds.
    TotalLatency The sum of back-end and internal latency in seconds.
  • Operator - The following table summarizes the available operators and their meaning:
    Table 2. Operators
    Operator Meaning
    GreaterThan A simple numeric algorithm that evaluates to True when the Attribute is greater than the defined Value.
    LessThan A simple numeric algorithm that evaluates to True when Attribute is less than the defined Value.
    TokenBucket A rate-based algorithm that allows bursting. The algorithm consists of a bucket with a maximum capacity of Limit tokens. The bucket refills at a constant rate of Value tokens per Interval, while for each unit of Attribute a token is removed. This algorithm evaluates to True when there are no tokens in the bucket, and evaluates to False otherwise. Here is an example to help explain the algorithm: Assume Limit=100, Value=5, Interval=1 second, and the Attribute=MessageCount.
    1. The bucket starts full with a maximum capacity of 100 tokens
    2. When a message arrives, the algorithm checks whether the bucket holds any tokens:
      1. If it does, the algorithm evaluates to False and one token is removed from the bucket
      2. If it does not, the algorithm evaluates to True.
    3. All the while, every second, the algorithm adds 5 tokens back to the bucket as room permits.
    HighLow An algorithm that evaluates to True when Attribute reaches the high threshold specified as the Value and then continues to evaluate to True until Attribute reaches the low threshold specified as the Limit.
  • Value – This is a positive integer element. “0” is valid.
  • Interval - This optional element defines in xs:duration format the time interval, used as a sliding window, to measure the wsme:Attribute when evaluating the expression,. If not specified, the interval used is 60 seconds. If specified, a reasonable value must be specified, taking into account the configured capabilities of the Policy Enforcement Point. That is, the higher this value, the more memory is needed by the Policy Enforcement Point to keep track of the attribute. (Click the xs:duration hyperlink to understand this industry standard.)
  • Limit - This optional integer element defines the additional Limit argument required when wsme:Operator is TokenBucket or HighLow. The unit depends on the wsme:Operator specified.

    When wsme:Operator is HighLow it defines the low threshold while wsme:Value defines the high threshold. The specified threshold must be lower than that of wsme:Value. When not specified the default Limit is 0.

    When wsme:Operator is TokenBucket it defines the maximum size of the burst, or maximum number of tokens in the bucket, while Value specifies the rate at which the bucket is refilled, in number of tokens per Interval. When not specified the default Limit is 0 and TokenBucket is then equivalent to a GreaterThan operation.

Mediation policy actions

The Mediation Action element specifies the actions to be taken. Although the syntax allows many combinations, not all of them make sense and when conflicting actions are specified, such as asking for a message to be both queued and rejected, the behavior is rejected by the Policy Authoring Point. The mediation policy actions allowed are:
  • QueueMessage – This action specifies that transactions are queued when the logical condition is met. Message processing does not recommence until the logical condition is no longer met. The queue methodology and any associated timeouts are as defined by the Policy Enforcement Point, in this case WebSphere DataPower. When several actions are specified within a single Action element, QueueMessage must be the first action.
  • RejectMessage – This action specifies that transactions are rejected when the logical condition is met. Transactions continue to be rejected until the logical condition is no longer met. When transactions are rejected, a SOAP fault is returned to the client (consumer) service. When several actions are specified within a single Action element, RejectMessage must be the first action. QueueMessage and RejectMessage are mutually exclusive.
  • Notify - This optional element specifies that a notification is produced when the logical condition is met. For DataPower, a message is written to the DataPower system log.
  • RouteMessage - This optional element specifies that messages is routed to specified endpoint destination when the logical condition is met. Messages continue to be routed to the specified endpoint until the logical condition is no longer met.
    • EndPoint – This parameter is required when an action of RouteMessage is specified. The endpoint value supported can be an IP address, hostname, or virtual host; such as load balancer group.
  • ValidateMessage - This optional element specifies that messages is validated against the specified grammars. Messages are rejected when validation fails. Either XSD or WSDL must be specified as a subparameter if ValidateMessage is specified. SCOPE is optional, and if not specified, SOAPBody is used for the validation.
    • XSD - Specifies that messages are validated against the XML schema identified by the URI it contains.
    • WSDL - Specifies that messages are validated against the Web services description (WSDL) identified by the URI it contains.
    • SCOPE – Specifies what part of the message is validated. The following table lists the possible values and what they mean:
      Table 3. ValidateMessage elements
      Value Description
      SOAPBody The contents of the SOAP Body element, without special processing for SOAP faults. (Default)
      SOAPBodyOrDetails The contents of the detail element for SOAP faults, and the contents of the Body otherwise.
      SOAPEnvelope The entire SOAP message, including the envelope.
      SOAPIgnoreFaults No validation if the message is a SOAP fault, the contents of the SOAP Body otherwise.
  • ExecuteXSL - Specifies that an XSL transform is performed with the specified style sheet and parameters. Transactions are rejected when the execution fails. Style sheet information must be specified, while parameters are optional, and must be specified as needed by the particular style sheet specified.
    • Stylesheet - Specifies that the transform operation uses the stylesheet specified by the contained URI. The style sheet MUST be an XSLT file.
    • Parameter - This optional, repeating element specifies a style sheet parameter to be used for the ExecuteXSL operation.
      • Name – This attribute is required for each corresponding Parameter parameter and specifies the name of the parameter.
      • Value - This attribute is required for each corresponding Name parameter and specifies the value of the parameter.

Concept Concept

Feedback

Timestamp icon Last updated: Thursday, 3 July 2014
http://publib.boulder.ibm.com/infocenter/prodconn/v1r0m0/topic/com.ibm.scenarios.soawdpwsrr25.doc/topics/csoa2_SOA_implementation.htm