You are here: Entitlement Management > Entitlement > searchEntitlements

Search Entitlements

Description

Search entitlements by the given query parameters. Empty values of input parameters are ignored.

This Web service is available for both contact login and ISV login.

Default Protocol Method Type URI
HTTPS GET searchEntitlements.xml

Query Parameters

Parameter Description Valid Values Optional
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
customerId The unique record ID of the customer in EMS database. Integer Yes
contactEmailId The contact e-mail ID for the customer. String Yes
lifecycleState

Lifecycle state of the entitlement.

If the login has been done using the loginByContact web service, the lifecycleState parameter has no effect. Only committed entitlements are shown.

String [0 (all), 1 (draft), 2 (complete)]

Default Value: 0

Yes
customerName Name of the customer. String Yes
customerRefId The unique reference ID of the customer. String Yes
pageIndex The starting page number.

Integer (>0)

Default Value: 1

Yes
pageSize

The number of entitlements retrieved by one request.

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

Integer (>0)

Yes
sortCol Sort against the column.

String (startDate, endDate, state, totalCredit, status, contactEmailId, customerName, id)

Default Value: id

Yes
sortOrder The order to sort.

String (asc, desc)

Default Value: desc

Yes
refId1 Information that uniquely identifies the entitlement in a different ERP system. String Yes
refId2 Identifier to store the unique record ID as used by external ERP/CRM systems. String Yes
deploymentType

The deployment type, which can be:

  • 1: for Cloud entitlements
  • 2: for On-premise entitlements (feature level and entitlement level)

If the login has been done using the loginByContact web service, the deploymentType parameter has no effect. All entitlements irrespective of their deployment type are shown.

Integer Yes
lastModified Creation or Modification time stamp. Long Yes
startdate

Start date of the entitlement.

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

String (yyyy-mm- dd) Yes
enddate End date of the entitlement. String (yyyy-mm- dd) 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.

By default, only enabled and disabled entitlements are included 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 searchEntitlements.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/searchEntitlements.xml");
    query = new StringBuffer();
    setParameter("customerName", "");
    setParameter("lastModified", "");
    setParameter("sortOrder", "");
    setParameter("pageSize", "");
    setParameter("sortCol", "");
    setParameter("eid", "");
    setParameter("contactEmailId", "");
    setParameter("lifecycleState", "");
    setParameter("pageIndex", "");
    setParameter("refId2", "");
    setParameter("customerId", "1");
    setParameter("customerRefId", "");
    setParameter("refId1", "");
    setParameter("deploymentType", "");
   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 + "&"); } } }
See Also:

Output Format for Failure

Sample Response

For Cloud Deployment

<emsResponse>
  <stat>ok</stat>
  <entitlements>
    <entitlement>
      <entId>10</entId>
      <eid>101ab94****</eid>
      <entitlementType>enterprise</entitlementType>
      <startDate>2014-03-04</startDate>
 <?xml version="1.0" encoding="UTF-8"?>
<emsResponse>
   <stat>ok</stat>
   <entitlements>
      <entitlement>
         <entId>8</entId>
         <eid>a09381****</eid>
         <entitlementType>enterprise</entitlementType>
         <startDate>2010-01-01</startDate>
         <endDate>2020-01-01</endDate>
         <customer>
            <customerId>1</customerId>
            <customerName>cl</customerName>
            <customerRefId>cl</customerRefId>
         </customer>
         <contact>
            <contactId>1</contactId>
            <contactEmailId>cl@cl.com</contactEmailId>
         </contact>
         <alternateEmailId />
         <state>2</state>
         <status>0</status>
         <refId1 />
         <refId2 />
         <deploymentType>Cloud</deploymentType>
         <creationTime>1413440736000</creationTime>
         <modificationTime>1413441431000</modificationTime>
         <timezone>(GMT) Greenwich Mean Time, : Dublin, Edinburgh, Lisbon, London</timezone>
      </entitlement>
   </entitlements>
   <total>1</total>
</emsResponse>

For On-premise Deployment

<?xml version="1.0" encoding="UTF-8"?>
<emsResponse>
   <stat>ok</stat>
   <entitlements>
      <entitlement>
         <entId>6</entId>
         <eid>0f6c7e****</eid>
         <entitlementType>enterprise</entitlementType>
         <startDate>2015-04-08</startDate>
         <endDate>2500-12-31</endDate>
         <customer>
            <customerId>4</customerId>
            <customerName>EL</customerName>
            <customerRefId>EL</customerRefId>
         </customer>
         <contact>
            <contactId>5</contactId>
            <contactEmailId>el@el.com</contactEmailId>
         </contact>
         <alternateEmailId />
         <state>2</state>
         <status>0</status>
         <refId1 />
         <refId2 />
         <featureCachingMode>Entitlement Level</featureCachingMode>
         <deploymentType>On-Premise</deploymentType>
         <stationCount>12</stationCount>
         <creationTime>1428463880000</creationTime>
         <modificationTime>1428464275000</modificationTime>
         <timezone>(GMT) Greenwich Mean Time, : Dublin, Edinburgh, Lisbon, London</timezone>
         <detachInterval>Never Expires</detachInterval>
         <usageCollection>On</usageCollection>
         <vmEnabled>true</vmEnabled>
         <cloneProtection>true</cloneProtection>
      </entitlement>
   </entitlements>
   <total>1</total>
</emsResponse>



Notes

For on-premise entitlements, the Web services response includes an additional tag <featureCachingMode>. The value of this tag can be one of the following:

Error Codes

Error Code Description
100 Invalid request parameter.
101 You are not authorized to use this service.
109 The sort order value is not valid. Specify asc or desc.
110 The page index value is not valid. Specify any positive integer value greater than 0.
111 The page size value is not valid. Specify any positive integer value greater than 0.
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.]
124 Invalid sortColumn. Valid values are startdate, enddate, state, status, contactemailid, customername, id.
128 You should log on first.
132 The URL address does not exist.
634 The customer ID cannot be a negative value.
635 Invalid lifecycleState. Valid values are '0'( for all), '1'(for draft) or '2'(for complete).
1068 Valid values for deploymentType are 1(Cloud) and 2(On-Premise).
1080 {field} should be of dataType long. [Note: This error code is applicable for the field - lastModified.]
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.
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.