![]() ![]() ![]() ![]() ![]() ![]() |
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.
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
:
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. |
<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
>
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:
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.
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. |
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. |
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:
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.
This tag is a container of one or more <override> tags.
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:
Note: | For an override to be active all of the following must be true: |
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.
<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
>
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. |
The listing below illustrates the structure of the <contract> segment of an SLA.
<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>
This tag serves to hold together all service-specific data. A <contract> tag occurs once for every <scs> and once for every <override>.
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>.
The name of the method to have guaranteed precedence.
The number of requests to be guaranteed over the time period given in <timeperiodGuarantee>.
The timeperiod to apply the guarantee, given in milliseconds.
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.
<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.
Contains restrictions for a method in the application-facing interface. Encapsulates the tags:
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.
This tag defines the maximum number of requests to be guaranteed over a short time period, rate.
The <rate> tag contains two sub-tags:
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:
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.
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.
<params
>
<methodParameters
>
<methodName
>sendMessage</methodName
>
<parameterName
>arg0.subject</parameterName
>
<parameterValues
>A B C</parameterValues
>
<acceptValues
>true</acceptValues
>
</methodParameters
>
</params
>
Encapsulates the <methodName>, <parameterName>, <ParameterValue> and <acceptValues> tag.
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. |
<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
>
This tag is used to filter results from application-initiated requests.
This tag encapsulates one or more <resultRestriction> tags.
Specifies a result restriction.
Encloses the following sub-tags:
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:
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>
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.
<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:
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.
Encapsulates the following sub-tags:
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.
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.
The method getData
returns an array of data, where data is a complex type consisting of the name-value pair:
Listing 9-7 illustrates the SLA.
<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:
After applying the result filter, the result is:
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:
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.
![]() ![]() ![]() |