Policies

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

Policies in WSRR

WSRR can be used to author all of the SOA policies, including SLA (Service Level Agreement) policies, mediation policies, monitoring policies, custom policies, and other policy domains that shall be supported in the future. 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 which 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 adding 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 policies.

Mediation policy assertions

Service Level Agreement’s (SLAs) should originate from a requirement of the business that the quality of service provided by a service must meet a specified standard. As a service is being designed, functional requirements are created to guide the logic of what the service does. Non-functional requirements should be specified in parallel as part of the analysis and design of that service to designate the quality of service that 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 in order to meet the business non-functional requirements.

We can write a policy that implements runtime checks on the performance of the service and take action when the SLA is not being met so as to guarantee that the service meets its SLA. For example, we might have a service primary endpoint that is normally able to (95% of the time) provide service response within 2 seconds. The SOA architect has created a secondary endpoint on another server that is normally 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. We 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 a variety of consumers, each with a different level of priority. A simple example might have “gold” and “bronze” customers, where we only guarantee a specific quality of service for our “gold” customers. In this example, we can check if the consumer is “gold” and reroute to our secondary endpoint, leaving the “bronze” customer to deal with a slower response time. The business made the decision 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, we might have a situation where a service will do the best it can, but when it determines that it is under load, it will queue or even reject messages from low priority consumer services. One example of this is when a batch routine floods the system with consumer requests at an unexpected time. In order to protect the quality of service, we can create a runtime policy that is in effect during business hours only, and that will reject all batch requests during this period.

More generically, mediation policy allows for validation and transformation on the incoming message from the client (consumer) prior to 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 which only applies to consumers for which no other policies apply. Using this feature allows policies to be specified for rogue consumers that don’t 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 evaluating to True and any actions 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 specified are evaluated by the local Policy Enforcement Point and the time zone 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 the date at which the schedule becomes effective in xs:date format. StartDate is inclusive and if this attribute is not present, the schedule becomes effective immediately today.
    Note: Click the xs:date hyperlink to understand this industry standard.
  • StopDate - This optional attribute specifies the date at which the schedule stops being effective in xs:date format. StopDate is exclusive and the specified date should 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 the time at which the schedule starts daily in xs:time format. (Note: click on the xs:time hyperlink to understand this industry standard).
    • StopTime - If Daily is specified, then this attribute is required. It specifies the time at which the schedule stops daily in xs:time format. 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 only affects the start of the daily timeframe as schedules are allowed to run passed midnight. For example, if a schedule is set to start at 11 p.m. and run for 2 hours on Wednesdays, the schedule will effectively end 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 a required three parameters consisting of Attribute, Operator, and Value, plus an optional Interval and Limit. 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 may 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 observed during this monitoring interval.
    MessageCount The number of actual messages 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 the time interval, used as a sliding window, to measure the wsme:Attribute when evaluating the expression, in xs:duration format. If not specified, the interval used is 60 seconds. If specified, a reasonable value should 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.
    Note: 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 this defines the low threshold while wsme:Value defines the high threshold. The specified threshold should be lower than that of wsme:Value. When not specified the default Limit is 0.

    When wsme:Operator is TokenBucket this 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 will be rejected by the Policy Authoring Point. The mediation policy actions allowed are:
  • QueueMessage – This action specifies that transactions will be queued when the logical condition is met. Message processing will not re-commence 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 should be the first action.
  • RejectMessage – This action specifies that transactions will be rejected when the logical condition is met. Transactions will continue to be rejected until the logical condition is no longer met. When transactions are rejected, a SOAP fault will be returned to the client (consumer) service. When several actions are specified within a single Action element, RejectMessage should be the first action. QueueMessage and RejectMessage are mutually exclusive.
  • Notify - This optional element specifies that a notification will be produced when the logical condition is met. For WebSphere DataPower, a message will be written to the DataPower system log.
  • RouteMessage - This optional element specifies that messages will be routed to specified endpoint destination when the logical condition is met. Messages will 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 shall be validated against the specified grammars. Messages shall be rejected when validation fails. Either XSD or WSDL must be specified as a sub-parameter if ValidateMessage is specified. SCOPE is optional, and if not specified, SOAPBody is used for the validation.
    • XSD - Specifies that messages will be validated against the XML schema identified by the URI it contains.
    • WSDL - Specifies that messages will be validated against the Web services description (WSDL) identified by the URI it contains.
    • SCOPE – Specifies what part of the message will be 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 will be performed with the specified Stylesheet and Parameters. Transactions will be rejected when the execution fails. Stylesheet information must be specified, while Parameters are optional, and should be specified as needed by the particular stylesheet specified.
    • Stylesheet - Specifies the transform operation will use the stylesheet specified by the contained URI. The stylesheet MUST be an XSLT file.
    • Parameter - This optional, repeating element specifies a stylesheet 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.soawdpwsrr.doc/topics/csoa2_SOA_implementation.htm