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.

Notes:

Description

Default Protocol Method Type URI

HTTPS

GET

getRawUsageDataForCustomer.xml

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

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
eid

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

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.

Integer

(>0)

Yes
featureName

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
outputMode

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
formatType

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
pageSize

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

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 getRawUsageDataForCustomer.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/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];
         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 Response

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

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

For formatType = ExcelFile and outputMode = Advance

<emsResponse>
	<stat>ok</stat>
	<url>https://local.sentinelcloud.com:8443/ems/usageData_2014_09_16_11_44_19.zip</url>
</emsResponse>

For formatType = ExcelFile and outputMode = Basic

<emsResponse>
	<stat>ok</stat>
	<url>https://local.sentinelcloud.com:8443/ems/usageData_1_2014_09_16_11_44_19.zip</url>
</emsResponse>

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 = "usagelog.zip";
 
            // 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();
                e.MoveNext();
 
                zip.ExtractSelectedEntries(e.Current.FileName, ExtractExistingFileAction.OverwriteSilently);
 
                file_name = e.Current.FileName;
            }
 
            File.Delete(zip_file);
        }
See Also:

Output Format for Failure

Error Codes

Error Code Description

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.

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

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

1008

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.