This chapter describes how the different types of Service Level Agreements (SLAs) are managed and provisioned in Oracle Communications Services Gatekeeper (OCSG).
It contains the following sections:
Introduction to SLA types
Summary of Tasks Related to SLAs
There are two different kinds of SLAs:
System level SLAs
Custom SLAs
System level SLAs have static XSDs that are already defined in Services Gatekeeper, while custom SLAs provides the possibility to use a custom XSD. Any given service provider group or application group can have only one system SLA associated with it, while they can have many custom SLAs. Create custom SLAs when additional SLA enforcement logic is required that is not provided by default in Services Gatekeeper. You must create the enforcement logic for a Custom SLA. See Services Gatekeeper Extension Developer's Guide for information on how to develop Custom SLAs.
When SLAs are loaded into memory, they are stored in the SLA repository. SLAs can be loaded into the repository in two ways:
The contents of the SLA is provided as a parameter in the operation that loads the SLA.
The SLA is stored in a file and the URL to that file is provided as a parameter in the operation that loads the SLA.
SLAs are retrieved from the SLA repository using the retrieve operations.
The SLA loaded into the SLA repository is the one being enforced. Changes to the file after the SLA is loaded into the repository are not automatically reflected in the active version.
Table 3-1 outlines the different SLA types, the IDs and their scope.
SLA Type | ID(s) | Description |
---|---|---|
Application Group |
application system:geo_application |
System SLA. Defines how application can use Services Gatekeeper. See "Application Group SLAs" for a summary of related management operations. For information on creating these SLAs, see "Defining Service Provider Group and Application Group SLAs". The SLA type ID:
|
Service Provider Group |
service_provider system:geo_service_provider |
System SLA. Defines how service providers can use Services Gatekeeper. See "Service Provider Group Node SLAs" for a summary of related management operations. For information on creating these SLAs, see "Defining Service Provider Group and Application Group SLAs". The SLA type ID:
|
Global Node |
global_node |
System SLA. Defines how Services Gatekeeper is allowed to use the underlying telecom network nodes. See "Global Node SLAs" for a summary of related management operations. For information on creating these SLAs, see "Defining Service Provider Group and Application Group SLAs". This SLA type is loaded and enforced locally in the network tier cluster it is loaded. |
Service Provider Node |
service_provider_node |
System SLA. Defines how Service Providers are allowed to use the underlying telecom network nodes. See "Service Provider Group Node SLAs". For information on creating these SLAs, see "Defining Service Provider Group and Application Group SLAs". This SLA type is loaded and enforced locally in the network tier cluster it is loaded. |
Subscriber |
subscr |
System SLA. Defines classes of application services that can be associated with subscribers in the context of Services Gatekeeper. Using the Platform Development Studio, an operator or integrator may create a subscriber-centric policy mechanism. The specifics of this mechanism are covered in ”Using SLA Policies to Manager Subscribers” in Services Gatekeeper Extension Developer's Guide. This SLA type is loaded and enforced locally in the network tier cluster on which it is loaded. |
Custom |
Defined at load time |
Custom SLA. A custom SLA is defined by an XSD, that must be created and loaded. A custom SLA type ID is associated with the XSD, and this type is the one being referenced when loading the custom SLAs. In addition to the SLA, the enforcement logic that operates on the data in the SLA must be created. See ”Creating Custom Runtime SLAs” in Services Gatekeeper Services Gatekeeper Extension Developer's Guide. Just like system SLAs, the custom SLAs are associated with service provider groups and application groups. In addition there is a custom global SLA, that does not take into consideration the originator of the request, but affects all requests. Custom SLAs are loaded and enforced locally in the network tier cluster it is loaded. |
Note:
The prefix system is reserved, and should not be used by custom SLAs. For backward compatibility, there is a set of SLA types without this prefix.The tasks related to the management of SLAs comprise the following:
The management of Service Provider and Application Group system SLAs comprises managing the following:
You use the methods of the ServiceLevelAgreementMBean MBean to manage Service Provider and Application Group system SLAs. For information on the methods and fields of the ServiceLevelAgreementMBean, see the ”All Classes” section of Services Gatekeeper OAM Java API Reference.
Table 3-2 describes the tasks related to managing Service Provider Group system SLAs and the ServiceLevelAgreementMBean MBean methods to use.
Table 3-2 Tasks Related to Managing Service Provider Group System SLAs
Task | ServiceLevelAgreementMBean Method to Use |
---|---|
Associate Service Provider Group with SLA |
loadServiceProviderGroupSlaByType loadServiceProviderGroupSlaFromUrlByType |
View Service Provider Group SLA |
retrieveServiceProviderGroupSlaByType |
Table 3-3 describes the tasks related to managing Application Group system SLAs and the ServiceLevelAgreementMBean MBean methods to use.
The management of Node SLAs comprises managing the following:
You use the methods of the ServiceLevelAgreementMBean MBean to manage Node SLAs. For information on the methods and fields of the ServiceLevelAgreementMBean, see the ”All Classes” section of Services Gatekeeper OAM Java API Reference.
Table 3-4 describes the tasks related to managing Global Node system SLAs and the operations you use to perform those tasks.
Table 3-5 describes the tasks related to Service Provider Group Node SLAs and the operations you use to perform those tasks.
Subscriber SLAs are a feature that can be developed using the Platform Development Studio. Table 3-6 describes the tasks related to managing Subscriber SLAs and the operations you use to perform those tasks.
Custom SLAs are a feature that can be developed using the Platform Development Studio. This section describes the management of Custom SLAs.
You use the methods of the ServiceLevelAgreementMBean MBean to manage custom SLAs. For information on the ServiceLevelAgreementMBean methods and fields, see the ”All Classes” section of Services Gatekeeper OAM Java API Reference.
Table 3-7 describes the tasks related to managing Custom XSDs and the operations you use to perform those tasks.
Table 3-8 describes the tasks related to managing Custom Application Group SLAs and the operations you use to perform those tasks.
Table 3-8 Tasks Related to Managing Custom Application Group SLAs
Task | Operation to Use |
---|---|
Associate Custom Application Group with SLA |
loadApplicationGroupSlaByType loadApplicationGroupSlaFromUrlByType |
View Custom Application Group SLA |
retrieveApplicationGroupSlaByType |
Count Custom Application Group SLA |
countApplicationGroupsByType |
List Custom Application Group SLA |
listApplicationGroupsByType |
Table 3-9 describes the tasks related to managing Custom Service Provider Group SLAs and the operations you use to perform those tasks.
Table 3-9 Tasks Related to Managing Custom Service Provider Group SLAs
Task | Operation to Use |
---|---|
Associate Custom Service Provider Group with SLA |
loadServiceProviderGroupSlaByType loadServiceProviderGroupSlaFromUrlByType |
View Custom Service Provider Group SLA |
retrieveServiceProviderGroupSlaByType |
Count Custom Service Provider Group SLA |
countServiceProviderGroupsByType |
List Custom Service Provider Group SLA |
listServiceProviderGroupSlaTypes listServiceProviderGroupsByType |
Table 3-10 describes the tasks related to managing Custom Global SLAs and the operations you use to perform those tasks.
Services Gatekeeper provides a mapping mechanism to allow you to assign a specific HTTP response for a given deny code during SLA validation. Table 3-11 describes the mapping.
Table 3-11 Deny Code to HTTP Response Mapping
From | To |
---|---|
errorCode in DenyCodes |
|
SLA validation uses the mapper to resolve which HTTP response to send. Validation no longer uses static HTTP responses. If no mapping exists for a deny code, an HTTP response is generated from the built-in list of deny code definitions.
Services Gatekeeper provides a REST API to manage these mappings along with a corresponding MBean interface to provide troubleshooting capabilities for the administrator. The OCSG database provides cluster-wide data storage and a cache layer. The REST API consumes and produces both JSON and XML content types:
application/xml
application/json
You can manage mappings using both DafConfigurationsMBean
and the Partner Manager REST API.
Table 3-12 illustrates sample REST interface requests.
Table 3-12 Example REST Requests
Operation | Curl Example |
---|---|
Get a mapping |
|
Remove a mapping |
|
Add a mapping |
|
List mappings |
|
The following sections describe in detail the operations you can perform using the REST API.
When no mapping exists for a deny code, a default HTTP response from this list is returned. To list the built-in deny code definitions, issue an HTTP GET to the URL in the following example:
GET prm_pm_rest/services/prm_pm/services/partner_manager/denycode/definitions
The response returns a list of the deny code definitions in descending order.
{"denyCodeDefinitionItems": {"items": [ { "name": "NO_APP_INSTANCE", "denyCode": 1, "httpStatus": 400, "httpContentType": "text/plain", "httpBody": "Application instance does not exist" }, { "name": "APP_INST_DEACTIVATED", "denyCode": 2, "httpStatus": 400, "httpContentType": "text/plain", "httpBody": "Application instance is not active" }, ... ] } }
<denyCodeDefinitionItems> <denyCodeDefinitionItem> <denyCode>1</denyCode> <httpBody>Application instance does not exist</httpBody> <httpContentType>text/plain</httpContentType> <httpStatus>400</httpStatus> <name>NO_APP_INSTANCE</name> </denyCodeDefinitionItem> <denyCodeDefinitionItem> <denyCode>2</denyCode> <httpBody>Application instance is not active</httpBody> <httpContentType>text/plain</httpContentType> <httpStatus>400</httpStatus> <name>APP_INST_DEACTIVATED</name> </denyCodeDefinitionItem> ...
To list the mappings of deny codes to HTTP responses, issue an HTP GET to the URL shown in the following example:
GET prm_pm_rest/services/prm_pm/services/partner_manager/denycode/mappings
Table 3-13 describes the request's optional parameters:
Table 3-13 Parameters for GET List Mappings
Name | Type | Description |
---|---|---|
skip |
Positive Integer |
Specifies how many mappings to skip. For example, set skip to 0 to obtain the full list. For the list 0, 1, 2, 3, 4, 5, 6, setting skip to 2 would return items 2, 3, 4, 5, 6. Default is 0. |
limit |
Positive Integer |
For a full list with no items omitted, specify 0. For the list 0, 1, 2, 3, 4, 5, 6 specifying limit of 5 would return 0, 1, 2, 3, 4. Default is 0. |
Returns a standard response of 200 with the list of MappingItem items ordered by deny code in ascending order
{"mappingItems": {"items": [ { "denyCode": 34, "httpStatus": 403, "httpContentType": "application/json", "httpBody": "{\"message\":\"Forbidden123\"}" }, { "denyCode": 35, "httpStatus": 403, "httpContentType": "application/json", "httpBody": "{\"message\":\"Forbidden123\"}" }, { "denyCode": 37, "httpStatus": 403, "httpContentType": "application/json", "httpBody": "{\"message\":\"Forbidden123\"}" }] } }
An empty list would look like this:
{ "mappingItems":{ "items":[ ] } }
<mappingItems> <mappingItem> <denyCode>34</denyCode> <httpBody>{"message":"Forbidden123"}</httpBody> <httpContentType>application/json</httpContentType> <httpStatus>403</httpStatus> </mappingItem> <mappingItem> <denyCode>35</denyCode> <httpBody>{"message":"Forbidden123"}</httpBody> <httpContentType>application/json</httpContentType> <httpStatus>403</httpStatus> </mappingItem> <mappingItem> <denyCode>37</denyCode> <httpBody>{"message":"Forbidden123"}</httpBody> <httpContentType>application/json</httpContentType> <httpStatus>403</httpStatus> </mappingItem> </mappingItems>
An empty list would look like this:
<mappingItems/>
To add a mapping or overwrite an existing mapping, issue a POST command to the following URL with a mapping item:
POST prm_pm_rest/services/prm_pm/services/partner_manager/denycode/mappings
{"mappingItem": { "denyCode": 36, "httpStatus": 403, "httpContentType": "application/json", "httpBody": "{\"message\":\"Forbidden123\"}" } }
<mappingItem> <denyCode>36</denyCode> <httpBody>{"message":"Forbidden123"}</httpBody> <httpContentType>application/json</httpContentType> <httpStatus>403</httpStatus> </mappingItem>
Returns a status code 201 with the location header pointing to the end of the created mapping as shown in the following example:
http://127.0.0.1:8001/prm_pm_rest/services/prm_pm/services/partner_manager/denycode/mappings/prm_pm/services/partner_manager/denycode/mappings/34
To get an existing mapping item, issue a GET to the URL in the following example, replacing {denyCode}
with the deny code for which you want the mapping:
http://127.0.0.1:8001/prm_pm_rest/services/prm_pm/services/partner_manager/denycode/mappings/{denyCode}
Returns a standard HTTP response with a status code 200 and the payload. Produces the added MappingItem item, including any automatically populated properties like httpContentType
.
{"mappingItem": { "denyCode": 36, "httpStatus": 403, "httpContentType": "application/json", "httpBody": "{\"message\":\"Forbidden123\"}" } }
<mappingItem> <denyCode>36</denyCode> <httpBody>{"message":"Forbidden123"}</httpBody> <httpContentType>application/json</httpContentType> <httpStatus>403</httpStatus> </mappingItem>
To remove a mapping, issue an HTTP Delete request with the following URL, replacing {denyCode}
with the deny code for the mapping that you want to remove.
Returns a standard HTTP response with status code 200 and the payload. Produces the removed MappingItem item or Content-Length of 0 to indicate that there was no item to remove.
{"mappingItem": { "denyCode": 36, "httpStatus": 403, "httpContentType": "application/json", "httpBody": "{\"message\":\"Forbidden123\"}" } }
<mappingItem> <denyCode>36</denyCode> <httpBody>{"message":"Forbidden123"}</httpBody> <httpContentType>application/json</httpContentType> <httpStatus>403</httpStatus> </mappingItem>
The REST API uses the following data definitions.
Table 3-14 describes the definition of a deny code mapping to an HTTP response. All properties are mandatory:
Table 3-14 DenyCodeDefinitionItem Data Definition
Property Name | Description | Type |
---|---|---|
denyCode |
A non-negative integer code that specifies the reason for denial in SLA enforcement. |
Int |
httpBody |
Text that is used in HTTP response body. |
String |
httpContentType |
Statically set to plain text and used in the Content-Type header in an HTTP response. |
String |
httpStatus |
Status code used in HTTP response. |
Int |
name |
A more friendly identifier for this deny reason. Has a one to one relationship with denyCode. |
String |
Table 3-15 describes the definition of a MappingItem item.
Property Name | Description | Type | Mandatory |
---|---|---|---|
denyCode |
A non-negative integer code that identifies this deny reason in SLA enforcement. |
Int |
true |
httpStatus |
HTTP response status code. |
Int |
true |
httpBody |
The text that is sent in the HTTP response body. If not present the following applies:
|
String |
false |
httpContentType |
Used in Content-Type header in an HTTP response. If not present, it will be set to default value of text / plain |
String |
false |
You can receive the following error codes when using the REST APIs:
400 - Omitting a mandatory parameter
JSON example:
{ "SOAPException":{ "message":"Mandatory parameter missing: httpStatus" } }
XML example:
<?xml version="1.0" encoding="UTF-8"?> <ns2:SOAPException xmlns:ns2="http://ocsg.oracle/portal/ws/common"> <message>Mandatory parameter missing: httpStatus</message> </ns2:SOAPException>
400 - Using illegal parameter value
JSON example:
{ "SOAPException":{ "message":"Mandatory parameter cannot be negative: denyCode" } }
XML example:
<?xml version="1.0" encoding="UTF-8"?> <ns2:SOAPException xmlns:ns2="http://ocsg.oracle/portal/ws/common"> <message>Mandatory parameter cannot be negative: denyCode</message> </ns2:SOAPException>
400 - When API user doesn't have a partner manager access role
JSON Example:
{ "SOAPException":{ "message":"The login user type is invalid!" } }
XML Example:
<?xml version="1.0" encoding="UTF-8"?> <ns2:SOAPException xmlns:ns2="http://ocsg.oracle/portal/ws/common"> <message>The login user type is invalid!</message> </ns2:SOAPException>
404 - Attempting to reach a non-existing endpoint
405 - Attempting to use an unsupported HTTP operation
500 - An internal error happens. Use incidentID to correlate with the error l (default.log)
JSON example:
{"incidentID":"E-8b4cc44c49534f72a14f5b026103a145"}
XML example
<?xml version="1.0" encoding="UTF-8"?> <internalServerException> <incidentID>E-700cf6bd27a940fc8476d9cfbeabe2ab</incidentID> </internalServerException>
An interface uses primitive types to assert that it can be managed through the WebLogic console. In results, JSON formatted Strings encapsulate a complex structure in the primitive String type.
Note:
Gatekeeper attributes are read-only values, while operations are executable functions.The following interface is in DafGeneralInformation:
public interface DenyCodeMappingsOperations { /** * Use this operation to find out the available deny codes which you can * re-configure mappings for. If no mapping is configured for a specific deny * code, the response in this listing applies. * * @return Array of deny code definitions. Each definition is in JSON format. * @throws ManagementException If deny deny codes could not be fetched from * storage. */ String[] getDenyCodeDefinitions() throws ManagementException; /** * Use this operation to view the existing deny code to HTTP mappings. * * @param offset Offset to use when listing mappings. * @param limit Limit the number of results to retrieve. * @return Array of mappings, ordered by deny code (ascending). Each Mapping is in * JSON format. * @throws ManagementException If mappings could not be retrieved from Storage. */ String[] getMappings(int offset, int limit) throws ManagementException; /** * Use this operation to view the existing deny code to HTTP mappings. * * @param denyCode Deny code to show mapping for. * @return Mapping in JSON format. * @throws ManagementException If mapping could not be retrieved from Storage. */ String getMapping(int denyCode) throws ManagementException; /** * Use this operation to specify what HTTP response to generate for a given deny * code. * @param denyCode Numeric value of deny deny code. * @param httpCode HTTP status code to use for this deny code. * @param contentType The content type that matches content in httpBody parameter. * @param httpBody HTTP Body to use for this deny code. * @return Saved mapping in JSON format, eg {"denyCode": 40,"httpCode": * 400,"httpBody": "DEFAULT"} * @throws ManagementException If mapping could not be saved to Storage. */ String setMapping(int denyCode, int httpCode, String contentType, String httpBody) throws ManagementException; /** * Use this operation to remove an existing mapping. * * @param denyCode Deny code to remove mapping for. * @return Removed mapping in JSON format or null if no mapping was found. * @throws ManagementException If mapping could not be removed from Storage. */ String removeMapping(int denyCode) throws ManagementException; }
In SLA enforcement, you can do the following when an SLA Exception is thrown:
throwSLAException(DenyCodes.API_STATE_INVALID);
When a request is denied, the deny code is added to the EDR. See the highlighted DenyCode in this example:
[03-30 03:42:07:DEBUG EdrInternalPublisher.java] *** EDR:
ContainerTransactionId = null
Method = null
HttpStatusCode = 401
TsAfAT = 1490881317793
TsAfNT = 1490881317792
ReqAction = ["seq=1, name=OAuth2Validator, status=Success", "seq=2, name=SLAEnforcement, status=Reject, err='No Service Contract found for type: %s'"]
Position = after
ServiceProviderId = partner
DenyCode = 34
TransactionId = 04a6dce8-5f86-4092-99d0-5bd0af36881a_IDX_4
ServiceName = /ECHOServer/1
State = ENTER_AT
Class = oracle.ocsg.daf.trafficlogger.SingleTierTrafficLogger
ApplicationId = exposed-calendar
TsBeAT = 1490881317725
HttpMethod = POST
status = Reject
TsBeNT = 1490881317734
Timestamp = 1490881317793
Direction = south
Source = exception
URL = /ECHOServer/1/echo
ServiceProviderGroup = gold
AppInstanceId = appkey_Password2
RspMsgSize = 1468
ErrCat = ActionErr
ServerName = Server1
ApiId = ECHOServer
ReqMsgSize = 16
HTTP 4xx responses that originate from Actions or security providers go through content transformation before being sent to the caller. Table 3-16 describes the supported conversions:
Table 3-16 Supported Conversions for HTTP 4xx Responses
From | To |
---|---|
JSON |
XML |
XML |
JSON |
Plain |
JSON |
Plain |
XML |
If no transformation is needed or one cannot be performed, the original response is sent.