Managing Accounts and SLAs

Defining Service Provider Group and Application Group SLAs

An application’s usage policies of Network Gatekeeper are specified in Service Level Agreement (SLA) XML files. There is an SLA associated with the service provider group and one associated with the application group. For more information on this administration model, see Creating and Maintaining Service Provider and Application Accounts.

This section describes:

Structure of a Service Level Agreement

The xsds for the SLAs are found in /sla_schema/ in $BEA_HOME/wlng400/modules/com.bea.wlcp.wlng.policy_4.0.0.0.jar:

app_sla_file.xsd is the application group SLA xsd.
sp_sla_file.xsd is and the service provider group SLA xsd.

The SLA contains two main types of information specified by the attributes in the <Sla> tag and the contents of the <serviceContract> tags. Service level agreement XML file overview shows the service provider level SLA XML file’s main structure and the relation between the <Sla> and the <serviceContract> tags. Differences between the SLA files on service provider and application level are described in the tag descriptions below the listing.

Note:

If the SLA XML file has spaces before the <?xml...> tag, the SLA will not load.

Listing 9-1 Service level agreement XML file overview

<Sla [serviceProviderGroupID | applicationGroupID] ="<Group>"

	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

	xsi:noNamespaceSchemaLocation="[sp_sla_file.xsd | app_sla_file.xsd]">

	<serviceContract>

		<startDate></startDate>

		<endDate></endDate>

		<scs></scs>

		<contract>

			....

		</contract>

		<overrides>

			<override>

				<startDate></startDate>

				<endDate></endDate>

				<startDow></startDow>

				<endDow></endDow>

				<startTime></startTime>

				<endTime></endTime>

				<contract>

...

      				</contract>

			</override>

		</overrides>

		<enforceAcrossGeoSites></enforceAcrossGeoSites>

	</serviceContract>

</Sla>

<Sla>

This tag contains a number of service contracts specifying under which conditions a service provider or an application is allowed to access and use service capabilities.

The serviceProviderGroupID attribute specifies service provider group the service provider belongs to and for which the SLA is valid. For SLAs on application level the applicationGroupID attribute is used instead. It specifies the application group the application belongs to and for which the SLA is valid.

The attribute xmlns:xsi contains processing information and should not be changed.

The attribute xsi:noNamespaceSchemaLocation shall point to the xsd for the service provider group SLA or the application group SLA, depending on which type of SLA it is:

app_sla_file.xsd is the application group SLA xsd
sp_sla_file.xsd is and the service provider group SLA xsd

<serviceContract>

This tag contains contractual data specifying under which conditions a service provider or an application is allowed to access and use specific services in Network Gatekeeper. One <serviceContract> tag is needed for each application-facing interface a service provider or an application shall have access to.

The data to be defined in the <serviceContract> tag for each interface is described below.

<startdate>

This tag specifies the date the application can start using the service capability. Use format YYYY-MM-DD.

Note:

A later start date on the service provider level service contract overrides this date.

<enddate>

This tag specifies the last date the application can use the service capability. Use format YYYY-MM-DD.

Note:

A earlier end date on the service provider level service contract overrides this date.

<scs>

This tag specifies the application-facing interface that the service contract applies to. The content of this tag is a Java representation of the WSDL that defines the interface. See section Managing and Configuring the Plug-in Manager in Network Gatekeeper Administration Guide for information on how to get a list of valid content.

Typically, the Java representation is expressed according to the pattern below:

<package name>.<standard indicator>.plugin.<interface name from WSDL>

For example, the Java representation of the interfaces for Parlay X 2.1 Short Messaging interfaces are:

com.bea.wlcp.wlng.px21.plugin.SendSmsPlugin
com.bea.wlcp.wlng.px21.plugin.ReceiveSmsPlugin
com.bea.wlcp.wlng.px21.plugin.SmsNotificationManagerPlugin

<contract>

This tag contains all contractual data.

The <contract> tag directly following the <scs> tag contains the default restrictions.

This tag, including its’ sub tags, can also be defined within the <override> tag in order to override the default restrictions.

<overrides>

This tag is a container of one or more <override> tags.

<override>

The contract data specified within this tag is used for overriding the default contractual data given in the <contract> tag directly following the <scs> tag.

When an override occurs, only the restrictions given in the <override> section are used. That is, all restrictions that are present in the normal contract will be disregarded if not explicitly restated in the override section. No quota definitions are valid within the override section.

In each occurrence of this tag, the following sub tags can be used:

<startDate>, specifies the start date the contract data given within the <override> tag is valid. Use format YYYY-MM-DD. Optional tag. If omitted, the start date for the service contract is used.
<endDate>, specifies the end date the contract data given within the <override> tag is valid. Use format YYYY-MM-DD. If omitted, the end date for the service contract is used.
<startDow>, specifies the starting weekday for which the contract data given within the <override> tag is valid. Use 1 for Sunday, 2 for Monday and so on. Optional tag.
<endDow>, specifies the end weekday for which the contract data given within the <override> tag is valid. Use 1 for Sunday, 2 for Monday and so on. Optional tag if <startDow> is not given.
<startTime>, specifies the start time for which the contract data given within the <override> tag is valid. Use format hh:mm:ss, where hh can be 00-24. Optional tag.
<endTime>, specifies the end time for which the contract data given within the <override> tag is valid. Use format hh:mm:ss, where hh can be 00-24. Optional tag if <startTime> is not given.
<contract>, specifies the contract data that overrides the contract data given directly after the <scs> tag. The tags that can be defined within the <contract> tag are described in the sections describing the contract data for each service capability.

Note:

For an override to be active all of the following must be true:

Today’s date must be the same as or later than startDate
Todays’ date must be earlier than endDate (must not be the same date)
Current time must be between startTime and endTime. endTime being earlier than startTime means the limit spans midnight.
Current day of week must be between startDow and endDow or equal to startDow or endDow. endDow being less than startDow means the limit spans the week end.

Since several <override> tags can be defined, with different settings for the time periods for which the restrictions applies, make sure the time periods do not overlap. In the case of overlapping time periods, there is no guarantee which contract that applies.

Below are two examples of <override> sections.

Listing 9-2 Listing D-2 <override> example

<overrides>

	<override>

		<startDate>2008-11-01</startDate>

		<endDate>2008-11-30</endDate>

		<startDow>2</startDow>

		<endDow>2</endDow>

		<startTime>09:00:00</startTime>

		<endTime>10:00:00</endTime>

		<contract>

...

		</contract>

	</override>

	<override>

		<startDate>2008-12-01</startDate>

		<endDate>2008-12-30</endDate>

		<startDow>2</startDow>

		<endDow>2</endDow>

		<contract>

...

	 	</contract>

	</override>

</overrides>

<enforceAcrossGeoSites>

This tag specifies if the SLA shall be enforced across geo-redundant sites.

Specify <enforceAcrossGeoSites>true<enforceAcrossGeoSites> if the SLA shall be enforced across geo-redundant site, otherwise false.

Optional tag. If not present, default is false.

Note:

If set to true, the SLA must not contain any <override> tag.

Contract structure

The listing below illustrates the structure of the <contract> segment of an SLA.

Listing 9-3 Contract structure

<contract>

	<guarantee>

		<methodGuarantee>

			<methodNameGuarantee></methodNameGuarantee>

			<reqLimitGuarantee></reqLimitGuarantee>

			<timePeriodGuarantee></timePeriodGuarantee>

		</methodGuarantee>

	</guarantee>

	<methodRestrictions>

		<methodRestriction>

			<methodName></methodName>

			<rate>

				<reqLimit></reqLimit>

				<timePeriod></timePeriod>

			</rate>

			<quota>

				<qtaLimit></qtaLimit>

				<days></days>

				<limitExceedOK></limitExceedOK>

			</quota>

		</methodRestriction>

	</methodRestrictions>

	<methodAccess>

		<blacklistedMethod>

			<methodName></methodName>

		</blacklistedMethod>

	</methodAccess>

</contract>

<contract>

This tag serves to hold together all service-specific data. A <contract> tag occurs once for every <scs> and once for every <override>.

<guarantee>

Optional.

This tag is used to specify a number of method requests the service provider or application is guaranteed during a specified time period (in milliseconds). Method requests from service providers and applications having the method tagged as guaranteed will have precedence above requests from service providers and applications not having the method tagged as guaranteed. Requests are given high priority if the request rate is below either the request rate stated in the service provider level SLA or the application level SLA, whichever has the higher request rate. For example, if the service provider level SLA guarantees 30 requests per second and the application level SLA guarantees 40 requests per second, the application level SLA applies.

The <guarantee> tag must encapsulate the <methodNameGuarantee>, <reqLimitGuarantee>, and <timePeriodGuarantee> tags within a <methodGuarantee> tag.

Note:

The <methodGuarantee> tag is ignored for mobile-originated traffic.

Each method in <methodNameGuarantee> must also be defined in <methodRestrictions>. The time period defined for a certain method must be identical in both the <guarantee> tag and the <methodRestriction>. See <methodRestriction>.

<methodNameGuarantee>

The name of the method to have guaranteed precedence.

<reqLimitGuarantee>

The number of requests to be guaranteed over the time period given in <timeperiodGuarantee>.

<timePeriodGuarantee>

The timeperiod to apply the guarantee, given in milliseconds.

<methodRestrictions>

Optional.

This tag is used for restricting the number of method requests an application is allowed to do over a short time period, the short time period is referred to as a rate, typically spanning a few seconds. A longer time period, referred to as a quota, typically spans several days.

Note:

The <methodRestrictions> tag is ignored for mobile-originated traffic.

One <methodRestrictions> tag, including one or more <methodRestriction> tags, is needed for each method that should have restricted usage. Only one <methodRestrictions> tag is allowed.

Below is an example with usage restrictions both for quotas and rates.

Listing 9-4 Example of a usage restriction

<methodRestrictions>

	<methodRestriction>

		<methodName>sendSms</methodName>

		<rate>

			<reqLimit>5</reqLimit>

			<timePeriod>1000</timePeriod>

		</rate>

		<quota>

			<qtaLimit>600</qtaLimit>

			<days>3</days>

			<limitExceedOK>true</limitExceedOK>

		</quota>

	</methodRestriction>

	<methodRestriction>

		<methodName>sendSmsLogo</methodName>

		<rate>

			<reqLimit>5</reqLimit>

			<timePeriod>1000</timePeriod>

		</rate>

		<quota>

			<qtaLimit>600</qtaLimit>

			<days>3</days>

			<limitExceedOK>true</limitExceedOK>

		</quota>

	</methodRestriction>

</methodRestrictions>

The example above specifies the usage restrictions for the methods SendSms and SendSmsLogo. The usage restriction for the short time period is 5 requests per second (5 requests divided by 1000 milliseconds). The usage restriction for the longer time period, the quota, is 600 requests over a 3 day period.

If the application does not have any usage restrictions within the allowed methods, the whole <restriction> tag should be deleted or commented out.

The most restrictive limit is always enforced, so if a restriction in a service provider level SLA is more restrictive than a restriction defined in an application level SLA, the service provider level SLA is the one being enforced.

<methodRestriction>

Contains restrictions for a method in the application-facing interface. Encapsulates the tags:

<methodName>
<rate>
<quota>

<methodName>

The name of the method to put restrictions on. The content of this tag is the Java representation of the method defined in the WSDL. See section Managing and Configuring the Plug-in Manager in Network Gatekeeper Administration Guide for information on how to get a list of valid method names.

<rate>

This tag defines the maximum number of requests to be guaranteed over a short time period, rate.

The <rate> tag contains two sub-tags:

<reqLimit> defines the maximum number of requests over the timeperiod given in <timePeriod>
<timePeriod> defines the time period, given in milliseconds.

<quota>

This tag defines the maximum number of requests over a longer time period.

The counters associated with the quota are reset at the beginning of each time period.

The <quota> tag contains the tags:

<qtaLimit> defines the maximum number of requests over the timeperiod defined in <qtaLimit>.
<days> defines the timeperiod period, given in days (only integers are valid). The starting day (day 0) is the same day as the <startdate> for the service contract. Only one quota limit and time period can be specified per <quota> tag.
<limitExceedOK> is used to specify what action to take if the quota limit is exceeded. If it is defined as true, the request will be allowed even if the quota is exceeded. If it is defined as false, the request will be rejected. An alarm is always emitted if the limit is exceeded.

<methodAccess>

Optional.

This tag is used to block the application from accessing one or more methods in the service capability. If the application is allowed to access all methods, the <methodAccess> tag should be omitted.

This tag encapsulates one or more <blacklistedMethod> tags.

<params>

This tag is used to either allow or deny certain parameters values to be provided by applications.

The <params> tag can encapsulate zero (0) or more <methodParameters> tags, each containing a <methodName>, <parameterName>, <parameterValues> and <acceptValues> tag.

In the example below, the parameter subject is allowed to contain only the parameter values A, B, and C for the method sendMessage. No other values for this parameter are allowed.

Listing 9-5 Example of <params>

<params>

	<methodParameters>

		<methodName>sendMessage</methodName>

		<parameterName>arg0.subject</parameterName>

		<parameterValues>A B C</parameterValues>

		<acceptValues>true</acceptValues>

	</methodParameters>

</params>

<methodParameters>

Encapsulates the <methodName>, <parameterName>, <ParameterValue> and <acceptValues> tag.

<methodName> contains name of the method whose parameters are to be allowed or denied.
<parameterName> contains the name of the parameter whose values are to be defined as allowed or denied. The content of this tag is the Java representation of the parameter defined in the WSDL. See section Managing and Configuring the Plug-in Manager in Network Gatekeeper Administration Guide for information on how to get a list of valid parameter names. The representation is arg0.<name of parameter as defined in WSDL>
<parameterValue> tag contains a list of allowed values. Several values can be defined, separated by white space.
<acceptValues> tag defines if the parameter values shall be allowed or denied. If the tag contains true, the parameter values given are allowed and all other values are denied. If the tag contains false, the parameter values given are denied and all other values are allowed.

<requestContext>

Encapsulates one or more <contextAttribute> tags.

A <contextAttribute> tag contains one <attributeName> and one <attributeValue> tag.

A plug-in can retrieve the value specified in <attributeValue> using the name specified in <attributeName>.

Note:

The plug-in must implement the functionality for fetching the value by name, see section Policy in Platform Development Studio- Developer's Guide for more information. Contact support for information on which parameters are supported by the standard Communication Services provided in this release.

Listing 9-6 Example of <requestContext>

<requestContext>

  <contextAttribute>

    <attributeName>com.bea.wlcp.wlng.plugin.sms.testName1</attributeName>

    <attributeValue>testValue1</attributeValue>

  </contextAttribute>

  <contextAttribute>

    <attributeName>com.bea.wlcp.wlng.plugin.sms.testName2</attributeName>

    <attributeValue>testValue2</attributeValue>

  </contextAttribute>

</requestContext>

<resultRestrictions>

Optional.

This tag is used to filter results from application-initiated requests.

This tag encapsulates one or more <resultRestriction> tags.

<resultRestriction>

Specifies a result restriction.

Encloses the following sub-tags:

<methodName> the method for which to restrict the return parameter.
<parameterRemovalName> the parameter, or set of parameters to remove.
<parameterMatch> filter to match to enable the removal (optional).
<filterMethod> defines how the filter is applied.

The result restriction makes is possible to remove return parameters from application-initiated requests.

The name of the method is identical to the name in the WSDL that defines the interface.

The return parameter is expressed as a String representation of a Java class. Arrays are expressed using the notation []directly following the parameter name. The notation format is:

arg0.result.<name of parameter as defined in WSDL> when the parameter is a single entity.
arg0.result[].<name of parameter as defined in WSDL> when the parameter is an array.

If the return parameter is a complex type, the hierarchy is expressed using dot notation. For example, if the return value expressed in XML is:

<xsd:complexType name="SmsMessage">

  <xsd:sequence>

   <xsd:element name="message" type="xsd:string"/>

   <xsd:element name="senderAddress" type="xsd:anyURI"/>

   <xsd:element name="smsServiceActivationNumber" type="xsd:anyURI"/>

   <xsd:element name="dateTime" type="xsd:dateTime" minOccurs="0" maxOccurs="1"/>

  </xsd:sequence>

</xsd:complexType>

The String representation is:

arg0.result[].dateTime.firstDayOfWeek

arg0.result[].dateTime.lenient

arg0.result[].dateTime.minimalDaysInFirstWeek

arg0.result[].dateTime.time.date

arg0.result[].dateTime.time.hours

arg0.result[].dateTime.time.minutes

arg0.result[].dateTime.time.month

arg0.result[].dateTime.time.seconds

arg0.result[].dateTime.time.time

arg0.result[].dateTime.time.year

arg0.result[].dateTime.timeInMillis

arg0.result[].dateTime.timeZone.ID

arg0.result[].dateTime.timeZone.rawOffset

arg0.result[].message

arg0.result[].senderAddress

arg0.result[].smsServiceActivationNumber

Note: In the example above, an array of SmsMessage is returned, hence arg0.result[]

The tag <parameterRemovalName> specifies which part of the return parameter to remove. It is possible to explicitly specify a leaf or to specify a node in the hierarchy. When specifying a node, the node and all siblings are removed. If the parameter to remove is a Boolean, it will not be removed but set to False.

For example, if specifying

<parameterRemovalName>arg0.result[].dateTime.timeZone.ID</parameterRemovalName>

only that part of the result parameter is removed, since it is a leaf.

If specifying:

<parameterRemovalName>arg0.result[].dateTime.time</parameterRemovalName>

All of the siblings are removed from the result parameters:

arg0.result[].dateTime.time.date
arg0.result[].dateTime.time.hours
arg0.result[].dateTime.time.minutes
arg0.result[].dateTime.time.month
arg0.result[].dateTime.time.seconds
arg0.result[].dateTime.time.time
arg0.result[].dateTime.time.year

See section Managing and Configuring the Plug-in Manager in Network Gatekeeper System Administrator’s Guide for information on how to get a list of all method names and parameter names.

<parameterMatch>

Encapsulates the following sub-tags:

<parameterName> (exactly one)
<parameterValues> (exactly one).

Optional tag.

If <parameterMatch> is present, result filtering takes place only if the parameter defined in <parameterName> has a value defined in one of the <parameterValue> tags.

The format of <parameterName> is the same as for <parameterRemovalName>.

<ParameterValues> encapsulates one or more <ParameterValue> tags.

The <ParameterValue> tag is the value of <parameterName>. The value can be expressed as a regular expression.

<filterMethod>

Enumeration. Possible values:

BLACK_LIST
WHITE_LIST

Defines how the filter defined in <parameterMatch> is applied.

If <filterMethod> is defined as BLACK_LIST, all parameters matching <parameterRemovalName> are removed if the request matches the filter.

If <filterMethod> is defined as WHITE_LIST, only the parameters matching <parameterRemovalName> are kept if the request matches the filter.

Example

The method getData returns an array of data, where data is a complex type consisting of the name-value pair:

dataName
dataValue

Listing 9-7 illustrates the SLA.

Listing 9-7 Result filter for blacklisting array parameter values

<resultRestrictions>

  <resultRestriction>

    <methodName>getData</methodName>

    <parameterRemovalName>result.data[].dataName</parameterRemovalName>

    <parameterMatch>

      <parameterName>result.data[].dataName</parameterName>

      <parameterValues>

        <parameterValue>ssn<parameterValue>

        <parameterValue>homephone<parameterValue>

      <parameterValues>

    </parameterMatch>

    <filterMethod>BLACK_LIST</filterMethod>

  </resultFilter>

<resultFilfters>

Assuming the result before the filter is applied is:

result.data[0].dataName = “cellphone”
result.data[0].dataValue =”415-555-1234”
result.data[1].dataName = “ssn”
result.data[1].dataValue =” 123 45 6789”
result.data[2].dataName = “homephone”
result.data[2].dataValue =”415-333-4444”

After applying the result filter, the result is:

result.data[0].dataName = “cellphone”
result.data[0].dataValue =”415-555-1234”

since <filterMethod> is BLACK_LIST and <parameterValue> contains only ssn and homephone, these are removed from the result returned to the application.

If <filterMethod> had been WHITE_LIST, the result after applying the filter would be:

result.data[0].dataName = “ssn”
result.data[0].dataValue =”123 45 6789”
result.data[0].dataName = “homephone”
result.data[0].dataValue =”415-333-4444”

since only these parameters matches the filter.

If <parameterRemovalName> is result.data instead of result.data[] the filtered result would be null in both cases, since both filters match and the absence of the [] means that all results starting from the hierarchy result.data should be removed given that the filter matches the result.