You are here: Usage Information > getRawUsageDataForCustomer

Retrieve Raw Usage Data for a Customer

Retrieves raw usage data.This Web service provides information of customer,entitlement, products, features, users, usageType, vendor data, and client machine's host address.



Default Protocol Method Type URI




Query Parameters

Parameter Description Valid Values Optional
customerId The unique record ID of the customer in EMS database. Integer Mandatory if outputMode is Basic. Otherwise, it is optional.

Start date, in GMT, from when the usage data is to be obtained. The startDate is appended with 00:00:00.

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

String (yyyy-mm- dd) No
endDate End date, in GMT, till when the usage data is to be obtained. The endDate is appended with 23:59:59. String (yyyy-mm- dd) No
customerRefId The unique reference ID of the customer. String Yes

Specify the EID to login to EMS.

Please note that EID and EntId are different.

  • EID: It is a globally unique identifier assigned to a newly created entitlement. This EID can be used by end users for EMS login (if configured). You can view EID for a given entitlement on EMS GUI, for example on View Entitlement Certificate screen.
  • EntId: It is the web service handle returned on the successful creation of an entitlement. This handle can be used for calling other web services related to entitlement management.
String Yes
productName Name of the product. String Mandatory if productVersion is provided. Otherwise, it is optional.
productVersion Version of the product. String Mandatory if productName is provided. Otherwise, it is optional.

Feature ID.

The authorization is done either on featureID or on featureName. You should provide only one of these feature identifiers; otherwise an error is returned.

Please note that ftrId and featureId are different.

  • ftrId: It is an auto-generated, unique record ID of a feature in EMS database.
  • featureId: It is the unique identification code provided by software provider for a feature. It is used in license enforcement.




The unique feature name.

The authorization is done either on featureID or on featureName. You should provide only one of these feature identifiers; otherwise an error is returned.

String Yes
usageType Type of data aggregation. Possible values are 1 (Count Based) and 2 (Time Based). Integer Yes

Level of details required in output. Possible values are:

  • Basic: Provides the basic information. It allows search based on the following parameters only: startDate, endDate, and customerRefId.
  • Advance: Provides a detailed output containing additional fields.

The default is Basic.

String Yes

Format for the response. Possible values are:

  • ExcelFile: Provides the URL of a zipped excel file, which contains the retrieved information.
  • Records: Provides information in XML format. This option is applicable only when outputMode is Advance.

The default is ExcelFile.

String Yes
pageIndex The starting page number. Integer (>0) Default Value: 1 Yes

Number of records to be displayed on a page.

Its default value can be configured from EMS Admin Console by using the Max Records Per Response (Web Services) property.

Integer (>0) Yes

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

Sample Code


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 getRawUsageDataForCustomer.xml()throws Exception  {
        	return "login failed";
    HttpContext context = new BasicHttpContext();
    context.setAttribute(ClientContext.USER_TOKEN, principal);
         HttpGet get = new HttpGet("https://localhost:8443/ems/3.6/getRawUsageDataForCustomer.xml");
    query = new StringBuffer();
    setParameter("startDate", "2014-01-01");
    setParameter("featureName", "");
    setParameter("outputMode", "Advance");
    setParameter("usageType", "");
    setParameter("endDate", "2015-01-01");
    setParameter("productVersion", "");
    setParameter("eid", "");
    setParameter("pageIndex", "");
    setParameter("formatType", "Records");
    setParameter("customerId", "");
    setParameter("customerRefId", "");
    setParameter("featureId", "");
    setParameter("pageSize", "");
    setParameter("productName", "");
    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];
    	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 Response

For formatType = Records (available only for outputMode = Advance)

  <customer refId="FL">
    <entitlement id="717fb21a-37ca-4b99-9405-9ab3cc88abb4">
      <product name="Prod1.1" version="1.0">
        <feature name="FL_DETACH" usageType="TimeBased">
            <user id="user">
              <record id="1">
                <startDateTime>2014-08-13 10:01:58.0</startDateTime>
                <endDateTime>2014-08-13 10:01:58.0</endDateTime>
              <record id="2">
                <startDateTime>2014-08-21 04:50:09.0</startDateTime>
                <endDateTime>2014-08-21 04:50:09.0</endDateTime>
              <!--Similarly records for other records -->
            <!--Similarly records for other users -->
        <!--Similarly records for other feature -->
      <!--Similarly records for other products -->
    <!--Similarly records for other entitlements of this customer -->
  <!--Similarly records for other other customers -->

For formatType = ExcelFile and outputMode = Advance


For formatType = ExcelFile and outputMode = Basic


Downloading Zip file when formatType is ExcelFile

The zip file should be downloaded in the same session in which the Web service has been called. The following C# snippet shows how to download the zip file:

        private void dowloadAndUnzipUsageLog(string url, out string file_name)
            file_name = String.Empty;
            string zip_file = "";
            // Download zip file
            using( WebClient webClient = new WebClient() )
                webClient.DownloadFile(url, zip_file);
            // Unzip, should only be the single file
            using (ZipFile zip = new ZipFile(zip_file))
                IEnumerator<ZipEntry> e = zip.GetEnumerator();
                zip.ExtractSelectedEntries(e.Current.FileName, ExtractExistingFileAction.OverwriteSilently);
                file_name = e.Current.FileName;
See Also:

Output Format for Failure

Error Codes

Error Code Description


You are not authorized to use this service.

102 Invalid data entered.


An internal error occurred! Please report the error to System administrator.


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

512 The customer does not exist.
617 Start date cannot be greater than end date.


Unable to retrieve Usage Data.

1175 {field0} is mandatory if {field1} is provided. Note: This error code is applicable for the following fields: productName and productVersion.
1176 Invalid {field}. Note: This error code is applicable for the following fields: formatType, outputMode, vendorData, and status.
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.