You are here: Usage Information > retrievePeakCapacity

Retrieve Peak Capacity

Description

This Web service reports maximum capacity of a postpaid feature during a given billing period across one or all entitlement(s) of a customer. Capacity is a feature-level integer value that is specified in Cloud Run-time, as an optional parameter of the login API.

Default Protocol Method Type URI
HTTPS GET retrievePeakCapacity.xml

Note

To learn more about capacity and peak capacity, refer to EMS User's Guide.

Query Parameters

Parameter Description Valid Values Optional
customerId Customer for whom you want to determine peak capacity. Integer No
entId

Identifier of the entitlement for which you want to determine peak capacity.

Note: The entId is the handle returned by the createEntitlement.xml web service. You can use the searchEntitlements.xml web service to retrieve entId for an entitlement.

Integer Yes
ftrIds List of unique record IDs of features (as stored in EMS database), separated by commas String Yes
featureNames List of feature names separated by commas String Yes
startDate

Start date of the duration for which the report is required

The startDate should be earlier than or same as the enddate.

String (yyyy-mm-dd) No
endDate End date of the duration for which the report is required String (yyyy-mm-dd) No
granularity Granularity of time interval, in hours, at which peak capacity is to be reported. Its value can range from 1 to 744 hours. Integer > 0 No
status

Specifies whether or not to include revoked entitlements in the response. Possible values are:

  • 3 : Include revoked entitlements in the response. This is the default value.
  • 4: Do not include revoked entitlements in the response.
Integer Yes

Possible Combinations

You can obtain data for all features across all entitlements for a customer, or refine by each entitlement or each feature. The possible input combinations are:

Input Output

customerId Only

Report for all features across all entitlements for a customer.

customerId and selected ftrIds

Report for selected features across all entitlement for a customer.

customerId and featureNames

customerId and entId

Report for all features in an entitlement.

customerId, entId, and ftrIds

Report for selected features in an entitlement.

customerId, entId, and featureNames

This Web service shows data for only those features for which capacity has been recorded.

Sample Code

import java.io.IOException;
import java.net.URLDecoder;

//..............................
//..............................
//..............................
import org.apache.http.params.HttpParams;
public class EMSSample {
                private static DefaultHttpClient httpclient = new DefaultHttpClient();
                private static Principal principal = null;
                private static StringBuffer query;
                //..............................
                //..............................
                //..............................
public static String retrievePeakCapacity.xml()throws Exception  {
    if(!verifyLogin()){
                return "login failed";
    }
    HttpContext context = new BasicHttpContext();
    context.setAttribute(ClientContext.USER_TOKEN, principal);
         HttpGet get = new HttpGet("https://localhost:8443/ems/3.6/retrievePeakCapacity.xml");
    query = new StringBuffer();
    setParameter("startDate", "2013-07-10");
    setParameter("customerId", "1");
    setParameter("entId", "");
    setParameter("granularity", "1");
    setParameter("endDate", "2013-07-10");
    setParameter("featureNames", "");
    setParameter("ftrIds", "");
    setParameter("status", "1");
    get.setURI(new URI(URLDecoder.decode(get.getURI() + query.toString(),"UTF-8")));
    HttpResponse response = httpclient.execute(get, context);
    HttpEntity entity = response.getEntity();
    byte[] b = null;
    if (entity != null) {
        long l = entity.getContentLength();
         b = new byte[(int) l];
         entity.getContent().read(b);
         entity.consumeContent();
                }
                return new String(b);
                }
    static void setParameter(String key, String value) {
                if (query.toString().equals("")) {
                                query.append("?" + key + "=" + value + "&");
                } else {
                                query.append(key + "=" + value + "&");
                }
    }
    }

Sample Example

To bill customers based on the capacity consumed by them, a vendor needs to determine how much capacity is consumed in a billing period.

Sample Data

Suppose, the customers used the application and recorded capacity characteristics for a particular feature, across a group of entitlements, in a day. The following table shows the sample capacity values recorded at the time of login and logout.

Time Instance

Capacity Requested (With login)

Capacity Returned (At logout)

07:15 400  
07:52 200  
07:59   200
09:05 500  
10:17   400
12:30 700  
13:45   500

The Run-time sends the above data from application to Cloud Connect.

Computing Peak Capacity

For the above data set, a vendor can determine the peak value of the capacity for a given billing period. In this case, it is 1 day or 24 hours. The report data can be refined by specifying granularity as input. Granularity specifies the time interval, in hours, at which peak capacity is reported. The billing period is divided into time slices equal to granularity.

Assuming a granularity of 1 hour, the peaks for each time slice is computed as follows:

Time Slice

(granularity is 1 hour)

Peak Capacity Remarks
0-7 0 Indicates no capacity specified.
7 – 8 600

This equals 400 + 200.

The logout at 07:59 is not considered. To calculate maximum capacity utilized during a time interval, logouts are ignored.

8 – 9 400 No capacity recorded between 8-9. So the peak capacity during this interval is actual capacity until 09:00, that is (400 + 200 – 200).
9 – 10 900  
10 – 11 900  
11 – 12 500  
12 – 13 1200  
13 – 14 1200  
14 – 15 700  
15 – 16 till 23-24 700 For session created at 12:30, the subsequent logout has not arrived. It means that the amount of capacity blocked has not been released completely. The residual capacity is carried forward till logout, that is till capacity is zero. So, the peak capacity remains same for all these intervals.

Sample Response

For the sample data set given above, the following will be the output of the Web service for the specified feature on that day, assuming the granularity of 1 hour:

<emsResponse>
  <capacityData>
    <customerRefId>Customer</customerRefId>
    <feature>
      <id>1</id>
      <name>Feature</name>
      <peakCapacity>0, 0, 0, 0, 0, 0, 0, 600, 400, 900, 900, 500, 1200, 1200, 700, 700, 700, 700, 700, 700, 700, 700, 700, 700</peakCapacity>
    </feature>
  </capacityData>
  <capacityProvisionedData>
    <entitlement>
      <eid>0bfd2072-84cd-44e3-81be-e2122a8dacc8</eid>
      <product>
        <name>Product</name>
        <version>1</version>
        <feature>
          <id>1</id>
          <name>Feature</name>
          <capacityAttribute>305</capacityAttribute>
        </feature>
      </product>
    </entitlement>
  </capacityProvisionedData>
  <stat>ok</stat>
</emsResponse>

In the above response:

Using Peak Capacity

The vendors can analyze the Web service response according to their requirements. For example, below is a sample interpretation of how a customer used the application during a day:

The above data is for all features across all entitlements, but this can be refined down to a single entitlement or to a single feature, as required.

See Also:

Output Format for Failure

Error Codes

Error Code Description
100 Invalid request parameter.
101 You are not authorized to use this service.
102 Invalid data entered.
107 An internal error occurred! Please report the error to System administrator.
118 {field} should be of data type integer. [Note: This error code is applicable for the fields - featureId, License modelId, entId, ftrId, customerId, lmId, templateType, lineItemId, CustomerId, stationCount, status, and granularity.]
120 {field} value is less than the minimum permitted value {value}. [Note: This error code is applicable for the fields - productd, featureId,entId, billType, lmId, lastModified, timeZoneId, customerId, and granularity.]
122 {field} is a required field and should have a not null value. [Note: This error code is applicable for the fields - Eid, namespaceName, featureName, startDate, endDate, userIds, featureId, productName, productVersion, detailsLM, lmId, templateType, customAttribute, lineItemId, customerRefId, granularity, loginId, oldPassword, and newPassword.]
123 endDate should be of dataType Date in the format yyyy-mm-dd startDate should be of dataType Date in the format yyyy-mm-dd.
128 You should log on first.
309 Unable to find feature.
519 Customer not found for the given customerId.
621 Entitlement does not exist. Retry with a correct ID.
1081 Invalid Web service version provided
1084 No Web service version provided
1088 The EMS system is running on HTTPS. Please provide the correct Web service URL.
1132 Error in retrieving capacity information. Please contact the system administrator for further assistance.
1134 Invalid capacity value.Capacity value between 1 - 2147483647 is allowed.
1176 Invalid {field}. Note: This error code is applicable for the following fields: formatType, outputMode, vendorData, and status.
1180 No usage found for specified values.
1191 Invalid request, either {field0} or {field1} should be provided in the request. Here, {field0} represents featureId, entId, or eid; and {field1} represents featureName or status.