3 Managing SLAs

Managing Service Provider and Application Group System SLAs

The management of Service Provider and Application Group system SLAs comprises managing the following:

• Service Provider Group System SLAs

• Application Group SLAs

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.

Managing Node SLAs

The management of Node SLAs comprises managing the following:

• Global Node SLAs

• Service Provider Group Node SLAs

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.

Subscriber SLAs

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

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.

List Deny Code Definitions

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.

JSON Example

{"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"
    },
    ...
    ]
  }
}

XML Example

<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>
  ...

List Mappings

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

Parameters

Table 3-13 describes the request's optional parameters:

Returns a standard response of 200 with the list of MappingItem items ordered by deny code in ascending order

JSON Example

{"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":[
    ]
  }
}

XML Example

<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/>

Add a Mapping

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

JSON Payload Example

{"mappingItem": 
  {
    "denyCode": 36,
    "httpStatus": 403,
    "httpContentType": "application/json",
    "httpBody": "{\"message\":\"Forbidden123\"}"
  }
}

XML Payload Example

<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

Get a Mapping

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.

JSON Example

{"mappingItem": 
  {
    "denyCode": 36,
    "httpStatus": 403,
    "httpContentType": "application/json",
    "httpBody": "{\"message\":\"Forbidden123\"}"
  }
}

XML Example

<mappingItem>
  <denyCode>36</denyCode>
  <httpBody>{"message":"Forbidden123"}</httpBody>
  <httpContentType>application/json</httpContentType>
  <httpStatus>403</httpStatus>
</mappingItem>

Remove a Mapping

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.

JSON Example

{"mappingItem": 
  {
    "denyCode": 36,
    "httpStatus": 403,
    "httpContentType": "application/json",
    "httpBody": "{\"message\":\"Forbidden123\"}"
  }
}

XML Example

<mappingItem>
  <denyCode>36</denyCode>
  <httpBody>{"message":"Forbidden123"}</httpBody>
  <httpContentType>application/json</httpContentType>
  <httpStatus>403</httpStatus>
</mappingItem>

Data Definitions

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-15 describes the definition of a MappingItem item.

Error Handling

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>
    

MBean Interface

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.

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;
 
}

SLA Enforcement

In SLA enforcement, you can do the following when an SLA Exception is thrown:

throwSLAException(DenyCodes.API_STATE_INVALID);

EDR Details

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

Tranformation of Error Content

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:

If no transformation is needed or one cannot be performed, the original response is sent.