Revision Action/Change Date. A Sentinel Cloud 3.0 Release December 2012 B Sentinel Cloud 3.1 Release April 2013 C

Transcription

1

2 ii Sentinel Cloud Web Services Guide Software Version This documentation is applicable for the Sentinel Cloud EMS Version 3.4. Revision History Part Number , Revision E Revision Action/Change Date A Sentinel Cloud 3.0 Release December 2012 B Sentinel Cloud 3.1 Release April 2013 C D Sentinel Cloud 3.2 Release. New Web services related to on-premise machine registration added. Sentinel Cloud 3.3 Release. Added new Web services: addentitlementfingerprint, deleteentitlementfingerprint, retrieveentitlementfingerprint, and retrievepeakcapacity July 2013 September 2013 E Sentinel Cloud 3.4 Release. December 2013 Disclaimer and Copyrights Copyright 2013, SafeNet, Inc. All rights reserved. We have attempted to make this document complete, accurate, and useful, but we cannot guarantee it to be perfect. When we discover errors or omissions, or they are brought to our attention, we endeavor to correct them in succeeding releases of the product. SafeNet, Inc., is not responsible for any direct or indirect damages or loss of business resulting from inaccuracies or omissions contained herein. The specifications contained in this document are subject to change without notice. SafeNet, Sentinel, and EMS are registered and/or unregistered trademarks of SafeNet, Inc., in the United States and other countries. All other trademarks referenced herein are registered and/or unregistered trademarks of their respective owners.

3 Table of Contents Table of Contents iii Preface v Chapter 1: Introduction 1 Chapter 2: Web Services Integration About emswsdemo Accessing the emswsdemo URL Using the Java Code Samples for Calling EMS Web Services Getting Ready The Concept Output Format for Failure Web Services Call Syntax 6 Chapter 3: Web Service Interfaces Version Information Obtain Web Service Version Authorization Vendor Login Customer Login By EID Customer Contact Login by User ID and Password Close Session Managing Catalog Elements Namespace Feature Product License Model Service Agreement Managing Entitlements Entitlement Entitlement Line Item Entitlement License Model Attributes Entitlement Service Agreement Attributes Enterprise User Identities Reconfiguring Entitlements State and Status Information 137

4 iv Sentinel Cloud Web Services Guide Retrieve License State Retrieve Contract Status Change Contract Status Retrieve Contract Line Item Status Change Contract Line Item Status Usage Information Retrieve Usage Log Retrieve Customer Usage Log Retrieve Customer Usage Log for Vendor Information Retrieve Usage Bill View Concurrent Sessions Retrieve Current Usage Count Retrieve Peak Capacity Managing Customers and Contacts Create Customer Create Contact Search Customers Retrieve Customer Details by ID Retrieve Customer Details by Name Retrieve Customer by Customer Ref ID Check Duplicate Customer Names Retrieve Customer Reference ID by Customer Name Delete Customer Retrieve Time Zone List Custom Attributes Create Template Attribute Find a Custom Attribute by Template Type and Entity ID Search Entity By Custom Attribute Update Custom Attribute Delete Custom Attribute On-premise Machine Registration Add Fingerprint Retrieve Fingerprint Delete Fingerprint Add Entitlement Fingerprint Retrieve Entitlement Fingerprint Delete Entitlement Fingerprint 227 Error Codes 231 Glossary 237 Index 241

5 Preface Who Should Read This Document? This document is intended for software providers who want to integrate entitlement management capabilities in their application by using the Sentinel EMS Web services. Conventions Used in This Document Convention Bold lettering Courier Italic lettering Denotes keystrokes, menu items, window names, and fields. Denotes syntax, prompts, and code examples. Denotes file names and directory names. Else, used for emphasis. Documentation Resources Document What's in it? Who Should Read it? EMS User s Guide EMS Web Services Guide EMS Web Services Cheatsheet Cloud Run-time Guide Cloud Run-time Java Demo Application ReadMe Cloud Run-time.NET Reference ReadMe Cloud Run-time C Reference ReadMe Quick Start Guide Release Notes Reference for using the Sentinel Cloud EMS Web portal for Sentinel Cloud Services Reference for using the Sentinel Cloud EMS Web services A quick reference document that summarizes all the available EMS Web services Sentinel Cloud Run-time API reference A demo application and reference for using the Cloud Run-time APIs in Java Sample reference for using the Cloud Run-time APIs in.net Sample reference for using the Cloud Run-time APIs in C Document to help you quickly start with Sentinel Cloud Contains product overview, summary of new features, and enhancements Product Managers and software providers responsible for delivering and deploying the products Developers responsible for integrating Sentinel EMS with backend systems Developers responsible for integrating Sentinel Cloud EMS with backend systems Developers responsible for integrating APIs in the licensed application Developers and Product Managers Developers responsible for integrating APIs in.net applications Developers responsible for integrating APIs in C applications Developers and Project Managers All

6 vi Sentinel Cloud Web Services Guide Document What's in it? Who Should Read it? Cloud Connect Web Services Guide Cloud Connect Web Services Python Sample ReadMe Acknowledgements Reference for using the Sentinel Cloud Connect Web services Sample reference for using the Cloud Connect Web Services in Python Acknowledgements of the thirdparty software used in the product Developers responsible for integrating Cloud Connect Web Services in the licensed application Developers responsible for integrating Cloud Connect Web Services in Python applications General document Installation Guide Contains installation information Administrators responsible for installing Sentinel Cloud Services Migration Guide Obtaining Support Contains information helpful in migrating from one version to another You can contact us using any of the following options: Developers and Project Managers Business Contacts - To find the nearest office or distributor, use the following URL: Technical Support - To obtain assistance in using SafeNet products, feel free to contact our Technical Support team: o o o Phone: (US toll free), (International) [email protected] URL: Downloads - You may want to check out updated installers and other components here: Documentation Feedback To help us improve future versions of the documentation, we want to know about any corrections, clarifications, or further information you would find useful. When you contact us, please include the following information: The title, part number (if applicable), and version of the document you are referring to The version of the product you are using Your name, company name, job title, phone number, and ID Send us at: [email protected]

7 1 Chapter 1: Introduction Sentinel EMS is a comprehensive entitlement management system that allows you to generate, manage, and fulfill licenses. EMS provides a GUI as well as a Web service interface for the user to communicate with the Web server. This guide lists the various Web service interfaces along with sample codes. EMS uses RESTLike Web services to facilitate integration of EMS data and transactions with external IT systems like CRM and ERP. Each Web service call is a standard HTTPS request. The response is sent in XML format. The following table lists the Cloud EMS entities and the operations which can be performed on entities by using Web services: Entity Namespace Operations Retrieve Create Update Delete Feature Product License Model Service Agreement Customer Contact Entitlement Entitlement's Line Item Entitlement's License Model Entitlement's Service Agreement Enterprise User Identities Custom Attributes Machine Fingerprint

8 2 Chapter 1: Introduction The check symbol ( ) indicates that the Web service for this operation is available.

9 Chapter 2: Web Services Integration You can call EMS Web services using any programming language like Java, C#, and C. Most of the operations that can be performed using the EMS portal can also be performed using the Web services. EMS Web services are REST based, which is a light-weight and better performing style of network architecture compared to the heavy-weight SOAP style. This chapter provides the steps to integrate EMS Web services in your Java/C# applications About emswsdemo Sentinel Cloud EMS provides a demo application - emswsdemo - using which you can test the EMS Web services. Using this tool you can also generate sample codes for the available Web services Accessing the emswsdemo URL Please contact SafeNet Technical Support for access to the emswsdemo tool Using the Java Code Samples for Calling EMS Web Services The Java code samples provided in this Web Service Guide use Apache HTTPClient to access the EMS Web services. The Web services require authentication before you can use them in your code. This section first explains how to authenticate using EMS user name and password, and then provides an example to call a Web service for getting details of a product Getting Ready 1. Download or get a copy of HttpClient and its dependencies. Next, include them in your system's classpath. 2. The sample assumes that you have created a property file to read different EMS settings like EMS server name, http port, https port, etc. One such property file is present in the emswsdemo tool. You can modify the same to use it in your application. Following entries should be present in your property file: server = localhost:8080 sslserver = localhost:8443 truststore = c:/cacerts truststorepass = changeit

10 4 Chapter 2: Web Services Integration emscontext = ems emswsversion = 3.4 Include this property file in your system's classpath The Concept The general process for executing EMS Web service URLs can be divided into the following steps. 1. Read different values like server URL, trust store location, password from property file. Properties properties = new Properties();InputStream file = Thread.currentThread ().getcontextclassloader() getresourceasstream(emswsdemofile);if (file == null) { throw new Exception("unable to load file '" + emswsdemofile + "'");properties.load (file); server = properties.getproperty("server"); sslserver = properties.getproperty("sslserver"); truststore = properties.getproperty("truststore"); truststorepass = properties.getproperty("truststorepass"); emscontext = properties.getproperty("emscontext"); emswsversion = properties.getproperty("emswsversion"); 2. Set javax.net.ssl.truststore and javax.net.ssl.truststorepassword to authenticate the EMS Server specified in server property. System.setProperty("javax.net.ssl.trustStore", truststore); System.setProperty("javax.net.ssl.trustStorePassword", truststorepass); 3. To access a Web service, you need to determine the Web Service version first. Call the getwebserviceversioninfo to get the version information. First create an object of HTTPContext and provide the URL using GET method as shown below: HttpContext context = new BasicHttpContext(); DefaultHttpClient httpclient = new DefaultHttpClient(); context.setattribute(clientcontext.user_token, principal); HttpGet get = new HttpGet(" query = new StringBuffer(); 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);

11 2.2. Using the Java Code Samples for Calling EMS Web Services 5 entity.consumecontent(); String result = new String(b); 4. After determining the Web service version, you need to log on using verifylogin.xml. To implement this, create an object of HttpContext and call the EMS log on URL using POST method as shown below: HttpContext context = new BasicHttpContext(); HttpPost post = new HttpPost( " List<NameValuePair> nvps = new ArrayList<NameValuePair>(); nvps.add(new BasicNameValuePair("userName", "xxxxx")); nvps.add(new BasicNameValuePair("password", "xxxxx")); post.setentity(new UrlEncodedFormEntity(nvps, HTTP.UTF_8)); HttpResponse emsresponse = httpclient.execute(post, context); HttpEntity entity = emsresponse.getentity(); byte[] b = null; if (entity!= null) { long l = entity.getcontentlength(); b = new byte[(int) l]; entity.getcontent().read(b); entity.consumecontent(); principal = (Principal) context.getattribute(clientcontext.user_token); String loginresult = new String(b); if (loginresult.indexof("\"stat\":\"ok\"") > 0) return true; else return false; Once login is successful, store ClientContext.USER_TOKEN in a variable to use in further calls. This will help you to authenticate once for one session of your application.

12 6 Chapter 2: Web Services Integration 5. After login is successful, you can call any Web service method to get/create/update different EMS entities. For example, to get details of a product, you need to execute the Web service getproductbyid.xml. First create an object of HTTPContext, set ClientContext.USER_ TOKEN, add request parameters, and execute and parse the response. HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpGet get = new HttpGet( " query = new StringBuffer(); setparameter("productid", "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); Output Format for Failure <?xml version="1.0" encoding="utf-8"?> <emsresponse> <code>100</code> <desc>invalid request parameter</desc> <stat>fail</stat> </emsresponse> 2.3. Web Services Call Syntax A Web service call in Sentinel Cloud contains details of how to access an EMS entity. You need to specify the EMS host, EMS port, and Web services version in a Web service call. A Web Service call or URI has the following syntax: Example: The various parts of the Web service call syntax identify:

13 2.3. Web Services Call Syntax 7 host: The IP address or fully-qualified domain name of your EMS host. port: The port to use when establishing a connection with EMS host. emscontext: The vendor-specific EMS context. emswsversion: The version of Sentinel Cloud Web Services. You can use the getwebserviceversion Web service to obtain the version information. WSname: The name of the Web service you want to call.

14

15 Chapter 3: Web Service Interfaces This chapter lists all the Web services available in EMS and explains how to use REST to make requests through the EMS Web Services. REST allows you to make calls to EMS by passing parameters and values. EMS returns its response in XML format. The Web services available in EMS are grouped into the following categories: Version Information Authorization Managing Catalog Elements Managing Entitlements State and Status Information Usage Information Managing Customers and Contacts Custom Attributes On-premise Machine Registration 215

16 10 Chapter 3: Web Service Interfaces For each Web service, the default method supported is HTTPS. SSL is enabled in EMS by default, and hence HTTPS is supported. However, if your EMS administrator has disabled SSL then you have to use HTTP for all the Web services. The query/input parameters are listed for each Web service. The query parameters are case sensitive. Their data type and allowed values are mentioned under the column Valid Values for each Web service. Required parameters must be provided for the request to succeed. Each Web service contains a sample code. Important The POST parameters passed to a Web Service must be in a URL Encoded form. All Web services support internationalization, which allows you to store and transmit data in languages other than English, such as Japanese. The complete code sample is provided in the first two Web services (Vendor Login and Customer Login By EID). For rest of the Web services, the common part of the code sample is omitted. The sample response for both success and failure conditions are also listed. For error handling, the error codes and their description are provided for each Web service. To see the master list of all the error codes refer to Error Codes. If you call an HTTPS based Web service over HTTP, an error code is returned.

17 3.1. Version Information Version Information Obtain Web Service Version Retrieves the Web services version. You need to specify the version obtained with getwebserviceversion in all Web service calls. Default Protocol Method Type URI HTTPS GET getwebserviceversion.xml Query Parameters None 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 getwebserviceversion.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpGet get = new HttpGet(" query = new StringBuffer(); 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("")) {

18 12 Chapter 3: Web Service Interfaces query.append("?" + key + "=" + value + "&"); else { query.append(key + "=" + value + "&"); Sample Response <?xml version="1.0" encoding="utf-8"?> <emsresponse> <stat>ok</stat> <webserviceversion>3.4</webserviceversion> </emsresponse> See Also: Output Format for Failure Error Codes Error Code 100 Invalid request parameter. 107 An internal error occurred! Please report the error to System administrator. 128 You should log on first Invalid Web service version provided 1088 The EMS system is running on HTTPS. Please provide the correct Web service URL.

19 3.2. Authorization Authorization This section lists the Web services provided to log in and log out to EMS server. A client application must log in and obtain a sessionid before making any other Web service calls. When a client application invokes the verifylogin method, it passes user name and password as user credentials. Upon invocation, the EMS server authorizes the credentials and returns a sessionid for the session to use in all subsequent Web service calls. The client application can use the closesession Web service to log out of EMS server. Your can configure log in for your customers/end users by using the method loginbyeid and loginbycontact. The closesession method is common for both vendor and end user log in. Method URI POST verifylogin.xml Vendor Login POST loginbyeid.xml Customer Login By EID POST loginbycontact.xml Customer Contact Login by User ID and Password POST closesession.xml Close Session Vendor Login Use this method to log in to the EMS server and start a client session. A client application must log in and obtain a sessionid before making any other Web services calls. When a client application invokes the verifylogin method it passes in a user name and password as user credentials. Upon invocation, the EMS server authorizes the credentials and returns a sessionid for the session to use in all subsequent Web service calls. Default Protocol Method Type URI HTTPS POST verifylogin.xml Post Parameters Parameter Valid Values Optional username Login user name String No password Sample Code Login password associated with the specified user name String No import java.io.ioexception; import java.io.inputstream; import java.security.principal; import java.util.arraylist;

20 14 Chapter 3: Web Service Interfaces import java.util.list; import java.util.properties; import org.apache.http.httpentity; import org.apache.http.httpresponse; import org.apache.http.client.entity.urlencodedformentity; import org.apache.http.client.methods.httppost; import org.apache.http.client.protocol.clientcontext; import org.apache.http.impl.client.defaulthttpclient; import org.apache.http.message.basicnamevaluepair; import org.apache.http.protocol.basichttpcontext; import org.apache.http.protocol.http; import org.apache.http.protocol.httpcontext; import org.apache.http.namevaluepair; import org.apache.http.client.methods.httpget; import org.apache.http.params.basichttpparams; import org.apache.http.params.httpparams; public class EMSSample { private static DefaultHttpClient httpclient = new DefaultHttpClient(); private static Principal principal = null; private static String server; private static String sslserver; private static String truststore; private static String truststorepass; private static String emswsdemofile = "emswsdemo.properties"; public static void loadpropertiesfile()throws Exception { Properties properties = new Properties(); InputStream file = Thread.currentThread().getContextClassLoader ().getresourceasstream(emswsdemofile); if(file == null) { throw new Exception("unable to load file '" + emswsdemofile + "'"); properties.load(file); truststore = properties.getproperty("truststore"); truststorepass = properties.getproperty("truststorepass"); System.setProperty("javax.net.ssl.trustStore", truststore); System.setProperty("javax.net.ssl.trustStorePassword", truststorepass); public static boolean loginbyeid() throws Exception{ loadpropertiesfile(); HttpContext context = new BasicHttpContext(); HttpPost post = new HttpPost( " List<NameValuePair> nvps = new ArrayList<NameValuePair>(); nvps.add(new BasicNameValuePair("eid", "")); post.setentity(new UrlEncodedFormEntity(nvps, HTTP.UTF_8)); HttpResponse emsresponse = httpclient.execute(post, context); HttpEntity entity = emsresponse.getentity(); byte[] b = null; if (entity!= null) { long l = entity.getcontentlength(); b = new byte[(int) l]; entity.getcontent().read(b); entity.consumecontent(); principal = (Principal) context.getattribute(clientcontext.user_token); String loginresult = new String(b); if (loginresult.indexof("\"stat\":\"ok\"")>0)

21 3.2. Authorization 15 else return true; return false; Sample Response <?xml version= 1.0 encoding= UTF-8?> <emsresponse> <sessionid>1634c549efaa400c5c b7d9</sessionid> <stat>ok</stat> </emsresponse> See Also: Output Format for Failure Error Codes Error Code 100 Invalid request parameter. 107 An internal error occurred! Please report the error to System administrator. 132 The URL address does not exist. 213 User name cannot be blank. 214 Password cannot be blank. 215 Either username or password is incorrect 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 Customer Login By EID You can use this Web service in your application to configure login by entitlement ID (EID) for your customers/end users. The output are session id and entid. On login by EID, a customer can view details of only one entitlement, the EID of which has been used for login. For a complete list of operations that the customer can perform after login, refer to Sentinel Cloud EMS User's Guide. Default Protocol Method Type URI HTTPS POST loginbyeid.xml

22 16 Chapter 3: Web Service Interfaces Post Parameters Parameter 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. Valid Values String Optional No Sample Code import java.io.ioexception; import java.io.inputstream; import java.security.principal; import java.util.arraylist; import java.util.list; import java.util.properties; import org.apache.http.httpentity; import org.apache.http.httpresponse; import org.apache.http.client.entity.urlencodedformentity; import org.apache.http.client.methods.httppost; import org.apache.http.client.protocol.clientcontext; import org.apache.http.impl.client.defaulthttpclient; import org.apache.http.message.basicnamevaluepair; import org.apache.http.protocol.basichttpcontext; import org.apache.http.protocol.http; import org.apache.http.protocol.httpcontext; import org.apache.http.namevaluepair; import org.apache.http.client.methods.httpget; import org.apache.http.params.basichttpparams; import org.apache.http.params.httpparams; public class EMSSample { private static DefaultHttpClient httpclient = new DefaultHttpClient(); private static Principal principal = null; private static String server; private static String sslserver; private static String truststore; private static String truststorepass; private static String emswsdemofile = "emswsdemo.properties"; public static void loadpropertiesfile() throws Exception { Properties properties = new Properties(); InputStream file = Thread.currentThread().getContextClassLoader().getResourceAsStream(emsWSDemoFile);

23 3.2. Authorization 17 if (file == null) { throw new Exception("unable to load file '" + emswsdemofile + "'"); properties.load(file); server = properties.getproperty("server"); sslserver = properties.getproperty("sslserver"); truststore = properties.getproperty("truststore"); truststorepass = properties.getproperty("truststorepass"); System.setProperty("javax.net.ssl.trustStore", truststore); System.setProperty("javax.net.ssl.trustStorePassword", truststorepass); public static boolean loginbyeid() throws Exception { loadpropertiesfile(); HttpContext context = new BasicHttpContext(); HttpPost post = new HttpPost(" List<NameValuePair> nvps = new ArrayList<NameValuePair>(); nvps.add(new BasicNameValuePair("eid", "")); post.setentity(new UrlEncodedFormEntity(nvps, HTTP.UTF_8)); HttpResponse emsresponse = httpclient.execute(post, context); HttpEntity entity = emsresponse.getentity(); byte[] b = null; if (entity!= null) { long l = entity.getcontentlength(); b = new byte[(int) l]; entity.getcontent().read(b); entity.consumecontent(); principal = (Principal) context.getattribute(clientcontext.user_token); String loginresult = new String(b); if (loginresult.indexof("\"stat\":\"ok\"") > 0) return true; else return false; Sample Response <?xml version= 1.0 encoding= UTF-8?> <emsresponse> <entid>30</entid> <sessionid>1634c549efaa400c5c b7d9</sessionid> <stat>ok</stat> </emsresponse> See Also: Output Format for Failure Error Codes Error Code 100 Invalid request parameter.

24 18 Chapter 3: Web Service Interfaces Error Code 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, and granularity.] 132 The URL address does not exist. 621 Entitlement does not exist. Retry with a correct ID. 650 eid cannot be null 656 Entitlement not yet started, please contact administrator 657 Entitlement expired, please contact administrator. 658 Entitlement is not in complete state, please contact Administrator 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 Customer Contact Login by User ID and Password You can use this Web service in your application to configure customer/end user login by contact e- mail ID and password. The output parameters are sessionid and entid. On login by user ID and password, a contact can view details of all the entitlements created for the customer. For a complete list of operations that the customer can perform after login, refer to Sentinel Cloud EMS User's Guide. Default Protocol Method Type URI HTTPS POST loginbycontact.xml Post Parameters Parameter Valid Values Optional id ID of the contact. String No password Sample Code Login password associated with the contact. String No import java.io.ioexception; import java.io.inputstream; import java.security.principal; import java.util.arraylist; import java.util.list; import java.util.properties;

25 3.2. Authorization 19 import org.apache.http.httpentity; import org.apache.http.httpresponse; import org.apache.http.client.entity.urlencodedformentity; import org.apache.http.client.methods.httppost; import org.apache.http.client.protocol.clientcontext; import org.apache.http.impl.client.defaulthttpclient; import org.apache.http.message.basicnamevaluepair; import org.apache.http.protocol.basichttpcontext; import org.apache.http.protocol.http; import org.apache.http.protocol.httpcontext; import org.apache.http.namevaluepair; import org.apache.http.client.methods.httpget; import org.apache.http.params.basichttpparams; import org.apache.http.params.httpparams; public class EMSSample { private static DefaultHttpClient httpclient = new DefaultHttpClient(); private static Principal principal = null; private static String server; private static String sslserver; private static String truststore; private static String truststorepass; private static String emswsdemofile = "emswsdemo.properties"; public static void loadpropertiesfile()throws Exception { Properties properties = new Properties(); InputStream file = Thread.currentThread().getContextClassLoader ().getresourceasstream(emswsdemofile); if(file == null) { throw new Exception("unable to load file '" + emswsdemofile + "'"); properties.load(file); server = properties.getproperty("server"); sslserver = properties.getproperty("sslserver"); truststore = properties.getproperty("truststore"); truststorepass = properties.getproperty("truststorepass"); System.setProperty("javax.net.ssl.trustStore", truststore); System.setProperty("javax.net.ssl.trustStorePassword", truststorepass); public static boolean loginbycontact() throws Exception{ loadpropertiesfile(); HttpContext context = new BasicHttpContext(); HttpPost post = new HttpPost( " List<NameValuePair> nvps = new ArrayList<NameValuePair>(); nvps.add(new BasicNameValuePair(" Id", "")); nvps.add(new BasicNameValuePair("password", "")); post.setentity(new UrlEncodedFormEntity(nvps, HTTP.UTF_8)); HttpResponse emsresponse = httpclient.execute(post, context); HttpEntity entity = emsresponse.getentity(); byte[] b = null; if (entity!= null) { long l = entity.getcontentlength(); b = new byte[(int) l]; entity.getcontent().read(b); entity.consumecontent(); principal = (Principal) context.getattribute(clientcontext.user_token); String loginresult = new String(b);

26 20 Chapter 3: Web Service Interfaces if (loginresult.indexof("\"stat\":\"ok\"")>0) return true; else return false; Sample Response <?xml version="1.0" encoding="utf-8"?> <emsresponse> <entids> <entid>98</entid> <entid>97</entid> <entid>90</entid> </entids> <sessionid>b9902ff d71882bcd51e71a85f</sessionid> <stat>ok</stat> </emsresponse> See Also: Output Format for Failure Error Codes Error Code 214 Password cannot be blank id cannot be blank Id or Password is incorrect, please retry to login. 218 Your account has been disabled. Please contact Administrator! 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 Close Session Close the session and log out from EMS. This Web service is common for both vendor login and customer login. Default Protocol Method Type URI HTTPS POST closesession.xml Post Parameters None

27 3.2. Authorization 21 Sample Code import java.io.ioexception; import org.apache.http.params.httpparams; public class EMSSample { private static DefaultHttpClient httpclient = new DefaultHttpClient(); private static Principal principal = null; public static String closesession.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpPost post = new HttpPost(" List<NameValuePair> nvps = new ArrayList<NameValuePair>(); post.setentity(new UrlEncodedFormEntity(nvps, HTTP.UTF_8)); HttpResponse response = httpclient.execute(post, 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); Sample Response <?xml version= 1.0 encoding= UTF-8?> <emsresponse> <stat>ok</stat> </emsresponse> See Also: Output Format for Failure Error Codes Error Code 128 You should log on first 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.

28 22 Chapter 3: Web Service Interfaces 3.3. Managing Catalog Elements The Web services to manage namespaces, features, and products are listed in this section. The diagram below provides a quick overview of catalog Web services and their flow. Catalog Web Services The catalog Web services are grouped into the following categories: Namespace Feature Product License Model Service Agreement 65

29 3.3. Managing Catalog Elements Namespace The following table summarizes the RESTlike interfaces supported for the Namespace resource. Method URI POST addnamespace.xml Add Namespace GET namespacelist.xml Retrieve Namespace By Name and Ref IDs Add Namespace Adds a new namespace to EMS. Default Protocol Method Type URI HTTPS POST addnamespace.xml Post Parameters Parameter Valid Values namespacename The namespace name. String No namespace of the namespace. String Yes refid1 Information that uniquely identifies the namespace in a different ERP system. String refid2 A second unique reference ID, similar to Ref ID 1. String Yes Sample Code Optional Yes import java.io.ioexception; import org.apache.http.params.httpparams; public class EMSSample { private static DefaultHttpClient httpclient = new DefaultHttpClient(); private static Principal principal = null; public static String addnamespace.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpPost post = new HttpPost(" List<NameValuePair> nvps = new ArrayList<NameValuePair>(); nvps.add(new BasicNameValuePair("namespaceName", "")); nvps.add(new BasicNameValuePair("refId2", "")); nvps.add(new BasicNameValuePair("refId1", ""));

30 24 Chapter 3: Web Service Interfaces nvps.add(new BasicNameValuePair("namespace", "")); post.setentity(new UrlEncodedFormEntity(nvps, HTTP.UTF_8)); HttpResponse response = httpclient.execute(post, 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); Sample Response <?xml version= 1.0 encoding= UTF-8?> <emsresponse > <namespaceid>4</namespaceid> <stat>ok</stat> </emsresponse> See Also: Output Format for Failure Error Codes Error Code 100 Invalid request parameter. 101 Not authorized to use this product. 107 An internal error occurred! Please report the error to System administrator. 115 Length of {field is {actual value. It cannot be more Than {max value. [Note: This error code is applicable for the fields - billaddr, billaddrcity, billaddrcountry, billaddrstate, billaddrzip, shipaddr, shipaddrcity, shipaddrcountry, shipaddrstate, shipaddrzip, refid1, refid2, contactpassword, description, and default value.] 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, and granularity.] 128 You should log on first. 132 The URL address does not exist. 321 Namespace EMS_NMS already exists. Please try again with different name 1021 Please enter a valid value 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.

31 3.3. Managing Catalog Elements 25 Retrieve Namespace By Name and Ref IDs Retrieve a namespace by name and ref IDs. Default Protocol Method Type URI HTTPS GET namespacelist.xml Query Parameters Parameter Valid Values namespacename Name of the namespace. String Yes refid1 Information that uniquely identifies the license model in a different ERP system. String refid2 A second unique reference ID, similar to Ref ID 1. String Yes lastmodified Creation or Modification time stamp. Long Yes Sample Code Optional Yes 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 namespacelist.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpGet get = new HttpGet(" query = new StringBuffer(); setparameter("namespacename", "char"); setparameter("refid2", "ref2"); setparameter("lastmodified", " "); setparameter("refid1", "ref1"); 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);

32 26 Chapter 3: Web Service Interfaces 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 <emsresponse> <namespaces> <namespace> <creationtime> </creationtime> <deployed>true</deployed> <desc /> <modificationtime> </modificationtime> <namespaceid>1</namespaceid> <namespacename>a</namespacename> <refid1 /> <refid2 /> </namespace> </namespaces> <stat>ok</stat> </emsresponse> See Also: Output Format for Failure Error Codes Error Code 100 Invalid request parameter. 101 Not authorized to use this product. 107 An internal error occurred! Please report the error to System administrator. 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, and granularity.] 128 You should log on first {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.

33 3.3. Managing Catalog Elements Feature The following table summarizes the RESTlike interfaces supported for the Feature resource. Method URI POST addfeature.xml Add Feature POST updatefeature.xml Edit Feature Details POST updatefeaturelmassociation.xml Associate License Model with a Feature GET viewfeaturebyid.xml Retrieving Feature Details for a Given Feature ID POST deletefeature.xml Delete Feature GET featurelist.xml Retrieve Feature By Criteria Add Feature Add a feature to a particular namespace. Default Protocol Method Type URI HTTPS POST addfeature.xml Post Parameters Parameter Valid Values Optional namespacename Specify the namespace. String No featurename Specify the unique feature name. The feature name should be unique across all namespaces. String feature of the feature. String Yes licensemodelids defaultlicensemodel- Id isautogenerate featureid IDs corresponding to the license models chosen. Specify the default license model. Valid values are True or False. If True, then featureid is generated automatically, otherwise the user needs to enter featureid. Default Value: True Feature ID. It needs to be entered if isautogenerate is false. String (1,2, 3 ) Integer (one of license model Id from licensemodelids) Boolean Integer No No No No Mandatory if isautogenerate is false.

34 28 Chapter 3: Web Service Interfaces Parameter Valid Values Optional Feature ID should be in the range for on-premise entitlements. refid1 Identifier 1 to store the unique record ID as used by external ERP/CRM systems. String Yes refid2 A second unique reference ID, similar to Ref ID 1. String Yes Sample Code import java.io.ioexception; import org.apache.http.params.httpparams; public class EMSSample { private static DefaultHttpClient httpclient = new DefaultHttpClient(); private static Principal principal = null; public static String addfeature.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpPost post = new HttpPost(" List<NameValuePair> nvps = new ArrayList<NameValuePair>(); nvps.add(new BasicNameValuePair("featureName", "test")); nvps.add(new BasicNameValuePair("namespaceName", "char")); nvps.add(new BasicNameValuePair("refId2", "Fref2")); nvps.add(new BasicNameValuePair("licenseModelIds", "1")); nvps.add(new BasicNameValuePair("refId1", "Fref1")); nvps.add(new BasicNameValuePair("feature", "test+feature")); nvps.add(new BasicNameValuePair("featureID", "999")); nvps.add(new BasicNameValuePair("defaultLicenseModelId", "1")); nvps.add(new BasicNameValuePair("isAutoGenerate", "false")); post.setentity(new UrlEncodedFormEntity(nvps, HTTP.UTF_8)); HttpResponse response = httpclient.execute(post, 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); Sample Response <?xml version="1.0" encoding="utf-8"?> <emsresponse>

35 3.3. Managing Catalog Elements 29 <ftrid>54</ftrid> <stat>ok</stat> </emsresponse> See Also: Output Format for Failure Error Codes Error Code 100 Invalid request parameter. 101 Not authorized to use this product. 107 An internal error occurred! Please report the error to System administrator. 115 Length of {field is {actual value. It cannot be more Than {max value. [Note: This error code is applicable for the fields - billaddr, billaddrcity, billaddrcountry, billaddrstate, billaddrzip, shipaddr, shipaddrcity, shipaddrcountry, shipaddrstate, shipaddrzip, refid1, refid2, contactpassword, description, and default value.] 118 {field should be of datatype Integer. [Note: This error code is applicable for the fields - License modelid, entid, ftrid, customerid, lmid, templatetype, lineitemid, CustomerId, stationcount,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, 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, and granularity.] 128 You should log on first. 132 The URL address does not exist. 133 Invalid namespace. 322 This Namespace does not exists in the system. 323 Feature {feature already exists. Try again with different name. 345 featureid is mandatory. 411 License model does not exist. 412 Default license model is not from license Model list The specified featureid already exists 1079 Please enter a valid Feature ID, in the range 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.

36 30 Chapter 3: Web Service Interfaces Edit Feature Details Edit the feature details. Default Protocol Method Type URI HTTPS POST updatefeature.xml Post Parameters Parameter ftrid The auto-generated, unique record ID of a feature in EMS database. Note: The ftrid is the handle returned by the addfeature.xml web service. You can retrieve ftrid by using the featurelist.xml web service. Valid Values Optional Integer No feature for the feature. String Yes refid1 Information that uniquely identifies the Feature in a different ERP system. String refid2 A second unique reference ID, similar to Ref ID 1. String Yes Sample Code Yes import java.io.ioexception; import org.apache.http.params.httpparams; public class EMSSample { private static DefaultHttpClient httpclient = new DefaultHttpClient(); private static Principal principal = null; public static String updatefeature.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpPost post = new HttpPost(" List<NameValuePair> nvps = new ArrayList<NameValuePair>(); nvps.add(new BasicNameValuePair("ftrId", "1")); nvps.add(new BasicNameValuePair("refId2", "FRef2")); nvps.add(new BasicNameValuePair("refId1", "FRef1")); nvps.add(new BasicNameValuePair("feature", "Feature+1")); post.setentity(new UrlEncodedFormEntity(nvps, HTTP.UTF_8)); HttpResponse response = httpclient.execute(post, context); HttpEntity entity = response.getentity(); byte[] b = null; if (entity!= null) {

37 3.3. Managing Catalog Elements 31 long l = entity.getcontentlength(); b = new byte[(int) l]; entity.getcontent().read(b); entity.consumecontent(); return new String(b); Sample Response <?xml version="1.0" encoding="utf-8"?> <emsresponse> <stat>ok</stat> </emsresponse> See Also: Output Format for Failure Error Codes Error Code 100 Invalid request parameter. 101 Not authorized to use this product. 102 Invalid data entered 107 An internal error occurred! Please report the error to System administrator. 115 Length of {field is {actual value. It cannot be more Than {max value. [Note: This error code is applicable for the fields - billaddr, billaddrcity, billaddrcountry, billaddrstate, billaddrzip, shipaddr, shipaddrcity, shipaddrcountry, shipaddrstate, shipaddrzip, refid1, refid2, contactpassword, description, and default value.] 118 {field should be of datatype Integer. [Note: This error code is applicable for the fields - License modelid, entid, ftrid, customerid, lmid, templatetype, lineitemid, CustomerId, stationcount,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, and granularity.] 128 You should log on first. 132 The URL address does not exist. 133 Invalid namespace. 309 Unable to find feature. 320 A deployed feature cannot be updated 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.

38 32 Chapter 3: Web Service Interfaces Associate License Model with a Feature Edit the license models associated with a feature. Default Protocol Method Type URI HTTPS POST updatefeaturelmassociation.xml Post Parameters Parameter ftrid The auto-generated, unique record ID of a feature in EMS database. Valid Values Integer licensemodelids List of license model IDs separated by commas. String No defaultlicensemodelid The default license model ID. Integer No Sample Code Optional No import java.io.ioexception; import org.apache.http.params.httpparams; public class EMSSample { private static DefaultHttpClient httpclient = new DefaultHttpClient(); private static Principal principal = null; public static String updatefeaturelmassociation.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpPost post = new HttpPost (" List<NameValuePair> nvps = new ArrayList<NameValuePair>(); nvps.add(new BasicNameValuePair("ftrId", "")); nvps.add(new BasicNameValuePair("licenseModelIds", "")); nvps.add(new BasicNameValuePair("defaultLicenseModelId", "")); post.setentity(new UrlEncodedFormEntity(nvps, HTTP.UTF_8)); HttpResponse response = httpclient.execute(post, 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);

39 3.3. Managing Catalog Elements 33 Sample Response <?xml version="1.0" encoding="utf-8"?> <emsresponse> <stat>ok</stat> </emsresponse> See Also: Output Format for Failure Error Codes Error Code 100 Invalid request parameter. 101 Not authorized to use this product. 102 Invalid data entered 107 An internal error occurred! Please report the error to System administrator. 118 {field should be of datatype Integer. [Note: This error code is applicable for the fields - License modelid, entid, ftrid, customerid, lmid, templatetype, lineitemid, CustomerId, stationcount,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, and granularity.] 128 You should log on first. 132 The URL address does not exist. 133 Invalid namespace. 309 Unable to find feature 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. Retrieving Feature Details for a Given Feature ID Retrieve the details of a feature for a given feature ID. Default Protocol Method Type URI HTTPS GET viewfeaturebyid.xml Query Parameters Parameter Valid Values Optional ftrid The auto-generated, unique record ID of a feature in EMS Integer No

40 34 Chapter 3: Web Service Interfaces Parameter database. Note: The ftrid is the handle returned by the addfeature.xml web service. You can retrieve ftrid by using the featurelist.xml web service. Valid Values Optional 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 viewfeaturebyid.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpGet get = new HttpGet(" query = new StringBuffer(); setparameter("ftrid", ""); 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 <emsresponse> <feature> <licensemodels>

41 3.3. Managing Catalog Elements 35 <licensemodel> <default>1</default> <enfname>sentinel Cloud</enfname> <enfversion>3.4.0</enfversion> <id>2</id> <name>postpaid</name> </licensemodel> <licensemodel> <default>0</default> <enfname>sentinel Cloud</enfname> <enfversion>3.4.0</enfversion> <id>3</id> <name>concurrent</name> </licensemodel> <licensemodel> <default>0</default> <enfname>sentinel Cloud</enfname> <enfversion>3.4.0</enfversion> <id>4</id> <name>prepaid</name> </licensemodel> <licensemodel> <default>0</default> <enfname>sentinel Cloud</enfname> <enfversion>3.4.0</enfversion> <id>1</id> <name>subscription</name> </licensemodel> </licensemodels> <creationtime> </creationtime> <deployed>false</deployed> <desc>test</desc> <enabled>true</enabled> <featureid>1</featureid> <id>1</id> <modificationtime> </modificationtime> <name>feature1</name> <namespaceid>1</namespaceid> <namespacename>microsoft</namespacename> <refid1>test1</refid1> <refid2>test2</refid2> </feature> <stat>ok</stat> </emsresponse> Here, the default tag is set to 1 for the default license model of a feature. See Also: Output Format for Failure Error Codes Error Code 100 Invalid request parameter. 102 Invalid data entered 107 An internal error occurred! Please report the error to System administrator.

42 36 Chapter 3: Web Service Interfaces Error Code 118 {field should be of datatype Integer. [Note: This error code is applicable for the fields - License modelid, entid, ftrid, customerid, lmid, templatetype, lineitemid, CustomerId, stationcount,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, 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, and granularity.] 128 You should log on first. 132 The URL address does not exist. 133 Invalid namespace. 309 Unable to find feature 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. Retrieve Feature By Criteria Retrieves feature details by the specified criteria. This Web service also returns ftrid, which is an auto-generated,unique record ID of a feature as stored in EMS database. It is returned by the addfeature.xml web service on successful creation of a feature. The retrieved ftrid can be used further in web service calls for performing feature management operations. Default Protocol Method Type URI HTTPS GET featurelist.xml Query Parameters Parameter Valid Values Optional namespace Name of the namespace to which the feature belongs. String Yes featureid Feature ID. Please note that ftrid and featureid are different. Integer (>0) Yes ftrid: It is an autogenerated, unique record ID of a feature in EMS

43 3.3. Managing Catalog Elements 37 Parameter Valid Values Optional database. featureid: It is the unique identification code provided by software provider for a feature. It is used in license enforcement. featurename The unique feature name. String Yes refid1 refid2 Lastmodified Information that uniquely identifies the feature in a different ERP system. A second unique reference ID, similar to Ref ID 1. Creation or modification timestamp of the namespace. showassociatedproducts Indicates whether to retrieve the list of products associated with the given feature or not. Sample Code Valid values are True or False. Default Value: False String String Long Boolean Yes Yes Yes Yes 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 featurelist.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpGet get = new HttpGet(" query = new StringBuffer(); setparameter("featurename", ""); setparameter("refid2", ""); setparameter("lastmodified", ""); setparameter("refid1", ""); setparameter("featureid", "");

44 38 Chapter 3: Web Service Interfaces setparameter("showassociatedproducts", ""); setparameter("namespace", ""); 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 <emsresponse> <features> <feature> <creationtime> </creationtime> <deployed>true</deployed> <desc /> <enabled>true</enabled> <id>1</id> <licensemodels> <licensemodel> <default>0</default> <enfname>sentinel Cloud</enfName> <enfversion>3.4.0</enfversion> <id>2</id> <name>postpaid</name> </licensemodel> <licensemodel> <default>0</default> <enfname>sentinel Cloud</enfName> <enfversion>3.4.0</enfversion> <id>3</id> <name>concurrent</name> </licensemodel> <licensemodel> <default>1</default> <enfname>sentinel Cloud</enfName> <enfversion>3.4.0</enfversion> <id>4</id> <name>prepaid</name> </licensemodel> <licensemodel> <default>0</default>

45 3.3. Managing Catalog Elements 39 <enfname>sentinel Cloud</enfName> <enfversion>3.4.0</enfversion> <id>1</id> <name>subscription</name> </licensemodel> </licensemodels> <modificationtime> </modificationtime> <name>f1</name> <namespaceid>1</namespaceid> <namespacename>test</namespacename> <products> <product> <id>4</id> <name>mix2</name> <ver>3.4</ver> </product> <product> <id>1</id> <name>p1</name> <ver>3.4</ver> </product> </products> <refid1 /> <refid2 /> </feature> </features> <stat>ok</stat> </emsresponse> See Also: Output Format for Failure Error Codes Error Code 100 Invalid request parameter. 102 Invalid data entered 107 An internal error occurred! Please report the error to System administrator. 118 {field should be of datatype Integer. [Note: This error code is applicable for the fields - License modelid, entid, ftrid, customerid, lmid, templatetype, lineitemid, CustomerId, stationcount,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, and granularity.] 128 You should log on first. 133 Invalid namespace {field should be of datatype long. [Note: This error code is applicable for the field - lastmodified.] 1081 Invalid Web service version provided

46 40 Chapter 3: Web Service Interfaces Error Code 1084 No Web service version provided 1088 The EMS system is running on HTTPS. Please provide the correct Web service URL. Delete Feature Delete a feature for a given feature ID. The feature you want to delete should not be part of any entitlement. Default Protocol Method Type URI HTTPS POST deletefeature.xml Post Parameters Parameter ftrids Sample Code List of features to be deleted. Specify unique record IDs of features, as stored in EMS database. Valid Values Integer Optional No import java.io.ioexception; import org.apache.http.params.httpparams; public class EMSSample { private static DefaultHttpClient httpclient = new DefaultHttpClient(); private static Principal principal = null; public static String deletefeature.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpPost post = new HttpPost(" List<NameValuePair> nvps = new ArrayList<NameValuePair>(); nvps.add(new BasicNameValuePair("ftrIds", "")); post.setentity(new UrlEncodedFormEntity(nvps, HTTP.UTF_8)); HttpResponse response = httpclient.execute(post, 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);

47 3.3. Managing Catalog Elements 41 Sample Response <?xml version="1.0" encoding="utf-8"?> <emsresponse> <stat>ok</stat> </emsresponse> See Also: Output Format for Failure Error Codes Error Code 100 Invalid request parameter. 101 Not authorized to use this product. 102 Invalid data entered 107 An internal error occurred! Please report the error to System administrator. 118 {field should be of datatype Integer. [Note: This error code is applicable for the fields - License modelid, entid, ftrid, customerid, lmid, templatetype, lineitemid, CustomerId, stationcount,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, 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, and granularity.] 128 You should log on first. 132 The URL address does not exist. 133 Invalid namespace. 309 Unable to find feature. 320 A deployed feature cannot be updated. 343 Feature name is inside a completed/eol product and cannot be deleted 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 Product The following table summarizes the RESTlike interfaces supported for the Product resource.

48 42 Chapter 3: Web Service Interfaces Method URI POST createproduct.xml Create Product POST associatefeatureswithproduct.xml Associate Features with Product POST disassociatefeaturesfromproduct.xml Remove Features from Product POST changeproductlifecyclestage.xml Change Lifecycle Stage of a Product GET getproductbyid.xml Retrieve Product Details by productid GET searchproducts.xml Search Products GET getproductbynameandver.xml Retrieve Product Details By Name and Version Create Product Creates a new product for the specified namespace containing the given features. Default Protocol Method Type URI HTTPS POST createproduct.xml Post Parameters Parameter Valid Values Optional namespacename productname productversion Specify the namespace to which the product belongs. Specify the name of the product to be created. Specify the version of the product to be created. String String String product of the product. String Yes ftrids refid1 refid2 Specify unique record IDs of features (as stored tin EMS database) to be associated with this product. Information that uniquely identifies the Product in a different system, for example, a Product ID in your company's ERP system. A second unique reference ID, similar to Ref ID 1. serviceagreementid Unique identifier of the product agreement. Sample Code String (comma separated integers) String String Integer No No No Yes Yes Yes No import java.io.ioexception;

49 3.3. Managing Catalog Elements 43 import org.apache.http.params.httpparams; public class EMSSample { private static DefaultHttpClient httpclient = new DefaultHttpClient(); private static Principal principal = null; public static String createproduct.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpPost post = new HttpPost(" List<NameValuePair> nvps = new ArrayList<NameValuePair>(); nvps.add(new BasicNameValuePair("refId2", "")); nvps.add(new BasicNameValuePair("namespaceName", "")); nvps.add(new BasicNameValuePair("serviceAgreementID", "")); nvps.add(new BasicNameValuePair("product", "")); nvps.add(new BasicNameValuePair("refId1", "")); nvps.add(new BasicNameValuePair("productVersion", "")); nvps.add(new BasicNameValuePair("productName", "")); nvps.add(new BasicNameValuePair("featureIds", "")); post.setentity(new UrlEncodedFormEntity(nvps, HTTP.UTF_8)); HttpResponse response = httpclient.execute(post, 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); Sample Response <?xml version= 1.0 encoding= UTF-8?> <emsresponse> <productid>20</productid> <stat>ok</stat> </emsresponse> See Also: Output Format for Failure Error Codes Error Code 100 Invalid request parameter. 101 Not authorized to use this product. 107 An internal error occurred! Please report the error to System administrator. 115 Length of {field is {actual value. It cannot be more Than {max value. [Note: This

50 44 Chapter 3: Web Service Interfaces Error Code error code is applicable for the fields - billaddr, billaddrcity, billaddrcountry, billaddrstate, billaddrzip, shipaddr, shipaddrcity, shipaddrcountry, shipaddrstate, shipaddrzip, refid1, refid2, contactpassword, description, and default value.] 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, and granularity.] 128 You should log on first. 132 The URL address does not exist. 133 Invalid namespace. 305 Mentioned feature id should belong to same Namespace As product. 309 Unable to find feature. 312 Product ${productname already exists. Please try again with different name and version Service Agreement not found ftrid(s) should be of type integer 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. Associate Features with Product Associates features with products. Comma separated ftrids are provided as input. The output is the union of already existing features and new features to be associated. Default Protocol Method Type URI HTTPS POST associatefeatureswithproduct.xml Post Parameters Parameter Valid Values Optional productid Specify the product ID. Integer (>0) No ftrids Sample Code Specify unique record IDs of features (as stored in EMS database) to be associated. String (comma separated feature IDs) No import java.io.ioexception; import org.apache.http.params.httpparams;

51 3.3. Managing Catalog Elements 45 public class EMSSample { private static DefaultHttpClient httpclient = new DefaultHttpClient(); private static Principal principal = null; public static String associatefeatureswithproduct.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpPost post = new HttpPost (" List<NameValuePair> nvps = new ArrayList<NameValuePair>(); nvps.add(new BasicNameValuePair("featureIds", "")); nvps.add(new BasicNameValuePair("productId", "")); post.setentity(new UrlEncodedFormEntity(nvps, HTTP.UTF_8)); HttpResponse response = httpclient.execute(post, 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); Sample Response <?xml version="1.0" encoding="utf-8"?> <emsresponse> <features> <feature> <id>1</id> </feature> </features> <id>21</id> <stat>ok</stat> </emsresponse> See Also: Output Format for Failure Error Codes Error Code 100 Invalid request parameter. 101 Not authorized to use this product. 102 Invalid data entered 107 An internal error occurred! Please report the error to System administrator.

52 46 Chapter 3: Web Service Interfaces Error Code 118 {field should be of datatype Integer. [Note: This error code is applicable for the fields - License modelid, entid, ftrid, customerid, lmid, templatetype, lineitemid, CustomerId, stationcount,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, and granularity.] 128 You should log on first. 132 The URL address does not exist. 133 Invalid namespace. 301 Unable to find product for ID Id 304 Mentioned feature ids are not correct. 309 Unable to find feature. 333 Product already in complete state and cannot be updated. 344 Product already in End Of Life state and cannot be Updated/deleted 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. Remove Features from Product Removes features from products. Comma separated featureids are provided as input. The output is the intersection of already existing features and new features to be removed. Default Protocol Method Type URI HTTPS POST disassociatefeaturesfromproduct.xml Post Parameters Parameter Valid Values Optional productid Specify the product ID. Integer (>0) No ftrids Sample Code Specify unique record IDs of features (in EMS database) to be removed. String (comma separated feature IDs) No import java.io.ioexception; import org.apache.http.params.httpparams; public class EMSSample { private static DefaultHttpClient httpclient = new DefaultHttpClient();

53 3.3. Managing Catalog Elements 47 private static Principal principal = null; public static String disassociatefeaturesfromproduct.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpPost post = new HttpPost (" List<NameValuePair> nvps = new ArrayList<NameValuePair>(); nvps.add(new BasicNameValuePair("featureIds", "")); nvps.add(new BasicNameValuePair("productId", "")); post.setentity(new UrlEncodedFormEntity(nvps, HTTP.UTF_8)); HttpResponse response = httpclient.execute(post, 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); Sample Response <?xml version="1.0" encoding="utf-8"?> <emsresponse> </features> <id>11</id> <stat>ok</stat> </emsresponse> See Also: Output Format for Failure Error Codes Error Code 100 Invalid request parameter. 101 Not authorized to use this product. 102 Invalid data entered 107 An internal error occurred! Please report the error to System administrator. 118 {field should be of datatype Integer. [Note: This error code is applicable for the fields - License modelid, entid, ftrid, customerid, lmid, templatetype, lineitemid, CustomerId, stationcount,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,

54 48 Chapter 3: Web Service Interfaces Error Code userids, featureid, productname, productversion, detailslm, lmid, templatetype, customattribute, lineitemid, customerrefid, and granularity.] 128 You should log on first. 132 The URL address does not exist. 133 Invalid namespace. 304 Mentioned feature ids are not correct. 309 Unable to find feature. 333 Product already in complete state and cannot be updated. 344 Product already in End Of Life state and cannot be Updated/deleted 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. Change Lifecycle Stage of a Product Change the lifecycle stage of a product for a given product ID. The lifecycle stage can be Draft, Complete, End of Life (EOL). Notes 1. The initial stage of a product is Draft. On first call to this Web service, the stage changes to Complete. On second call, the stage changes to End of Life. 2. Once End of Life is reached, the product stage cannot be changed. Default Protocol Method Type URI HTTPS POST changeproductlifecyclestage.xml Post Parameters Parameter Valid Values Optional productid Specify the product ID. Integer (>0) No Sample Code import java.io.ioexception;

55 3.3. Managing Catalog Elements 49 import org.apache.http.params.httpparams; public class EMSSample { private static DefaultHttpClient httpclient = new DefaultHttpClient(); private static Principal principal = null; public static String changeproductlifecyclestage.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpPost post = new HttpPost (" List<NameValuePair> nvps = new ArrayList<NameValuePair>(); nvps.add(new BasicNameValuePair("productId", "")); post.setentity(new UrlEncodedFormEntity(nvps, HTTP.UTF_8)); HttpResponse response = httpclient.execute(post, 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); Sample Response <?xml version="1.0" encoding="utf-8"?> <emsresponse> <lifecyclestage>complete</lifecyclestage> <productid>16</productid> <stat>ok</stat> </emsresponse> See Also: Output Format for Failure Error Codes Error Code 100 Invalid request parameter. 101 Not authorized to use this product. 107 An internal error occurred! Please report the error to System administrator. 118 {field should be of datatype Integer. [Note: This error code is applicable for the fields - License modelid, entid, ftrid, customerid, lmid, templatetype, lineitemid, CustomerId, stationcount,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,

56 50 Chapter 3: Web Service Interfaces Error Code timezoneid, and granularity.] 128 You should log on first. 132 The URL address does not exist. 301 Unable to find product for ID Id 1006 productname is already in End Of Life state 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. Retrieve Product Details by productid Retrieve the details of a product for a given product ID. Default Protocol Method Type URI HTTPS GET getproductbyid.xml Query Parameters Parameter Valid Values Optional productid Specify the product ID. Integer No 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 getproductbyid.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpGet get = new HttpGet(" query = new StringBuffer(); setparameter("productid", ""); 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;

57 3.3. Managing Catalog Elements 51 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 <emsresponse> <product> <creationtime> </creationtime> <deployed>true</deployed> <desc /> <features> <feature> <id>1</id> <name>f1</name> <ver /> </feature> </features> <id>1</id> <lifecyclestage>complete</lifecyclestage> <modificationtime> </modificationtime> <name>prod</name> <namespaceid>1</namespaceid> <namespacename>name</namespacename> <refid1 /> <refid2 /> <said>1</said> <ver>1</ver> </product> <stat>ok</stat> </emsresponse> See Also: Output Format for Failure Error Codes Error Code 100 Invalid request parameter. 102 Invalid data entered 107 An internal error occurred! Please report the error to System administrator. 118 {field should be of datatype Integer. [Note: This error code is applicable for the fields - License modelid, entid, ftrid, customerid, lmid, templatetype, lineitemid,

58 52 Chapter 3: Web Service Interfaces Error Code CustomerId, stationcount,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, and granularity.] 128 You should log on first. 132 The URL address does not exist. 301 Unable to find product for ID 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. Search Products Retrieve the list of products against the query parameters. Default Protocol Method Type URI HTTPS GET searchproducts.xml Query Parameters Parameter Valid Values Optional productname Specify the product name. String Yes productversion Version of the product. String Yes namespacename Specify the namespace to which the product belongs. String Yes sortcol Sort against the column. String (productname, productversion, namespacename, product, lifecyclesatge, deployed) Default Value:productName sortorder The order to sort. String (asc, desc) pagesize The number of products retrieved by one request. Default Value: desc Integer (>0) Default Value: 200 pageindex The starting page number. Integer (>0) Default Value: 1 Yes Yes Yes Yes refid1 Information that uniquely identifies the Product in a different system, for String Yes

59 3.3. Managing Catalog Elements 53 Parameter Valid Values Optional refid2 example, a Product ID in your company's ERP system. A second unique reference ID, similar to Ref ID 1. String lastmodified Creation or Modification time stamp. Long Yes Sample Code Yes 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 searchproducts.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpGet get = new HttpGet(" query = new StringBuffer(); setparameter("namespacename", "char"); setparameter("refid2", "Pref2"); setparameter("lastmodified", " "); setparameter("refid1", "Pref1"); setparameter("sortorder", "asc"); setparameter("pagesize", "1"); setparameter("sortcol", "productname"); setparameter("productversion", "v1"); setparameter("productname", "P1"); setparameter("pageindex", "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 + "&");

60 54 Chapter 3: Web Service Interfaces Sample Response <emsresponse> <products> <product> <creationtime> </creationtime> <deployed>true</deployed> <desc /> <id>1</id> <lifecyclestage>complete</lifecyclestage> <modificationtime> </modificationtime> <name>prod</name> <namespaceid>1</namespaceid> <namespacename>name</namespacename> <refid1 /> <refid2 /> <said>1</said> <ver>1</ver> </product> </products> <stat>ok</stat> <total>5</total> </emsresponse> See Also: Output Format for Failure Error Codes Error Code 100 Invalid request parameter. 102 Invalid data entered 107 An internal error occurred! Please report the error to System administrator. 109 "Invalid sortorder.valid values are 'asc' or 'desc'. 110 Invalid pageindex. Valid value can be any positive integer greater than Invalid pagesize.valid value can be any positive integer greater than {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, and granularity.] 128 You should log on first. 132 The URL address does not exist. 133 Invalid namespace. 322 This Namespace does not exists in the system The sort column is not valid. Valid values are

61 3.3. Managing Catalog Elements 55 Error Code productid,productname,productversion,lifecyclestage,deployed,namespacename,product {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. Retrieve Product Details By Name and Version Retrieve product details for the given product name and version. Default Protocol Method Type URI HTTPS GET getproductbynameandver.xml Query Parameters Parameter Valid Values Optional productname Specify the product name. String No productversion Version of the product. String No 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 getproductbynameandver.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpGet get = new HttpGet (" query = new StringBuffer(); setparameter("productversion", ""); setparameter("productname", ""); get.seturi(new URI(URLDecoder.decode(get.getURI() + query.tostring(),"utf-8"))); HttpResponse response = httpclient.execute(get, context);

62 56 Chapter 3: Web Service Interfaces 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 <emsresponse> <product> <creationtime> </creationtime> <deployed>true</deployed> <features> <feature> <id>2</id> <name>ram111</name> <ver /> </feature> </features> <id>2</id> <lifecyclestage>complete</lifecyclestage> <modificationtime> </modificationtime> <name>raa</name> <namespaceid>2</namespaceid> <namespacename>ram</namespacename> <refid1 /> <refid2 /> <said>1</said> <ver>11</ver> </product> <stat>ok</stat> </emsresponse> <emsresponse> <product> <deployed>false</deployed> <features> <feature> <id>1</id> <name>feat1</name> <ver>1</ver> </feature> </features> <id>3</id> <lifecyclestage>eol</lifecyclestage> <name>prd1</name> <namespaceid>1</namespaceid> <namespacename>nm1</namespacename>

63 3.3. Managing Catalog Elements 57 <refid1 /> <refid2 /> <said>1</said> <ver>1</ver> </product> <stat>ok</stat> </emsresponse> See Also: Output Format for Failure Error Codes Error Code 100 Invalid request parameter. 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, and granularity.] 128 You should log on first. 132 The URL address does not exist. 133 Invalid namespace Product does not exist for the given name and version 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 License Model The following table summarizes the RESTlike interfaces supported for the License Model resource. Method URI GET licensemodellist.xml Retrieve List of License Models GET getlicensemodelbyid.xml Retrieve a License Model By ID POST copylicensemodel.xml Create Copy of License Model Retrieve List of License Models Retrieves a list of license models containing their details, such as ID, name, and description. Default Protocol Method Type URI HTTPS GET licensemodellist.xml

64 58 Chapter 3: Web Service Interfaces Query Parameters None Parameter Valid Values Optional lastmodified Creation or Modification time stamp. Long Yes refid1 Information that uniquely identifies the license model in a different ERP system. String Yes refid2 A second unique reference ID, similar to Ref ID 1. String 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 licensemodellist.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpGet get = new HttpGet(" query = new StringBuffer(); setparameter("refid2", "ref2"); setparameter("lastmodified", " "); setparameter("refid1", "ref1"); 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 + "&");

65 3.3. Managing Catalog Elements 59 Sample Response <emsresponse> <licensemodels> <licensemodel> <creationtime> </creationtime> <licensemodeldescription>prepaid License Model</licensemodeldescription> <licensemodelid>5</licensemodelid> <licensemodelname>copy-pre</licensemodelname> <modificationtime> </modificationtime> <refid1>lmr1</refid1> <refid2>lmr2</refid2> </licensemodel> </licensemodels> <stat>ok</stat> <total>1</total> </emsresponse> See Also: Output Format for Failure Error Codes Error Code 100 Invalid request parameter. 101 Not authorized to use this product. 102 Invalid data entered 107 An internal error occurred! Please report the error to System administrator. 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, and granularity.] 128 You should log on first. 132 The URL address does not exist {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. Retrieve a License Model By ID Retrieves information of a license model, such as its ID, name, and description by license model ID. Default Protocol Method Type URI HTTPS GET getlicensemodelbyid.xml

66 60 Chapter 3: Web Service Interfaces Query Parameters Parameter Valid Values Optional lmid Specify the license model ID. int No 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 getlicensemodelbyid.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpGet get = new HttpGet(" query = new StringBuffer(); setparameter("lmid", "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 <emsresponse> <licensemodeldetail> <copylmid>2</copylmid> <creationtime> </creationtime> <description>postpaid License Model</description>

67 <enfid>1</enfid> <groups> <group> <licensemodelgroupname>vendor Attribute</licenseModelGroupName> <subgroups> <subgroup> <Attributes> <Attribute> <id>16</id> <name>vendor Attribute</name> <overridable>2</overridable> <value /> </Attribute> </Attributes> <licensemodelsubgroupname>vendor Attribute</licenseModelSubGroupName> </subgroup> </subgroups> </group> <group> <licensemodelgroupname>time</licensemodelgroupname> <subgroups> <subgroup> <Attributes> <Attribute> <id>1</id> <name>start_date</name> <overridable>2</overridable> <value> :00</value> </Attribute> <Attribute> <id>2</id> <name>end_date</name> <overridable>2</overridable> <value> :59</value> </Attribute> </Attributes> <licensemodelsubgroupname>license Validity</licenseModelSubGroupName> </subgroup> </subgroups> </group> <group> <licensemodelgroupname>capacity Attribute</licenseModelGroupName> <subgroups> <subgroup> <Attributes> <Attribute> <id>17</id> <name>capacity Attribute</name> <overridable>2</overridable> <value /> </Attribute> </Attributes> <licensemodelsubgroupname>capacity Attribute</licenseModelSubGroupName> </subgroup> </subgroups> 3.3. Managing Catalog Elements 61

68 62 Chapter 3: Web Service Interfaces </group> <group> <licensemodelgroupname>usage Type</licenseModelGroupName> <subgroups> <subgroup> <Attributes> <Attribute> <id>4</id> <name>usage Type</name> <overridable>2</overridable> <value>2</value> </Attribute> </Attributes> <licensemodelsubgroupname>usage Type</licenseModelSubGroupName> </subgroup> </subgroups> </group> </groups> <licensemodelname>postpaid</licensemodelname> <modificationtime> </modificationtime> <refid1 /> <refid2 /> <total>4</total> </licensemodeldetail> <stat>ok</stat> </emsresponse> See Also: Output Format for Failure Error Codes Error Code 118 {field should be of datatype Integer. [Note: This error code is applicable for the fields - License modelid, entid, ftrid, customerid, lmid, templatetype, lineitemid, CustomerId, stationcount,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, 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, and granularity.] 411 License model does not exist 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.

69 3.3. Managing Catalog Elements 63 Create Copy of License Model Creates new license model according to the updated fields. The input of this Web service is the XML string returned by getlicensemodelbyid.xml. In the input XML, you can edit values of the following fields: 1. <description> 2. <Attribute> <overridable> Note: The possible valid values of overridable are 1 (No) and 2 (Yes). If a different value is given, the value defaults to <Attribute> <value> 4. <licensemodelname> 5. <refid1> 6. <refid2> The change in the value of a tag other than those listed above will result in error. Default Protocol Method Type URI HTTPS POST copylicensemodel.xml POST Parameters Parameter detailslm The XML string returned by getlicensemodelbyid. For on-premise applications deployed with feature level licensing, if you want to add a feature containing concurrent license model, you need to create a copy of concurrent license model with default counting type as 3. It means that you need to specify the Counting Type as 3 in the input XML, for concurrent license model. Valid Values Optional String No Sample Code import java.io.ioexception; import org.apache.http.params.httpparams; public class EMSSample { private static DefaultHttpClient httpclient = new DefaultHttpClient(); private static Principal principal = null;

70 64 Chapter 3: Web Service Interfaces public static String copylicensemodel.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpPost post = new HttpPost(" List<NameValuePair> nvps = new ArrayList<NameValuePair>(); nvps.add(new BasicNameValuePair("detailsLM", "")); post.setentity(new UrlEncodedFormEntity(nvps, HTTP.UTF_8)); HttpResponse response = httpclient.execute(post, 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); Sample Response <emsresponse> <licensemodelid>14</licensemodelid> <stat>ok</stat> </emsresponse> See Also: Output Format for Failure Error Codes Error Code 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, and granularity.] 413 LicenseModel <LicenseModel name> already exists. Try again with different name XML schema Validation Failed The attribute value {value is not available in the predefined list of values. Provide a valid value only 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 Invalid capacity value.capacity value between is allowed.

71 3.3. Managing Catalog Elements Service Agreement The following table summarizes the RESTlike interfaces supported for the Service Agreement resource. Method URI GET serviceagreementlist.xml Retrieve List of Service Agreements Retrieve List of Service Agreements Retrieves a list of service agreements containing their details such as, ID, name, and description. Default Protocol Method Type URI HTTPS GET serviceagreementlist.xml Query Parameters Parameter Valid Values Optional lastmodified Creation or Modification time stamp. Long Yes refid1 refid2 Sample Code Information that uniquely identifies the service agreement in a different ERP system. Identifier 2 to store the unique record ID as used by external ERP/CRM systems. String String Yes Yes 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 serviceagreementlist.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpGet get = new HttpGet(" query = new StringBuffer(); setparameter("refid2", "ref2"); setparameter("lastmodified", " "); setparameter("refid1", "ref1"); get.seturi(new URI(URLDecoder.decode(get.getURI() + query.tostring(),"utf-8"))); HttpResponse response = httpclient.execute(get, context);

72 66 Chapter 3: Web Service Interfaces 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 <emsresponse> <serviceagreements> <serviceagreement> <creationtime> </creationtime> <description>service Agreement Template definition</description> <modificationtime> </modificationtime> <refid1>tref1</refid1> <refid2 /> <serviceagreementid>3</serviceagreementid> <serviceagreementname>test2</serviceagreementname> </serviceagreement> </serviceagreements> <stat>ok</stat> <total>1</total> </emsresponse> See Also: Output Format for Failure Error Codes Error Code 100 Invalid request parameter. 101 Not authorized to use this product. 102 Invalid data entered 107 An internal error occurred! Please report the error to System administrator. 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, and granularity.] 128 You should log on first. 132 The URL address does not exist {field should be of datatype long. [Note: This error code is applicable for the field -

73 3.3. Managing Catalog Elements 67 Error Code 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.

74 68 Chapter 3: Web Service Interfaces 3.4. Managing Entitlements This sections lists the Web services provided for managing the entitlements.creating an entitlement involves the following steps: Create entitlement - createentitlement.xml Add products to the entitlement - addentitlementitem.xml Commit entitlement - commitentitlement.xml Before you commit an entitlement, it remains in Draft stage. You can edit various parameters related to the entitlement using the following Web services (see the flow diagram for details): Edit entitlement details - updateentitlement.xml Edit line item for start date, end date, feature license model associationupdateentitlementitem.xml Include or exclude features - updatefeaturelineitemassociation Update the license model of a feature inside a line item - updatelineitemfeaturelmassociation

75 3.4. Managing Entitlements 69 Update entitlement attribute for all features - updateentitlementattributeforallfeatures.xml Edit license model attributes for the features - setentfeaturelmattributes.xml The entitlement Web services are grouped into the following categories: Entitlement Entitlement Line Item Entitlement License Model Attributes Entitlement Service Agreement Attributes Enterprise User Identities Reconfiguring Entitlements 133

76 70 Chapter 3: Web Service Interfaces Entitlement The following table summarizes the RESTlike interfaces that help create, modify, and search entitlements. Method URI POST createentitlement.xml Create Entitlement Using Parameters GET getentitlementdetailsbyid.xml Retrieve Details of an Entitlement POST addentitlementitem.xml Add Product(s) to an Entitlement POST updateentitlement.xml Update Entitlement Details POST commitentitlement.xml Commit Entitlement GET searchentitlements.xml Search Entitlements GET getentitlementcertificatehtml.xml Retrieve Entitlement Certificate as HTML POST updateentitlementattributeforallfeatures.xml Update Entitlement Attribute for All Features GET getentitlementitembycriteria.xml Retrieve Line Item Details By Criteria Create Entitlement Using Parameters Create an entitlement using the parameters provided. The output values are entid and eid. 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. Default Protocol Method Type URI HTTPS POST createentitlement.xml Post Parameters Parameter Valid Values startdate Entitlement start date. Date (yyyymm-dd) enddate Entitlement end date. To create an entitlement having no limit on end Date Optional No No

77 3.4. Managing Entitlements 71 Parameter date, use as the enddate. Valid Values (yyyymm-dd) customerid The unique record ID of the customer in EMS database. Integer No contact id address of the contact. String No isretail deploymenttype Specify whether the entitlement is of type retail or not. Valid values are True or False. Default Value: True Specify the deployment type, which can be: 1: for Cloud entitlements 2: for On-premise entitlements that are cached at entitlement level 3: for On-premise entitlements that are cached at feature level 4: for On-premise entitlements that are cached at entitlement level and used in detach mode Default Value: 1 Boolean Integer Optional userid Specify the user ID. String Mandatory, if isretail is set to True refid1 Information that uniquely identifies the entitlement in a different ERP system. String refid2 A second unique reference ID, similar to Ref ID 1. String Yes stationcount Sample Code Maximum number of on-premise machines on which an entitlement can be used (in detach mode). You need to specify this value for on-premise entitlements created with detach mode (deploymenttype=4). This value is ignored for other deployment types. You can specify a value in the range of 1 to 50. Default Value: 1 Integer No Yes Yes Yes import java.io.ioexception; import org.apache.http.params.httpparams; public class EMSSample { private static DefaultHttpClient httpclient = new DefaultHttpClient(); private static Principal principal = null;

78 72 Chapter 3: Web Service Interfaces public static String createentitlement.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpPost post = new HttpPost(" List<NameValuePair> nvps = new ArrayList<NameValuePair>(); nvps.add(new BasicNameValuePair("startDate", "")); nvps.add(new BasicNameValuePair("refId2", "")); nvps.add(new BasicNameValuePair("customerId", "")); nvps.add(new BasicNameValuePair("refId1", "")); nvps.add(new BasicNameValuePair("isRetail", "")); nvps.add(new BasicNameValuePair("userId", "")); nvps.add(new BasicNameValuePair("endDate", "")); nvps.add(new BasicNameValuePair("deploymentType", "")); nvps.add(new BasicNameValuePair("stationCount", "")); nvps.add(new BasicNameValuePair("contact Id", "")); post.setentity(new UrlEncodedFormEntity(nvps, HTTP.UTF_8)); HttpResponse response = httpclient.execute(post, 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); Sample Response <emsresponse> <eid>ff9c33e3-9b49-4e64-9bed-4db529b147b0</eid> <entid>19</entid> <stat>ok</stat> </emsresponse> See Also: Output Format for Failure Error Codes Error Code 100 Invalid request parameter. 101 Not authorized to use this product. 107 An internal error occurred! Please report the error to System administrator. 117 Regular Expression validation failed for contact id 118 {field should be of datatype Integer. [Note: This error code is applicable for the fields - License modelid, entid, ftrid, customerid, lmid, templatetype, lineitemid, CustomerId, stationcount,and granularity.]

79 3.4. Managing Entitlements 73 Error Code 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, and granularity.] 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. 132 The URL address does not exist. 519 Customer not found for the given customerid. 617 Start date cannot be greater than end date 1012 UserId can not be blank An On-Premise entitlement can not be retail 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 Valid values for deploymenttype are 1(Cloud),2(On-Premise Entitlement Level), 3 (On-Premise Feature Level), 4(On-Premise Detach Mode) Invalid value for stationcount.valid values are between Retrieve Details of an Entitlement Retrieves the list of line items, with product(s), features(s), and license model, for a given entitlement ID. The output XML contains element numberofusers only for enterprise named entitlements The valid values for status of an entitlement or a line item are: 0: Enabled 1: Disabled 2: Revoked Default Protocol Method Type URI HTTPS GET getentitlementdetailsbyid.xml Query Parameters Parameter Valid Values Optional entid Identifier of the entitlement. Note: The entid is the handle returned by the Integer (>0) No

80 74 Chapter 3: Web Service Interfaces Parameter Valid Values Optional createentitlement.xml web service. You can use the searchentitlements.xml web service to retrieve entid for an entitlement. fetchcompleteeid Specify whether to retrieve complete details of the entitlement. Sample Code Valid values are True or False. Default Value: False Boolean Yes 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 getentitlementdetailsbyid.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpGet get = new HttpGet (" query = new StringBuffer(); setparameter("fetchcompleteeid", ""); setparameter("entid", "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 + "&");

81 3.4. Managing Entitlements 75 Sample Response For C loud Deployment <emsresponse> <stat>ok</stat> <entitlement> <entid>1</entid> <eid>4e0d6b****</eid> <entitlementtype>enterprise</entitlementtype> <startdate> </startdate> <enddate> </enddate> <customer> <customerid>1</customerid> <customername>alaska</customername> <customerrefid>alaska</customerrefid> </customer> <contact> <contactid>1</contactid> <contact id>[email protected]</contact id> </contact> <state>2</state> <status>0</status> <refid1></refid1> <refid2></refid2> <deploymenttype>cloud</deploymenttype> <lineitems> <lineitem> <lineitemid>1</lineitemid> <lineitemname>postpaid</lineitemname> <status>0</status> <type>product</type> <enforcement> <enforcementid>1</enforcementid> <enforcementname>sentinel Cloud</enforcementName> <enforcementversion>3.4.0</enforcementversion> </enforcement> <itemproduct> <itemfeaturelicensemodels> <itemfeaturelicensemodel> <entftrlmid>1</entftrlmid> <feature> <id>1</id> <featurename>postpaid</featurename> <featureid>1</featureid> </feature> <licensemodel> <licensemodelid>2</licensemodelid> <licensemodelname>postpaid</licensemodelname> </licensemodel> </itemfeaturelicensemodel> </itemfeaturelicensemodels> <product> <productid>1</productid> <productname>postpaid</productname> <productversion>3.4</productversion> <refid1></refid1>

82 76 Chapter 3: Web Service Interfaces <refid2></refid2> </product> <itemserviceagreement> <entproductsaid>1</entproductsaid> <serviceagreement> <serviceagreementid>1</serviceagreementid> <serviceagreementname>service Agreement Template</serviceAgreementName> </serviceagreement> </itemserviceagreement> </itemproduct> </lineitem> </lineitems> <creationtime> </creationtime> <modificationtime> </modificationtime> <timezone>(gmt-09:00) Alaska</timezone> </entitlement> </emsresponse> For O n-pr emis e Deployment <emsresponse> <stat>ok</stat> <entitlement> <entid>6</entid> <eid>63db7b****</eid> <entitlementtype>enterprise</entitlementtype> <startdate> </startdate> <enddate> </enddate> <customer> <customerid>2</customerid> <customername>onpremise</customername> <customerrefid>onpremise</customerrefid> </customer> <contact> <contactid>2</contactid> <contact id>[email protected]</contact id> </contact> <state>2</state> <status>0</status> <refid1></refid1> <refid2></refid2> <featurecachingmode>feature Level</featureCachingMode> <deploymenttype>on-premise</deploymenttype> <lineitems> <lineitem> <lineitemid>9</lineitemid> <lineitemname>p3</lineitemname> <status>0</status> <type>product</type> <enforcement> <enforcementid>1</enforcementid> <enforcementname>sentinel Cloud</enforcementName> <enforcementversion>3.1.0</enforcementversion> </enforcement> <itemproduct> <itemfeaturelicensemodels> <itemfeaturelicensemodel> <entftrlmid>15</entftrlmid>

83 3.4. Managing Entitlements 77 <feature> <id>3</id> <featurename>f3</featurename> <featureid>3</featureid> </feature> <licensemodel> <licensemodelid>2</licensemodelid> <licensemodelname>postpaid</licensemodelname> </licensemodel> </itemfeaturelicensemodel> </itemfeaturelicensemodels> <product> <productid>3</productid> <productname>p3</productname> <productversion>3.1</productversion> <refid1></refid1> <refid2></refid2> </product> <itemserviceagreement> <entproductsaid>9</entproductsaid> <serviceagreement> <serviceagreementid>1</serviceagreementid> <serviceagreementname>service Agreement Template</serviceAgreementName> </serviceagreement> </itemserviceagreement> </itemproduct> </lineitem> </lineitems> <creationtime> </creationtime> <modificationtime> </modificationtime> <timezone>(gmt) Greenwich Mean Time, : Dublin, Edinburgh, Lisbon, London</timezone> </entitlement> </emsresponse> See Also: For on-premise entitlements, the Web services response includes an additional tag <featurecachingmode>. The value of this tag can be Feature Level, Entitlement Level, or Detach Mode. For Detach Mode, the <stationcount> tag is also displayed in response. Output Format for Failure Error Codes Error Code 100 Invalid request parameter. 101 Not authorized to use this product. 107 An internal error occurred! Please report the error to System administrator. 113 Specify a valid Boolean value for {field. Valid values are true or false. [Note: This error code is applicable for the fields - fetchcompleteeid, loginallowed, isenabled, and optional.]. 118 {field should be of datatype Integer. [Note: This error code is applicable for the fields

84 78 Chapter 3: Web Service Interfaces Error Code - License modelid, entid, ftrid, customerid, lmid, templatetype, lineitemid, CustomerId, stationcount,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, 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, and granularity.] 128 You should log on first. 132 The URL address does not exist. 308 Entitlement's lifecyclestage is not valid. 621 Entitlement does not exist. Retry with a correct ID 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. Add Product(s) to an Entitlement This interface enables you to add a product to an entitlement. Note the following points: The entitlement should be in the Draft or Reconfigure stage. The product to be added should be in the Complete stage. If the product to be added has concurrent license type, the concurrentlimit field (if set) will update the overridable concurrent limit license model attributes of all the features inside the line item. For Dr aft Entitlements : If the entitlement is of type Retail, then numberofusers has no effect. If the entitlement is of type Enterprise, note the following points: o o o o In the first line item added, if numberofusers field is left blank, then the entitlement will be marked as unnamed. If some value is assigned to numberofusers field, the entitlement will be marked as named and can have number of users as specified. For subsequent line items, the numberofusers field has no effect. The number of users added for first line item is taken as default for subsequent line items. To change the entitlement type, use the Web services Update Entitlement Line Items and Update Entitlement Details.

85 3.4. Managing Entitlements 79 For R econfigur ed Entitlements : The numberofusers field has no effect and it inherits the value from the original entitlement. For O n-pr emis e and C loud Entitlements : For on-premise entitlements with feature level caching mode either as entitlement level or feature level, add only those products that contain on-premise supported license models. o o On-premise entitlement level licensing supports the following license models: Subscription, Postpaid, Concurrent with Per Login counting type. On-premise feature level licensing supports the following license models: Subscription, Postpaid, Concurrent with Per Identity Per Station counting type. For on-premise entitlements created with deployment type=2 (entitlement level deployment without detach mode), disconnectlimit will apply to all the line items of the entitlement. For all other deployment types, its value is ignored. Default Protocol Method Type URI HTTPS POST addentitlementitem.xml Post Parameters Parameter entid Identifier of the entitlement. 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. Valid Values Optional Integer No productid Specify the identifier of the product to be added. Integer No numberofusers Number of users who can use the product, in case of retail entitlement concurrentlimit Number of concurrent instances ( in the case of concurrent license type). The value should be between Integer Integer (>0) Yes Yes disconnectlimit Period for which the license can be used in offline mode on an on-premise machine. You need to specify this value for onpremise entitlements created with deploymenttype=2 (entitlement level deployment without detach mode). This value is ignored for other deployment types. Integer Yes The unit of disconnectlimit is Hours. You can specify a value in the range of 1 to Use to specify No Limit. Default Value is 1.

86 80 Chapter 3: Web Service Interfaces Parameter refid1 Information that uniquely identifies the line item in a different ERP system. Valid Values Optional String refid2 A second unique reference ID, similar to Ref ID 1. String Yes Sample Code Yes import java.io.ioexception; import org.apache.http.params.httpparams; public class EMSSample { private static DefaultHttpClient httpclient = new DefaultHttpClient(); private static Principal principal = null; public static String addentitlementitem.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpPost post = new HttpPost(" List<NameValuePair> nvps = new ArrayList<NameValuePair>(); nvps.add(new BasicNameValuePair("refId2", "ref2")); nvps.add(new BasicNameValuePair("entId", "1")); nvps.add(new BasicNameValuePair("refId1", "ref1")); nvps.add(new BasicNameValuePair("numberOfUsers", "12")); nvps.add(new BasicNameValuePair("concurrentLimit", "20")); nvps.add(new BasicNameValuePair("disconnectLimit", "12")); nvps.add(new BasicNameValuePair("productId", "1")); post.setentity(new UrlEncodedFormEntity(nvps, HTTP.UTF_8)); HttpResponse response = httpclient.execute(post, 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); Sample Response <?xml version= 1.0 encoding= UTF-8?> <emsresponse> <id>26</id> <stat>ok</stat> </emsresponse>

87 3.4. Managing Entitlements 81 See Also: Output Format for Failure Error codes Error Code 100 Invalid request parameter. 101 Not authorized to use this product. 118 {field should be of datatype Integer. [Note: This error code is applicable for the fields - License modelid, entid, ftrid, customerid, lmid, templatetype, lineitemid, CustomerId, stationcount,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, 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, and granularity.] 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. 132 The URL address does not exist. 301 Unable to find product for ID Id 325 This product is already part of Entitlement! 328 product is not in lifeycle stage complete 621 Entitlement does not exist. Retry with a correct ID. 647 Cannot update entitlement with lifecyclestate=complete UserId can not be blank Selected License Model for feature - <featurename>, is not supported for On-Premise deployment 1074 Only Per Login counting type is allowed in concurrent license model for On-Premise (Entitlement level and Detach Mode) entitlement Only days between 1 and 1825 are accepted Invalid concurrent limit.concurrent limit between is allowed FeatureID out of range for feature <featurename>. FeatureID can range from for On-premise deployment 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.

88 82 Chapter 3: Web Service Interfaces Update Entitlement Details Update entitlement details for a given entitlement ID. Using this Web service, you can update entitlements that are in Draft stage and Reconfigured stage. This Web service is used to update stationcount in the Reconfigured stage only for an on-premise entitlement created with Detach mode. For all other types of entitlements, this Web service can be used only in draft stage. You cannot update the deployment type of an entitlement. Default Protocol Method Type URI HTTPS POST updateentitlement.xml Post Parameters Parameter Valid Values entid Entitlement ID Integer (>0) startdate Entitlement start date. Date (yyyymm-dd) enddate Entitlement end date. Date (yyyymm-dd) customerid The unique record ID of the customer in EMS database. Integer (>0) contact id Id for the given customer. String Yes isretail Whether entitlement type is of retail or not Valid values are True or False. Boolean userid Identifier of the user in case of retail entitlement. String Yes refid1 Information that uniquely identifies the entitlement in a different ERP system. String refid2 A second unique reference ID, similar to Ref ID 1. String Yes stationcount Maximum number of on-premise machines on which an entitlement can be used (in detach mode). You need to specify this value for on-premise entitlements created with detach mode (deploymenttype=4). You can specify a value in the range of 1 to 50. Integer Default Value: 1 Optional No Yes Yes Yes Yes Yes Yes

89 3.4. Managing Entitlements 83 Sample Code import java.io.ioexception; import org.apache.http.params.httpparams; public class EMSSample { private static DefaultHttpClient httpclient = new DefaultHttpClient(); private static Principal principal = null; public static String updateentitlement.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpPost post = new HttpPost(" List<NameValuePair> nvps = new ArrayList<NameValuePair>(); nvps.add(new BasicNameValuePair("startDate", "")); nvps.add(new BasicNameValuePair("refId2", "")); nvps.add(new BasicNameValuePair("customerId", "")); nvps.add(new BasicNameValuePair("entId", "")); nvps.add(new BasicNameValuePair("refId1", "")); nvps.add(new BasicNameValuePair("isRetail", "")); nvps.add(new BasicNameValuePair("userId", "")); nvps.add(new BasicNameValuePair("endDate", "")); nvps.add(new BasicNameValuePair("stationCount", "")); nvps.add(new BasicNameValuePair("contact Id", "")); post.setentity(new UrlEncodedFormEntity(nvps, HTTP.UTF_8)); HttpResponse response = httpclient.execute(post, 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); Sample Response <emsresponse> <stat>ok</stat> </emsresponse> See Also: Output Format for Failure

90 84 Chapter 3: Web Service Interfaces Error Codes Error Code 100 Invalid request parameter. 101 Not authorized to use this product. 118 {field should be of datatype Integer. [Note: This error code is applicable for the fields - License modelid, entid, ftrid, customerid, lmid, templatetype, lineitemid, CustomerId, stationcount,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, 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, and granularity.] 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. 132 The URL address does not exist. 511 Unable to find customer for customer name 513 The contact does not exist. 515 Invalid contact for this customer. 519 Customer not found for the given customerid. 615 End date and Start date cannot be null 617 Start date cannot be greater than end date 621 Entitlement does not exist. Retry with a correct ID. 647 Cannot update entitlement with lifecyclestate=complete UserId can not be blank An On-Premise entitlement can not be retail Deployment type change not allowed.please delete the entitlement and create a new one with the desired deployment type 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. Commit Entitlement Commit an entitlement. The entitlement should be in the Draft or Reconfigure stage.

91 3.4. Managing Entitlements 85 Default Protocol Method Type URI HTTPS POST commitentitlement.xml Post Parameters Parameter entid Identifier of the entitlement. 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. Valid Values Optional Integer (>0) no Sample Code import java.io.ioexception; import org.apache.http.params.httpparams; public class EMSSample { private static DefaultHttpClient httpclient = new DefaultHttpClient(); private static Principal principal = null; public static String commitentitlement.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpPost post = new HttpPost (" List<NameValuePair> nvps = new ArrayList<NameValuePair>(); nvps.add(new BasicNameValuePair("entId", "")); post.setentity(new UrlEncodedFormEntity(nvps, HTTP.UTF_8)); HttpResponse response = httpclient.execute(post, 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); Sample Response <?xml version= 1.0 encoding= UTF-8?> <emsresponse>

92 86 Chapter 3: Web Service Interfaces <stat>ok</stat> </emsresponse> See Also: Output Format for Failure Error Codes Error Code 100 Invalid request parameter. 101 Not authorized to use this product. 102 Invalid data entered 107 An internal error occurred! Please report the error to System administrator. 118 {field should be of datatype Integer. [Note: This error code is applicable for the fields - License modelid, entid, ftrid, customerid, lmid, templatetype, lineitemid, CustomerId, stationcount,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, and granularity.] 128 You should log on first. 132 The URL address does not exist. 612 Entitlement cannot be completed as it does not contain line Items. 613 Already committed. 621 Entitlement does not exist. Retry with a correct ID. 810 Error in reading xx.tpl file. Please contact administrator Entitlement not deployed on SAAS server 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. Search Entitlements Search entitlements using a combination of customer ID, Contact id, and lifecycle stage. Empty values of input fields are ignored. Default Protocol Method Type URI HTTPS GET searchentitlements.xml Query Parameters Parameter Valid Values Optional customerid The unique record ID of the Integer Yes

93 3.4. Managing Entitlements 87 Parameter Valid Values Optional customer in EMS database. contact id The contact ID for the customer. String lifecyclestate Lifecycle state of the entitlement. String [0 (all), 1 (draft), 2 (complete)] Default Value: 0 Yes Yes customername Name of the customer. String Yes customerrefid The unique reference ID of the customer. String pageindex The starting page number. Integer (>0) pagesize The number of entitlements retrieved by one request. Default Value: 1 Integer (>0) Default Value: 200 sortcol Sort against the column. String (startdate, enddate, state, totalcredit, status, contact id, customername, id) Default Value: id sortorder The order to sort. String (asc, desc) Default Value: desc Yes Yes Yes Yes Yes refid1 refid2 Information that uniquely identifies the entitlement in a different ERP system. Identifier to store the unique record ID as used by external ERP/CRM systems. deploymenttype The deployment type, which can be: 1: for Cloud entitlements 2: for On-premise entitlements (feature level and entitlement level, including detach mode) String String Integer Yes Yes Yes lastmodified Creation or Modification time stamp. Long Yes Sample Code import java.io.ioexception; import java.net.urldecoder;

94 88 Chapter 3: Web Service Interfaces 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(" query = new StringBuffer(); setparameter("customername", ""); setparameter("lastmodified", ""); setparameter("sortorder", ""); setparameter("pagesize", ""); setparameter("sortcol", ""); setparameter("eid", ""); setparameter("contact id", ""); setparameter("lifecyclestate", ""); setparameter("pageindex", ""); setparameter("refid2", ""); setparameter("customerid", "1"); setparameter("customerrefid", ""); setparameter("refid1", ""); setparameter("deploymenttype", ""); 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

95 3.4. Managing Entitlements 89 Sample Response <emsresponse> <stat>ok</stat> <entitlements> <entitlement> <entid>1</entid> <eid>4e0d6b****</eid> <entitlementtype>enterprise</entitlementtype> <startdate> </startdate> <enddate> </enddate> <customer> <customerid>1</customerid> <customername>alaska</customername> <customerrefid>alaska</customerrefid> </customer> <contact> <contactid>1</contactid> </contact> <state>2</state> <status>0</status> <refid1></refid1> <refid2></refid2> <deploymenttype>cloud</deploymenttype> <creationtime> </creationtime> <modificationtime> </modificationtime> <timezone>(gmt-09:00) Alaska</timezone> </entitlement> </entitlements> <total>1</total> </emsresponse> For on-premise entitlements, the Web services response includes an additional tag <featurecachingmode>. The value of this tag can be Feature Level, Entitlement Level, or Detach Mode. For Detach Mode, the <stationcount> tag is also displayed in response. Error Codes Error Code 100 Invalid request parameter. 101 Not authorized to use this product. 109 "Invalid sortorder.valid values are 'asc' or 'desc'. 110 Invalid pageindex. Valid value can be any positive integer greater than Invalid pagesize.valid value can be any positive integer greater than {field should be of datatype Integer. [Note: This error code is applicable for the fields - License modelid, entid, ftrid, customerid, lmid, templatetype, lineitemid, CustomerId, stationcount,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, and granularity.] 124 Invalid sortcolumn. Valid values are

96 90 Chapter 3: Web Service Interfaces Error Code startdate,enddate,state,totalcredit,status,contact id, 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) Valid values for deploymenttype are 1(Cloud) and 2(On-Premise) {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. Retrieve Entitlement Certificate as HTML View entitlement certificate in HTML format for a given entitlement ID.The entitlement should be in the Complete stage. Default Protocol Method Type URI HTTPS GET getentitlementcertificatehtml.xml Query Parameters Parameter entid Identifier of the entitlement. 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. Valid Values Optional Integer (>0) No 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;

97 3.4. Managing Entitlements 91 public static String getentitlementcertificatehtml.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpGet get = new HttpGet (" query = new StringBuffer(); setparameter("entid", ""); 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 <?xml version="1.0" encoding="utf-8" standalone="yes"?><emsresponse><stat>ok</stat><entcert><style>.gridtable {BORDER-RIGHT: #d4d0c8 2px solid; BORDER-TOP: #d4d0c8 2px solid; FONT-SIZE: 10pt; BORDER-LEFT: #d4d0c8 2px solid; WIDTH: 100%; BORDER-BOTTOM: #d4d0c8 2px solid; FONT-FAMILY: Arial; BORDER-COLLAPSE: collapse.nohover1 tr:hover, tr.nohover:hover, tr.nohover { background:#fff.entconttable1 { border-top:0px solid #cdcccc; border-left:1px solid #cdcccc; border-right:1px solid #cdcccc; margin-bottom:0px; color:#555;.ent-conttable1 th,.ent-conttable1 td { textalign:left; padding:6px 12px; border-bottom:1px solid #cdcccc;.ent-conttable1 table { line-height:18px; margin-bottom:0.ent-conttable1 td.rtaln { text-align:right.enthometable1 { width:100%; border:0; color:#555;.ent-hometable1 th,.ent-hometable1 td { text-align:left; padding:7px 14px; border-bottom:1px solid #e8edf3;.ent-hometable1 th { background:#e1d7e0; color:#555;.ent-hometable1.status { margin:0 5px -2px 0.enthomeTable1 label { font-weight:bold; text-align:right.ent-hometable1.selectedrow {background:#824882;color:#ffffff;.ent-menu_head {display:block;position:relative;.ent-contacrtop { background-color:#6f396e; border-bottom:1px solid #C0C0C0; margin-top:10px;.ent-contacrtopinr { background-color:#6f396e; display:block; padding:10px 15px 0px 15px ; height:23px; border-top:1px solid #ccc; border-left:1px solid #ccc;borderright:1px solid #ccc;.ent-subcontacrtopinr { background-color:#e1d7e0; display:block; padding:10px 15px 0px 15px ; height:23px; border-top:1px solid #ccc; border-left:1px solid #ccc;border-right:1px solid #ccc;.ent-contacrtopinr label {backgroundcolor:#6f396e; padding-left:15px; font-weight:bold ;.ent-contacrtopinr label.nobg { background:none; padding-left:0.ent-contsubtitle { font-size:15px; font-weight:bold; display:inline-block;color:#fff;.ent-conttitle { font-size:15px; font-weight:bold; display:inline-block;color:#555; </STYLE> <div class="entcontacrtop ent-menu_head"> <div class="ent-subcontacrtopinr"> <label id="labelentitlementdetails" class="ent-conttitle">entitlement

98 92 Chapter 3: Web Service Interfaces Details</label> </div> </div> <div class="entconttable1" > <table width="100%" cellspacing="0" cellpadding="0" class="ent-hometable1 nohover1 "> <TBODY> <tr> <td style="width:20%;padding-right:4px;" align="right"><b>eid:</b></td> <td style="width:30%"><span id="eid">4889a58b b-ba97-067ef911453e</span></td> <td style="width:25%;padding-right:4px;" align="right"><b>entitlement Type:</b></td> <td style="width:25%"><span id="entitlementtype">enterprise </span> </tr> <tr> <td style="padding-right:4px;" align="right"><b>start Date:</b></td> <td><span id="startdate">01/17/2012</span></td> <td style="paddingright:4px;" align="right"><b>end Date:</b></td> <td ><span id="enddate">never Expires</span></td> </tr> <tr> <td style="padding-right:4px;" align="right"><b>refid 1:</b></td> <td><div style="word-wrap:break-word;width:12em;"><span id="refid1"></span></div></td> <td style="paddingright:4px;" align="right"><b>refid 2:</b></td> <td><div style="word-wrap:break-word;width:12em;"><span id="refid2"></span></div></td> </tr> <tr> <td style="padding-right:4px;" align="right"><b>contact </b></td> <td><span <td style="padding-right:4px;" align="right"><b>customer Name:</b></td> <td ><span id="customername">rose</span></td> </tr> <tr> <td style="padding-right:4px;" align="right"><b>customer Time Zone:</b></td> <td colspan="3"><span id="customertz">(gmt+00:00) Greenwich Mean Time: Dublin, Edinburgh, Lisbon, London</span></td> </tr> </TBODY> </table> </div> <div class="ent-contacrtop ent-menu_ head"> <div class="ent-subcontacrtopinr"> <label id="labelentitlementdetails" class="ent-conttitle">list of Products</label> </div> </div> <div class="entconttable1" style="padding-top:5px;" > <table width="100%" cellspacing="0" cellpadding="0" class="ent-hometable1 nohover1 "> <thead> <tr style="background-color:#f5f5f5"> <th width="5%" align="center"><b>s.no.</b></th> <th width="45%" align="center"><b>product</b></th> <th width="25%" align="center"><b>status</b></th> <th width="25%" align="center"><b>type</b></th> </tr> <tr> <td align="center">1</td> <td align="center">p1 1</td> <td align="center">enabled</td> <td align="center">unnamed</td> </tr> </thead> </table> </div></entcert></emsresponse> See Also: For on-premise entitlements, the Web services response includes an additional tag <featurecachingmode>. The value of this tag can be Feature Level, Entitlement Level, or Detach Mode. For Detach Mode, the <stationcount> tag is also displayed in response. Output Format for Failure

99 3.4. Managing Entitlements 93 Us ing the Sample R es pons e to R etr iev e C er tificate Here are the steps to use the above response of the getentitlementcertificatehtml Web service for viewing the HTML certificate: 1. Save the response as an XML file. 2. Copy the information starting from the <STYLE> tag till the </div> tag. 3. Save it as an HTML file. 4. Open the HTML file in a browser to view the certificate. Error Codes Error Code 100 Invalid request parameter. 101 Not authorized to use this product. 107 An internal error occurred! Please report the error to System administrator. 118 {field should be of datatype Integer. [Note: This error code is applicable for the fields - License modelid, entid, ftrid, customerid, lmid, templatetype, lineitemid, CustomerId, stationcount,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, 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, and granularity.] 128 You should log on first. 132 The URL address does not exist. 621 Entitlement does not exist. Retry with a correct ID. 701 Invalid operation: cannot obtain Entitlement Certificate for an entitlement(id- 317 ) which is Not complete 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. Update Entitlement Attribute for All Features Change attribute value for given/all features for an entitlement.the entitlement should be in the Draft stage. Default Protocol Method Type URI HTTPS POST updateentitlementattributeforallfeatures.xml

100 94 Chapter 3: Web Service Interfaces Post Parameters Parameter Valid Values Optional entid Identifier of the entitlement. Integer No 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. attrid Specify the attribute ID. Integer No attrvalue Specify the value of the attribute. String No ftrids Capacity Attribute Specify the unique record ID of a feature (as stored in EMS database), the attribute corresponding to which is to be updated. Specify the feature's capacity. This parameter is applicable only for postpaid license models. String (comma separated feature IDs) Integer The attrid parameter is same as the <attributeid> element returned by the getentfeaturelmattributes Web service. Sample Code Range is Yes Yes import java.io.ioexception; import org.apache.http.params.httpparams; public class EMSSample { private static DefaultHttpClient httpclient = new DefaultHttpClient(); private static Principal principal = null; public static String updateentitlementattributeforallfeatures.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpPost post = new HttpPost (" List<NameValuePair> nvps = new ArrayList<NameValuePair>(); nvps.add(new BasicNameValuePair("attrId", "")); nvps.add(new BasicNameValuePair("entId", "")); nvps.add(new BasicNameValuePair("ftrIds", "")); nvps.add(new BasicNameValuePair("attrValue", "")); post.setentity(new UrlEncodedFormEntity(nvps, HTTP.UTF_8)); HttpResponse response = httpclient.execute(post, context); HttpEntity entity = response.getentity(); byte[] b = null;

101 3.4. Managing Entitlements 95 if (entity!= null) { long l = entity.getcontentlength(); b = new byte[(int) l]; entity.getcontent().read(b); entity.consumecontent(); return new String(b); Sample Response <?xml version="1.0" encoding="utf-8"?> <emsresponse> <stat>ok</stat> </emsresponse> See Also: Output Format for Failure Error Codes Error Code 100 Invalid request parameter. 101 Not authorized to use this product. 118 {field should be of datatype Integer. [Note: This error code is applicable for the fields - License modelid, entid, ftrid, customerid, lmid, templatetype, lineitemid, CustomerId, stationcount,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, and granularity.] 128 You should log on first. 132 The URL address does not exist. 695 Mentioned feature ids are not present in the Entitlement with id 696 Entitlement with id entid does not exists. 697 No Attribute exists for given attribute Id. 801 Feature Ids should have a numeric value Invalid attribute value The given attributeid attribute is not updatable Only Per Login counting type is allowed in concurrent license model for On-Premise (Entitlement level and Detach Mode) entitlement 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.

102 96 Chapter 3: Web Service Interfaces Error Code 1100 Invalid max usage limit. Max usage limit between is allowed Only Per Identity Per Station counting type is allowed in concurrent license model for On-Premise Feature level entitlement Invalid capacity value.capacity value between is allowed Entitlement Line Item The following table summarizes the RESTlike interfaces that help create, modify, and remove entitlement line items. Method URI GET getentitlementitembyid.xml Retrieve Entitlement Line Item Details POST updateentitlementitem.xml Update Entitlement Line Items POST removeentitlementitem.xml Remove Entitlement Line Item GET getentitlementitembycriteria.xml Retrieve Line Item Details By Criteria GET retrievefeaturelineitemassociation.xml Retrieve Entitlement Line Item Feature Association POST updatefeaturelineitemassociation Update Line Item Feature Association GET retrievelineitemfeaturelmassociation Retrieve Entitlement Line Item Feature License Model Association POST updatelineitemfeaturelmassociation Update Line Item Feature License Model Association Retrieve Entitlement Line Item Details Retrieve entitlement line item details by lineitemid. Default Protocol Method Type URI HTTPS GET getentitlementitembyid.xml Query Parameters Parameter Valid Values Optional lineitemid Specify the line item ID. Integer No Sample Code import java.io.ioexception; import java.net.urldecoder; import org.apache.http.params.httpparams; public class EMSSample {

103 3.4. Managing Entitlements 97 private static DefaultHttpClient httpclient = new DefaultHttpClient(); private static Principal principal = null; private static StringBuffer query; public static String getentitlementitembyid.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpGet get = new HttpGet (" query = new StringBuffer(); setparameter("lineitemid", ""); 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 Cloud Deployment <emsresponse> <stat>ok</stat> <lineitem> <lineitemid>1</lineitemid> <lineitemname>postpaid</lineitemname> <status>0</status> <type>service</type> <enforcement> <enforcementid>1</enforcementid> <enforcementname>sentinel Cloud</enforcementName> <enforcementversion>3.4.0</enforcementversion> </enforcement> <entitlement> <entid>1</entid> <eid>4e0d6b****</eid> <timezone>(gmt-09:00) Alaska</timezone> </entitlement> <itemproduct>

104 98 Chapter 3: Web Service Interfaces <itemfeaturelicensemodels> <itemfeaturelicensemodel> <entftrlmid>1</entftrlmid> <feature> <id>1</id> <featurename>postpaid</featurename> <featureid>1</featureid> </feature> <licensemodel> <licensemodelid>2</licensemodelid> <licensemodelname>postpaid</licensemodelname> </licensemodel> </itemfeaturelicensemodel> </itemfeaturelicensemodels> <product> <productid>1</productid> <productname>postpaid</productname> <productversion>3.4</productversion> <refid1></refid1> <refid2></refid2> </product> <itemserviceagreement> <entproductsaid>1</entproductsaid> <serviceagreement> <serviceagreementid>1</serviceagreementid> <serviceagreementname>service Agreement Template</serviceAgreementName> </serviceagreement> </itemserviceagreement> </itemproduct> <refid1></refid1> <refid2></refid2> <creationtime> </creationtime> <modificationtime> </modificationtime> </lineitem> </emsresponse> For On-premise Deployment <emsresponse> <stat>ok</stat> <lineitem> <lineitemid>2</lineitemid> <lineitemname>p</lineitemname> <status>0</status> <type>service</type> <enforcement> <enforcementid>1</enforcementid> <enforcementname>sentinel Cloud</enforcementname> <enforcementversion>3.4.0</enforcementversion> </enforcement> <entitlement> <entid>2</entid> <eid>3a31a4****</eid> </entitlement> <itemproduct> <itemfeaturelicensemodels> <itemfeaturelicensemodel>

105 3.4. Managing Entitlements 99 <entftrlmid>3</entftrlmid> <feature> <id>2</id> <featurename>feature2</featurename> <featureid>2</featureid> </feature> <licensemodel> <licensemodelid>3</licensemodelid> <licensemodelname>concurrent</licensemodelname> </licensemodel> </itemfeaturelicensemodel> <itemfeaturelicensemodel> <entftrlmid>4</entftrlmid> <feature> <id>1</id> <featurename>feature1</featurename> <featureid>1</featureid> </feature> <licensemodel> <licensemodelid>3</licensemodelid> <licensemodelname>concurrent</licensemodelname> </licensemodel> </itemfeaturelicensemodel> </itemfeaturelicensemodels> <product> <productid>1</productid> <productname>p</productname> <productversion>1</productversion> <refid1 /> <refid2 /> </product> <itemserviceagreement> <entproductsaid>2</entproductsaid> <serviceagreement> <serviceagreementid>1</serviceagreementid> <serviceagreementname>service Agreement Template</serviceagreementname> </serviceagreement> </itemserviceagreement> </itemproduct> <disconnectlimit>1825</disconnectlimit> <refid1>ref1</refid1> <refid2>ref2</refid2> <creationtime> </creationtime> <modificationtime> </modificationtime> </lineitem> </emsresponse> See Also: Output Format for Failure Error Codes Error Code 100 Invalid request parameter. 101 Not authorized to use this product. 102 Invalid data entered

106 100 Chapter 3: Web Service Interfaces Error Code 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, and granularity.] 128 You should log on first. 132 The URL address does not exist. 618 Could not find the entitlement line item 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. Update Entitlement Line Items This interface enables you to update line items of an entitlement. The entitlement should be in the Draft or Reconfigured stage. Note the following points: For Draft entitlements, the numberofusers field has the following effect: o o If the entitlement is of type retail, then the numberofusers field has no effect. If the entitlement is of type enterprise named, then thenumberofusers gets updated for all the line items. To convert a named enterprise entitlement to an unnamed enterprise entitlement, set numberofusers as -1. This updates all the line items as unnamed. For Reconfigured entitlements, the numberofusers field has the following effect: o o o If the entitlement is of type retail, then numberofusers has no effect. If the entitlement is of type enterprise unnamed, numberofusers has no effect. If the entitlement is of type enterprise named, then number of users can be increased or decreased. However, it cannot be decreased below the number of users already added using the Web service Add Enterprise User IDs. The ConcurrentLimit field updates the concurrent limit value of the specified line item. Only overridable attribute is updated of the license model associated with the features inside the line item. For on-premise entitlements created with deployment type=2 (entitlement level deployment

107 3.4. Managing Entitlements 101 without detach mode), disconnectlimit will apply to all the line items of the entitlement. For all other deployment types, its value is ignored. Default Protocol Method Type URI HTTPS POST updateentitlementitem.xml Post Parameters Parameter Valid Values Optional lineitemid Identifier of the line item to be updated. This is not the product ID. Integer (>0) No concurrentlimit Number of concurrent instances ( in case of concurrent license type). The value should be between Integer (>0) Yes numberofusers Number of users (in case of named contract). Integer (> 0 for named contract, - 1 for unnamed contract) disconnectlimit Period for which the license can be used in offline mode on an on-premise machine. You need to specify this value for on-premise entitlements created with deploymenttype=2 (entitlement level deployment without detach mode). This value is ignored for other deployment types. Integer Default Value: 1 Yes Yes refid1 The unit of disconnectlimit is Hours. You can specify a value in the range of 1 to Use to specify No Limit. Information that uniquely identifies the entitlement in a different ERP system. String refid2 A second unique reference ID, similar to Ref ID 1. String Yes Sample Code Yes import java.io.ioexception; import org.apache.http.params.httpparams; public class EMSSample { private static DefaultHttpClient httpclient = new DefaultHttpClient(); private static Principal principal = null;

108 102 Chapter 3: Web Service Interfaces public static String updateentitlementitem.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpPost post = new HttpPost(" List<NameValuePair> nvps = new ArrayList<NameValuePair>(); nvps.add(new BasicNameValuePair("refId2", "newref2")); nvps.add(new BasicNameValuePair("refId1", "newref1")); nvps.add(new BasicNameValuePair("numberOfUsers", "12")); nvps.add(new BasicNameValuePair("lineItemId", "1")); nvps.add(new BasicNameValuePair("concurrentLimit", "25")); nvps.add(new BasicNameValuePair("disconnectLimit", "24")); post.setentity(new UrlEncodedFormEntity(nvps, HTTP.UTF_8)); HttpResponse response = httpclient.execute(post, 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); Sample Response <?xml version="1.0" encoding="utf-8"?> <emsresponse> <stat>ok</stat> </emsresponse> See Also: Output Format for Failure Error Codes Error Code 100 Invalid request parameter. 101 Not authorized to use this product. 118 {field should be of datatype Integer. [Note: This error code is applicable for the fields - License modelid, entid, ftrid, customerid, lmid, templatetype, lineitemid, CustomerId, stationcount,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, and granularity.] 128 You should log on first.

109 3.4. Managing Entitlements 103 Error Code 132 The URL address does not exist. 618 Could not find the entitlement line item. 661 The entitlement item cannot be updated because the entitlement is in the complete stage Invalid value for numberofusers. Valid values are -1(for unnamed contract), greater than 0 for Named contract { Number User(s) already added Only days between 1 and 1825 are accepted Invalid concurrent limit.concurrent limit between is allowed 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. Remove Entitlement Line Item Remove line items from an entitlement. The entitlement should be in the Draft lifecycle stage. Default Protocol Method Type URI HTTPS POST /removeentitlementitem.xml Post Parameters Parameter Valid Values Optional lineitemid Specify the line item to delete. Integer No Sample Code import java.io.ioexception; import org.apache.http.params.httpparams; public class EMSSample { private static DefaultHttpClient httpclient = new DefaultHttpClient(); private static Principal principal = null; public static String removeentitlementitem.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpPost post = new HttpPost (" List<NameValuePair> nvps = new ArrayList<NameValuePair>();

110 104 Chapter 3: Web Service Interfaces nvps.add(new BasicNameValuePair("lineItemId", "")); post.setentity(new UrlEncodedFormEntity(nvps, HTTP.UTF_8)); HttpResponse response = httpclient.execute(post, 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); Sample Response <?xml version="1.0" encoding="utf-8"?> <emsresponse> <stat>ok</stat> </emsresponse> See Also: Output Format for Failure Error Codes Error Code 100 Invalid request parameter. 101 Not authorized to use this product. 107 An internal error occurred! Please report the error to System administrator. 118 {field should be of datatype Integer. [Note: This error code is applicable for the fields - License modelid, entid, ftrid, customerid, lmid, templatetype, lineitemid, CustomerId, stationcount,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, and granularity.] 128 You should log on first. 132 The URL address does not exist. 327 Can be deleted only if it is in draft state. 618 Could not find the entitlement line item 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.

111 3.4. Managing Entitlements 105 Retrieve Line Item Details By Criteria Retrieves line Item details based on the specified criteria. Default Protocol Method Type URI HTTPS GET getentitlementitembycriteria.xml Query Parameters Parameter refid1 Information that uniquely identifies the line item in a different ERP system. Valid Values String refid2 A second unique reference ID, similar to Ref ID 1. String Yes lastmodified Creation or modification timestamp of the line item. Long Yes Sample Code Optional Yes 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 getentitlementitembycriteria.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpGet get = new HttpGet(" query = new StringBuffer(); setparameter("refid2", "ref2"); setparameter("lastmodified", " "); setparameter("refid1", "ref1"); 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);

112 106 Chapter 3: Web Service Interfaces static void setparameter(string key, String value) { if (query.tostring().equals("")) { query.append("?" + key + "=" + value + "&"); else { query.append(key + "=" + value + "&"); Sample Response <emsresponse> <stat>ok</stat> <lineitems> <lineitem> <lineitemid>8</lineitemid> <lineitemname>prepaid</lineitemname> <status>0</status> <type>service</type> <enforcement> <enforcementid>1</enforcementid> <enforcementname>sentinel Cloud</enforcementName> <enforcementversion>3.4.0</enforcementversion> </enforcement> <entitlement> <entid>8</entid> <eid>48d1c2****</eid> <timezone>(gmt) Coordinated Universal Time</timezone> </entitlement> <itemproduct> <itemfeaturelicensemodels> <itemfeaturelicensemodel> <entftrlmid>11</entftrlmid> <feature> <id>3</id> <featurename>prepaid</featurename> <featureid>3</featureid> </feature> <licensemodel> <licensemodelid>2</licensemodelid> <licensemodelname>postpaid</licensemodelname> </licensemodel> </itemfeaturelicensemodel> </itemfeaturelicensemodels> <product> <productid>2</productid> <productname>prepaid</productname> <productversion>3.4</productversion> <refid1></refid1> <refid2></refid2> </product> <itemserviceagreement> <entproductsaid>8</entproductsaid> <serviceagreement> <serviceagreementid>1</serviceagreementid> <serviceagreementname>service Agreement Template</serviceAgreementName> </serviceagreement>

113 3.4. Managing Entitlements 107 </itemserviceagreement> </itemproduct> <disconnectlimit>43800</disconnectlimit> <refid1></refid1> <refid2></refid2> <creationtime> </creationtime> <modificationtime> </modificationtime> </lineitem> </lineitems> <total>1</total> </emsresponse> See Also: Output Format for Failure Error Codes Error Code 100 Invalid request parameter. 101 Not authorized to use this product. 102 Invalid data entered 107 An internal error occurred! Please report the error to System administrator. 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, and granularity.] 128 You should log on first {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. Retrieve Entitlement Line Item Feature Association Retrieves a list of features that are associated with a line item and are either included or excluded. For user information, the line item product name, ID, and version are also returned. The values of the <On> tag in the XML response indicate the following: 1 =Feature is included in the line item 0= Feature is excluded from the line item Default Protocol Method Type URI HTTPS GET retrievefeaturelineitemassociation.xml

114 108 Chapter 3: Web Service Interfaces GET Parameters Parameter Valid Values Optional lineitemid Line item ID Integer No 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 retrievefeaturelineitemassociation.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpGet get = new HttpGet (" query = new StringBuffer(); setparameter("lineitemid", "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 <emsresponse> <stat>ok</stat> <lineitem>

115 3.4. Managing Entitlements 109 <lineitemid>1</lineitemid> <itemproduct> <itemfeaturelicensemodels> <itemfeaturelicensemodel> <feature> <id>5</id> <featurename>f4</featurename> <On>0</On> </feature> </itemfeaturelicensemodel> <itemfeaturelicensemodel> <feature> <id>2</id> <featurename>f2</featurename> <On>0</On> </feature> </itemfeaturelicensemodel> <itemfeaturelicensemodel> <feature> <id>1</id> <featurename>f1</featurename> <On>1</On> </feature> </itemfeaturelicensemodel> <itemfeaturelicensemodel> <feature> <id>3</id> <featurename>f3</featurename> <On>0</On> </feature> </itemfeaturelicensemodel> </itemfeaturelicensemodels> <product> <productid>2</productid> <productname>p1</productname> <productversion>2.2</productversion> </product> </itemproduct> </lineitem> </emsresponse> See Also: Output Format for Failure Error Codes Error Code 100 Invalid request parameter. 101 Not authorized to use this product. 102 Invalid data entered 107 An internal error occurred! Please report the error to System administrator. 118 {field should be of datatype Integer. [Note: This error code is applicable for the fields - License modelid, entid, ftrid, customerid, lmid, templatetype, lineitemid, CustomerId, stationcount,and granularity.]

116 110 Chapter 3: Web Service Interfaces Error Code 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, and granularity.] 128 You should log on first. 682 The line item does not exist 1081 Invalid Web service version provided 1084 No Web service version provided 1116 Only "Per Identity Per Station" counting type in Concurrent license type is allowed for the Feature Level caching mode of on-premise entitlements.please change the license model associated with this feature. Update Line Item Feature Association Updates the inclusion and exclusion of features associated with the given line item. The input of this Web service is the output of retrievefeaturelineitemassociation.xml. The input XML is edited to include or exclude the features. In the input XML, you can update the <On> tag of features. The valid values are: 1 =Feature is included 0= Feature is excluded If you try to include/exclude a feature that is already included/excluded, you will not get any error. In the case of an on-premise entitlement, when you include a feature that does not have an on-premise supported license model, the default license model is automatically changed to the supported one. You receive the response code 9001 as a notification of this change. Default Protocol Method Type URI HTTPS POST updatefeaturelineitemassociation.xml POST Parameters Parameter featuredetails Features you want to include or exclude. It is the updated XML string of the Web service retrievefeaturelineitemassociation.xml. Valid Values Optional String No

117 3.4. Managing Entitlements 111 Sample Code import java.io.ioexception; import org.apache.http.params.httpparams; public class EMSSample { private static DefaultHttpClient httpclient = new DefaultHttpClient(); private static Principal principal = null; public static String updatefeaturelineitemassociation.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpPost post = new HttpPost (" List<NameValuePair> nvps = new ArrayList<NameValuePair>(); nvps.add(new BasicNameValuePair("featureDetails", "")); post.setentity(new UrlEncodedFormEntity(nvps, HTTP.UTF_8)); HttpResponse response = httpclient.execute(post, 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); Sample Response <emsresponse> <stat>ok</stat> </emsresponse> The following is the example of response code 9001: <emsresponse> <code>9001</code> <desc>default license model selected modified for following features : [2, 3] for On-Premise deployment.</desc> <stat>ok</stat> </emsresponse> See Also: Output Format for Failure

118 112 Chapter 3: Web Service Interfaces Error Codes Error Code 100 Invalid request parameter. 101 Not authorized to use this product. 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, and granularity.] 128 You should log on first. 618 Could not find the entitlement line item. 647 Cannot update entitlement with lifecyclestate=complete XML schema Validation Failed FeatureID out of range for feature <featurename>. FeatureID can range from for Onpremise deployment Invalid Web service version provided 1084 No Web service version provided 1090 The product does not have feature {feature Id Invalid value {value given for On.Valid values are 0(off) and 1(on) Allow at least one feature No License Model exist for the featureid {0, which is supported for on-premise. Retrieve Entitlement Line Item Feature License Model Association Retrieves a list of license models for features which are associated with a line item and are in On state. For user information, the line item product name, ID, and version are also returned. In the XML returned by the retrievelineitemfeaturelmassociation Web service, the values of the <Selected> tag indicate the following: 1 = License model is selected 0= License model is not selected, although the given feature contains this license model Default Protocol Method Type URI HTTPS GET retrievelineitemfeaturelmassociation.xml GET Parameter Parameter Valid Values Optional lineitemid Line Item ID Integer No

119 3.4. Managing Entitlements 113 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 retrievelineitemfeaturelmassociation.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpGet get = new HttpGet (" query = new StringBuffer(); setparameter("lineitemid", "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 <emsresponse> <stat>ok</stat> <lineitem> <lineitemid>1</lineitemid> <itemproduct> <product> <productid>2</productid> <productname>p1</productname> <productversion>2.2</productversion> </product>

120 114 Chapter 3: Web Service Interfaces </itemproduct> </lineitem> <features> <feature> <id>1</id> <featurename>f1</featurename> <licensemodels> <licensemodel> <licensemodelid>2</licensemodelid> <licensemodelname>postpaid</licensemodelname> <licensemodel>postpaid License Model</licenseModel> <enfversion>2.2.0</enfversion> <enfname>2.2.0</enfname> <selected>0</selected> </licensemodel> <licensemodel> <licensemodelid>3</licensemodelid> <licensemodelname>concurrent</licensemodelname> <licensemodel>subscription with Controlled Concurrency</licenseModel> <enfversion>2.2.0</enfversion> <enfname>2.2.0</enfname> <selected>0</selected> </licensemodel> <licensemodel> <licensemodelid>4</licensemodelid> <licensemodelname>prepaid</licensemodelname> <licensemodel>prepaid License Model</licenseModel> <enfversion>2.2.0</enfversion> <enfname>2.2.0</enfname> <selected>1</selected> </licensemodel> <licensemodel> <licensemodelid>1</licensemodelid> <licensemodelname>subscription</licensemodelname> <licensemodel>subscription License Model</licenseModel> <enfversion>2.2.0</enfversion> <enfname>2.2.0</enfname> <selected>0</selected> </licensemodel> </licensemodels> </feature> </features> </emsresponse> See Also: Output Format for Failure Error Codes Error Code 100 Invalid request parameter. 101 Not authorized to use this product.

121 3.4. Managing Entitlements 115 Error Code 102 Invalid data entered 107 An internal error occurred! Please report the error to System administrator. 118 {field should be of datatype Integer. [Note: This error code is applicable for the fields - License modelid, entid, ftrid, customerid, lmid, templatetype, lineitemid, CustomerId, stationcount,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, and granularity.] 128 You should log on first. 682 The line item does not exist 1081 Invalid Web service version provided 1084 No Web service version provided Update Line Item Feature License Model Association Updates the license model of a feature inside a line item. For an entitlement in reconfigured stage, the license model of an already deployed feature will not be updated. The input of this Web service is the output of the retrievelineitemfeaturelmassociation.xml Web service. The input XML is edited to change the selected license model for a feature. In the input XML, you can update the <Selected> tag of features and set its value to one of the following: 1 =License model is selected. 0= License model is not selected (although the given feature contains this license model) Default Protocol Method Type URI HTTPS POST updatelineitemfeaturelmassociation.xml Post Parameters Parameter featurelmdetails Updated XML string of retrievelineitemfeaturelmassociation.xml Sample Code Valid Values String Optional No import java.io.ioexception; import org.apache.http.params.httpparams; public class EMSSample {

122 116 Chapter 3: Web Service Interfaces private static DefaultHttpClient httpclient = new DefaultHttpClient(); private static Principal principal = null; public static String updatelineitemfeaturelmassociation.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpPost post = new HttpPost (" List<NameValuePair> nvps = new ArrayList<NameValuePair>(); nvps.add(new BasicNameValuePair("featureLMDetails", "")); post.setentity(new UrlEncodedFormEntity(nvps, HTTP.UTF_8)); HttpResponse response = httpclient.execute(post, 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); Sample Response <emsresponse> <stat>ok</stat> </emsresponse> See Also: Output Format for Failure Error Codes Error Code 100 Invalid request parameter. 101 Not authorized to use this product. 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, and granularity.] 128 You should log on first.

123 3.4. Managing Entitlements 117 Error Code 618 Could not find the entitlement line item. 647 Cannot update entitlement with lifecyclestate=complete XML schema Validation Failed Selected License Model for feature - <featurename>, is not supported for On-Premise deployment 1074 Only Per Login counting type is allowed in concurrent license model for On-Premise (Entitlement level and Detach Mode) entitlement Invalid Web service version provided 1084 No Web service version provided 1093 nvalid value {0 for selected. Valid values are 0 and Only one license model can be set for a feature License Model of an already deployed feature {Name cannot be changed Unable to find feature with Id{ID 1099 Unable to find License Model with Id {ID Only Per Identity Per Station counting type is allowed in concurrent license model for On- Premise Feature level entitlement Entitlement License Model Attributes The following table summarizes the RESTlike interfaces that help modify and search entitlement license model attributes. Method URI GET getentfeaturelmattributes.xml Retrieve License Model Attributes for a Feature POST setentfeaturelmattributes.xml Update License Model Attributes for a Line Item Retrieve License Model Attributes for a Feature Retrieve license model attributes and values for a feature in a line item product. The start date and end date attributes are retrieved in YYYY-MM-DD Hours:Minutes format. Default Protocol Method Type URI HTTPS GET getentfeaturelmattributes.xml

124 118 Chapter 3: Web Service Interfaces Query Parameters Parameter Valid Values Optional lineitemid Specify the line item ID. Integer No productid Specify the product ID. Integer No ftrid Specify the auto-generated, unique record ID of the feature in EMS database. Note: The ftrid is the handle returned by the addfeature.xml web service. You can retrieve ftrid by using the featurelist.xml web service. Integer The possible values for the Usage Type license attribute are: 1 (Count Based) and 2 (Time Based). For on-premise feature level licensing, the concurrent license model's counting type is 3 (Per Identity Per Station). Sample Code No 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 getentfeaturelmattributes.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpGet get = new HttpGet (" query = new StringBuffer(); setparameter("ftrid", ""); setparameter("lineitemid", ""); setparameter("productid", ""); 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();

125 3.4. Managing Entitlements 119 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 <emsresponse> <stat>ok</stat> <itemfeaturelicensemodel> <entftrlmid>1</entftrlmid> <feature> <id>1</id> <featurename>f1</featurename> <featureid>1</featureid> </feature> <licensemodel> <licensemodelid>2</licensemodelid> <licensemodelname>postpaid</licensemodelname> </licensemodel> <itemfeaturelicensemodelattributes> <itemfeaturelicensemodelattribute> <attributeid>1</attributeid> <attributename>start_date</attributename> <attributevalue> :00</attributevalue> <groupname>time</groupname> <subgroupname>license Validity</subgroupname> <overridable>true</overridable> </itemfeaturelicensemodelattribute> <itemfeaturelicensemodelattribute> <attributeid>2</attributeid> <attributename>end_date</attributename> <attributevalue> :59</attributevalue> <groupname>time</groupname> <subgroupname>license Validity</subgroupname> <overridable>true</overridable> </itemfeaturelicensemodelattribute> <itemfeaturelicensemodelattribute> <attributeid>4</attributeid> <attributename>usage Type</attributename> <attributevalue>2</attributevalue> <groupname>usage Type</groupname> <subgroupname>usage Type</subgroupname> <overridable>true</overridable> </itemfeaturelicensemodelattribute> <itemfeaturelicensemodelattribute> <attributeid>16</attributeid> <attributename>vendor Attribute</attributename> <attributevalue /> <groupname>vendor Attribute</groupname> <subgroupname>vendor Attribute</subgroupname> <overridable>true</overridable> </itemfeaturelicensemodelattribute>

126 120 Chapter 3: Web Service Interfaces <itemfeaturelicensemodelattribute> <attributeid>17</attributeid> <attributename>capacity Attribute</attributename> <attributevalue>100</attributevalue> <groupname>capacity Attribute</groupname> <subgroupname>capacity Attribute</subgroupname> <overridable>true</overridable> </itemfeaturelicensemodelattribute> </itemfeaturelicensemodelattributes> </itemfeaturelicensemodel> </emsresponse> See Also: Output Format for Failure Error Codes Error Code 100 Invalid request parameter. 101 Not authorized to use this product. 102 Invalid data entered 118 {field should be of datatype Integer. [Note: This error code is applicable for the fields - License modelid, entid, ftrid, customerid, lmid, templatetype, lineitemid, CustomerId, stationcount,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, and granularity.] 128 You should log on first. 132 The URL address does not exist. 618 Could not find the entitlement line item. 644 Invalid lineitem Id. 680 The feature does not exist in the given product. 704 The entitlement item does not have this product 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. Update License Model Attributes for a Line Item Update values of license model attributes of the features associated with a line item. The corresponding entitlement should be in 'draft' or 'reconfigure' state. The input of this Web service is the output XML of getentfeaturelmattributes.xml. In the input XML, only the attributes with "overridable" property set to "true" can be modified, and the remaining information is treated as read-only.

127 3.4. Managing Entitlements 121 Default Protocol Method Type URI HTTPS POST setentfeaturelmattributes.xml Post Parameters Parameter Valid Values Optional entfeaturelmattributes XML string containing attributes to be updated String No Sample Code import java.io.ioexception; import org.apache.http.params.httpparams; public class EMSSample { private static DefaultHttpClient httpclient = new DefaultHttpClient(); private static Principal principal = null; public static String setentfeaturelmattributes.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpPost post = new HttpPost (" List<NameValuePair> nvps = new ArrayList<NameValuePair>(); nvps.add(new BasicNameValuePair("entFeatureLMAttributes", "")); post.setentity(new UrlEncodedFormEntity(nvps, HTTP.UTF_8)); HttpResponse response = httpclient.execute(post, 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); Sample Response <emsresponse> <stat>ok</stat> </emsresponse> See Also: Output Format for Failure

128 122 Chapter 3: Web Service Interfaces Error Codes Error Code 100 Invalid request parameter. 101 Not authorized to use this product. 102 Invalid data entered 118 {field should be of datatype Integer. [Note: This error code is applicable for the fields - License modelid, entid, ftrid, customerid, lmid, templatetype, lineitemid, CustomerId, stationcount,and granularity.] 128 You should log on first. 132 The URL address does not exist. 618 Could not find the entitlement line item. 668 Could not find the entitlement license model for id={actual value 679 License model does not exist in given feature. 692 Entitlement already in Complete state and cannot be Updated/Deleted The entitlement item does not have this product The product does not have this feature Invalid attribute value XML schema Validation Failed Only Per Login counting type is allowed in concurrent license model for On-Premise (Entitlement level and Detach Mode) entitlement 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 Invalid max usage limit. Max usage limit between is allowed Entitlement Service Agreement Attributes The following table summarizes the RESTlike interfaces that help modify and search entitlement service agreement attributes. Method URI GET getserviceagreementattributes.xml Retrieve Service Agreement Attributes for a Line Item POST updateserviceagreementattributes.xml Update Service Agreement Attributes for a Line Item Retrieve Service Agreement Attributes for a Line Item Retrieves service agreement attributes inside a line item.

129 3.4. Managing Entitlements 123 Default Protocol Method Type URI HTTPS GET getserviceagreementattributes.xml Query Parameters Parameter Valid Values Optional lineitemid Specify the line item ID. Integer No 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 getserviceagreementattributes.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpGet get = new HttpGet (" query = new StringBuffer(); setparameter("lineitemid", ""); 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 <emsresponse> <stat>ok</stat>

130 124 Chapter 3: Web Service Interfaces <itemserviceagreement> <entproductsaid>1</entproductsaid> <serviceagreement> <serviceagreementid>1</serviceagreementid> <serviceagreementname>service Agreement Template</serviceAgreementName> </serviceagreement> <itemserviceagreementattributes> <itemserviceagreementattribute> <attributeid>1</attributeid> <attributename>billing Cycle</attributeName> <attributevalue>43200</attributevalue> <groupname>preferences</groupname> <subgroupname>billing Preferences</subGroupName> <overridable>false</overridable> </itemserviceagreementattribute> <itemserviceagreementattribute> <attributeid>2</attributeid> <attributename>day</attributename> <attributevalue>15</attributevalue> <groupname>preferences</groupname> <subgroupname>billing Preferences</subGroupName> <overridable>false</overridable> </itemserviceagreementattribute> <itemserviceagreementattribute> <attributeid>3</attributeid> <attributename>policy (days)</attributename> <attributevalue>1440</attributevalue> <groupname>preferences</groupname> <subgroupname>aggregation Preferences</subGroupName> <overridable>false</overridable> </itemserviceagreementattribute> <itemserviceagreementattribute> <attributeid>4</attributeid> <attributename>frequency (in minutes)</attributename> <attributevalue>01</attributevalue> <groupname>preferences</groupname> <subgroupname>aggregation Preferences</subGroupName> <overridable>true</overridable> </itemserviceagreementattribute> </itemserviceagreementattributes> </itemserviceagreement> </emsresponse> See Also: Output Format for Failure Error Codes Error Code 101 Not authorized to use this product. 118 {field should be of datatype Integer. [Note: This error code is applicable for the fields - License modelid, entid, ftrid, customerid, lmid, templatetype, lineitemid, CustomerId, stationcount,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, and granularity.]

131 3.4. Managing Entitlements 125 Error Code 128 You should log on first. 132 The URL address does not exist. 618 Could not find the entitlement line item 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. Update Service Agreement Attributes for a Line Item Updates service agreement attributes for a line item for which the corresponding entitlement is in Draft stage. The input of this Web service is the output of getserviceagreementattributes.xml. In the input XML, only the attributes with "overridable" property set to "true" can be modified, and the remaining information is treated as read-only. Only the overridable attributes are modified. Default Protocol Method Type URI HTTPS POST updateserviceagreementattributes.xml POST Parameters Parameter entserviceagreementattributesxml XML string containing attributes to be updated. Sample Code Valid Values String Optional No import java.io.ioexception; import org.apache.http.params.httpparams; public class EMSSample { private static DefaultHttpClient httpclient = new DefaultHttpClient(); private static Principal principal = null; public static String updateserviceagreementattributes.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpPost post = new HttpPost (" List<NameValuePair> nvps = new ArrayList<NameValuePair>();

132 126 Chapter 3: Web Service Interfaces nvps.add(new BasicNameValuePair("entServiceAgreementAttributesXml", "")); post.setentity(new UrlEncodedFormEntity(nvps, HTTP.UTF_8)); HttpResponse response = httpclient.execute(post, 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); Sample Response <?xml version="1.0" encoding="utf-8"?> <emsresponse> <stat>ok</stat> </emsresponse> See Also: Output Format for Failure Error Codes Error Code 101 Not authorized to use this product. 112 The input string is not valid. 128 You should log on first. 132 The URL address does not exist. 618 Could not find the entitlement line item. 692 Entitlement already in Complete state and cannot be Updated/Deleted Service agreement attribute value can be updated only for 'Draft' entitlement EntitlementServiceAgreement not found for passed ID={ XML schema Validation Failed 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.

133 3.4. Managing Entitlements Enterprise User Identities In case of enterprise named entitlement, an enterprise user can access the service only if his user ID 1 is mentioned in the entitlement. While creating a named entitlement, you need to specify number of users. After creating the entitlement, you need to add the user IDs who are allowed to use the entitlement. This sections lists the Web services available for adding, removing, and retrieving the enterprise user IDs. Method URI POST addenterpriseuserids.xml Add Enterprise User IDs POST removeenterpriseuserids.xml Remove Enterprise User IDs GET retrieveenterpriseidentities.xml Retrieve Enterprise User IDs Add Enterprise User IDs Add user IDs to a enterprise named entitlement. The entitlement must be deployed before adding the user IDs. Default Protocol Method Type URI HTTPS POST addenterpriseuserids.xml Post Parameters Parameter Valid Values Optional entid Identifier of the entitlement 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 No userids User name List of strings (comma separated) No Sample Code import java.io.ioexception; 1 Identifies a user in case of a named entitlements (both retail and enterprise). User ID is same as the identifier coming from the ISV application after authorizing a user of named entitlement.

134 128 Chapter 3: Web Service Interfaces import org.apache.http.params.httpparams; public class EMSSample { private static DefaultHttpClient httpclient = new DefaultHttpClient(); private static Principal principal = null; public static String addenterpriseuserids.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpPost post = new HttpPost(" List<NameValuePair> nvps = new ArrayList<NameValuePair>(); nvps.add(new BasicNameValuePair("entId", "")); nvps.add(new BasicNameValuePair("userIds", "")); post.setentity(new UrlEncodedFormEntity(nvps, HTTP.UTF_8)); HttpResponse response = httpclient.execute(post, 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); Sample Response <?xml version="1.0" encoding="utf-8"?> <emsresponse> <stat>ok</stat> </emsresponse> See Also: Output Format for Failure Error codes Error Code 101 Not authorized to use this product. 107 An internal error occurred! Please report the error to System administrator. 118 {field should be of datatype Integer. [Note: This error code is applicable for the fields - License modelid, entid, ftrid, customerid, lmid, templatetype, lineitemid, CustomerId, stationcount,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, and granularity.]

135 3.4. Managing Entitlements 129 Error Code 128 You should log on first. 132 The URL address does not exist. 621 Entitlement does not exist. Retry with a correct ID Entitlement is not Activated Entitlement is for a Retail Customer Enterprise UserIDs not added Entitlement is for an unnamed enterprise Customer Identity(s) not added. [Note: The reason is dynamic, such as total number of permitted identities exceeded.] 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. Remove Enterprise User IDs Remove user IDs from a enterprise named entitlement. The entitlement must be deployed and should have user IDs added. Default Protocol Method Type URI HTTPS POST removeenterpriseuserids.xml Post Parameters Parameter entid Identifier of the entitlement 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. Valid Values Integer Optional No userids Names of the users. List of Strings (comma separated) No Sample Code import java.io.ioexception; import org.apache.http.params.httpparams;

136 130 Chapter 3: Web Service Interfaces public class EMSSample { private static DefaultHttpClient httpclient = new DefaultHttpClient(); private static Principal principal = null; public static String removeenterpriseuserids.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpPost post = new HttpPost (" List<NameValuePair> nvps = new ArrayList<NameValuePair>(); nvps.add(new BasicNameValuePair("entId", "")); nvps.add(new BasicNameValuePair("userIds", "")); post.setentity(new UrlEncodedFormEntity(nvps, HTTP.UTF_8)); HttpResponse response = httpclient.execute(post, 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); Sample Response <?xml version="1.0" encoding="utf-8"?> <emsresponse> <stat>ok</stat> </emsresponse> See Also: Output Format for Failure Error codes Error Code 101 Not authorized to use this product. 107 An internal error occurred! Please report the error to System administrator. 118 {field should be of datatype Integer. [Note: This error code is applicable for the fields - License modelid, entid, ftrid, customerid, lmid, templatetype, lineitemid, CustomerId, stationcount,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, and granularity.]

137 3.4. Managing Entitlements 131 Error Code 128 You should log on first. 132 The URL address does not exist. 621 Entitlement does not exist. Retry with a correct ID Entitlement is not Activated Entitlement is for a Retail Customer Enterprise UserID not removed Entitlement is for an unnamed enterprise Customer Enterprise UserIDs cannot be added/deleted in reconfigure stage 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. Retrieve Enterprise User IDs Return the list of user IDs added to an enterprise named entitlement. The entitlement must be deployed on Sentinel Cloud Connect. Default Protocol Method Type URI HTTPS GET retrieveenterpriseidentities.xml Post Parameters Parameter entid Identifier of the entitlement. 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. Valid Values Optional Integer No lastmodified Creation or Modification time stamp. Long 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;

138 132 Chapter 3: Web Service Interfaces private static StringBuffer query; public static String retrieveenterpriseidentities.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpGet get = new HttpGet(" query = new StringBuffer(); setparameter("entid", "1"); setparameter("lastmodified", " "); 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 <emsresponse> <stat>ok</stat> <entitlements> <entitlement> <entid>30</entid> <eid>5ffc31****</eid> <entitlementtype>enterprise</entitlementtype> <startdate> </startdate> <enddate> </enddate> <customer> <customerid>9</customerid> <customername>con7</customername> </customer> <contact> <contactid>16</contactid> <contact id>[email protected]</contact id> </contact> <state>2</state> <status>0</status> <refid1 /> <refid2 /> <creationtime> </creationtime> <modificationtime> </modificationtime>

139 3.4. Managing Entitlements 133 </entitlement> </entitlements> <total>1</total> </emsresponse> See Also: Output Format for Failure Error codes Error Code 101 Not authorized to use this product. 107 An internal error occurred! Please report the error to System administrator. 118 {field should be of datatype Integer. [Note: This error code is applicable for the fields - License modelid, entid, ftrid, customerid, lmid, templatetype, lineitemid, CustomerId, stationcount,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, 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, 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, and granularity.] 128 You should log on first. 132 The URL address does not exist Entitlement is for a Retail Customer Enterprise UserID not removed Entitlement is for an unnamed enterprise Customer {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 Reconfiguring Entitlements Entitlement Reconfiguration is the process of updating a committed entitlement. You can do the following updates while reconfiguring an entitlement:

140 134 Chapter 3: Web Service Interfaces Add line item(s) Update license model attributes Edit entitlement item, that is concurrent users and number of users Update station count of on-premise entitlements created with detach mode Following are the steps to reconfigure an entitlement: 1. Call the initiatereconfigure.xml Web service to initiate the reconfiguration process. The lifecycle stage of entitlement is set to Reconfigured (state 3). 2. To update concurrent limit and number of users of an enterprise named entitlement, call the updateentitlementitem.xml Web service. 3. To update license model attributes of the feature associated with a line item: a. First, call the getentfeaturelmattributes.xml Web service. b. Then, call the setentfeaturelmattributes.xml Web service, which uses the output of the getentfeaturelmattributes as input. You can update the values of overridable attributes. 4. To add a new product (line item) to an entitlement, call the addentitlementitem.xml Web service. 5. To include or exclude features in a line item, call the updatefeaturelineitemassociation Web service. 6. To update the license model of a feature in a line item, call the updatelineitemfeaturelmassociation Web service. 4. To update station count of on-premise entitlements created with detach mode, call the updateentitlement.xml Web service. 5. Finally, call commitentitlement.xml to deploy all the changes made to the entitlement. The flow is depicted in the diagram below:

141 3.4. Managing Entitlements 135 Reconfiguration Flow Initiate Entitlement Reconfiguration This Web service will initiate the reconfiguration process by modifying the lifecycle stage of entitlement as Reconfigure or state 3. Default Protocol Method Type URI HTTPS POST initiatereconfigure.xml POST Parameters Parameter entid Identifier of the entitlement to be reconfigured. Note: The entid is the handle returned by the Valid Values Optional Integer (>0) No

142 136 Chapter 3: Web Service Interfaces Parameter Valid Values Optional createentitlement.xml web service. You can use the searchentitlements.xml web service to retrieve entid for an entitlement. Sample Code import java.io.ioexception; import org.apache.http.params.httpparams; public class EMSSample { private static DefaultHttpClient httpclient = new DefaultHttpClient(); private static Principal principal = null; public static String initiatereconfigure.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpPost post = new HttpPost (" List<NameValuePair> nvps = new ArrayList<NameValuePair>(); nvps.add(new BasicNameValuePair("entId", "")); post.setentity(new UrlEncodedFormEntity(nvps, HTTP.UTF_8)); HttpResponse response = httpclient.execute(post, 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); Sample Response <?xml version="1.0" encoding="utf-8"?> <emsresponse> <stat>ok</stat> </emsresponse> See Also: Output Format for Failure

143 3.5. State and Status Information 137 Error Codes Error Code 100 Invalid request parameter. 101 Not authorized to use this product. 102 Invalid data entered 107 An internal error occurred! Please report the error to System administrator. 118 {field should be of datatype Integer. [Note: This error code is applicable for the fields - License modelid, entid, ftrid, customerid, lmid, templatetype, lineitemid, CustomerId, stationcount,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, 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, and granularity.] 128 You should log on first. 132 The URL address does not exist. 621 Entitlement does not exist. Retry with a correct ID Entitlement is not marked complete Entitlement is already in Reconfigure State 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 State and Status Information The following Web services are covered under this section. Method URI GET retrievelicensestate.xml Retrieve License State GET retrievecontractstatus.xml Retrieve Contract Status POST changecontractstatus.xml Change Contract Status GET retrievecontractlineitemstatus.xml Retrieve Contract Line Item Status POST changecontractlineitemstatus.xml Change Contract Line Item Status

144 138 Chapter 3: Web Service Interfaces Retrieve License State Retrieves the license state for the given line item and ftrid. The license state can be: 1: Not Active 2: Active 4: Expired 8: Exhausted 32: ExpiredGrace 64: ExhaustedGrace The entitlement should be in the Complete lifecycle stage. Default Protocol Method Type URI HTTPS GET retrievelicensestate.xml Query Parameters Parameter Valid Values Optional lineitemid Specify the line item ID. Integer No ftrid Sample Code Specify the unique record ID of feature (as stored in EMS database) corresponding to the specified line item. Note: The ftrid is the handle returned by the addfeature.xml web service. You can retrieve ftrid by using the featurelist.xml web service. Integer No 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 retrievelicensestate.xml()throws Exception { if(!verifylogin()){ return "login failed";

145 3.5. State and Status Information 139 HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpGet get = new HttpGet (" query = new StringBuffer(); setparameter("ftrid", ""); setparameter("lineitemid", ""); 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 <?xml version="1.0" encoding="utf-8" standalone="yes"?> <emsresponse> <stat>ok</stat> <licensestate>1</licensestate> </emsresponse> See Also: Output Format for Failure Error Codes Error Code 100 Invalid request parameter. 102 Invalid data entered 107 An internal error occurred! Please report the error to System administrator. 118 {field should be of datatype Integer. [Note: This error code is applicable for the fields - License modelid, entid, ftrid, customerid, lmid, templatetype, lineitemid, CustomerId, stationcount,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, and granularity.]

146 140 Chapter 3: Web Service Interfaces Error Code 128 You should log on first. 132 The URL address does not exist. 309 Unable to find feature. 618 Could not find the entitlement line item. 680 The feature does not exist in the given product Entitlement is not marked complete 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 Retrieve Contract Status Retrieves the contract status for the given entitlement. The status of contract can be: 0: Enabled 1: Disabled 2: Revoked The entitlement should be in the Draft or Complete lifecycle stage. Default Protocol Method Type URI HTTPS GET retrievecontractstatus.xml Query Parameters Parameter entid Identifier of the entitlement. 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. Valid Values Optional Integer No Sample Code import java.io.ioexception; import java.net.urldecoder; import org.apache.http.params.httpparams;

147 3.5. State and Status Information 141 public class EMSSample { private static DefaultHttpClient httpclient = new DefaultHttpClient(); private static Principal principal = null; private static StringBuffer query; public static String retrievecontractstatus.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpGet get = new HttpGet (" query = new StringBuffer(); setparameter("entid", ""); 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 <?xml version="1.0" encoding="utf-8" standalone="yes"?> <emsresponse> <stat>ok</stat> <status>0</status> </emsresponse> See Also: Output Format for Failure Error Codes Error Code 100 Invalid request parameter. 101 Not authorized to use this product. 102 Invalid data entered

148 142 Chapter 3: Web Service Interfaces Error Code 107 An internal error occurred! Please report the error to System administrator. 118 {field should be of datatype Integer. [Note: This error code is applicable for the fields - License modelid, entid, ftrid, customerid, lmid, templatetype, lineitemid, CustomerId, stationcount,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, and granularity.] 128 You should log on first. 132 The URL address does not exist. 621 Entitlement does not exist. Retry with a correct ID Entitlement is not marked complete 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 Change Contract Status Updates the contract status for the given entitlement. The contract status can be: 0: Enabled 1: Disabled 2: Revoked The entitlement should be in the Complete lifecycle stage. Default Protocol Method Type URI HTTPS POST changecontractstatus.xml Query Parameters Parameter entid Identifier of the entitlement. 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. Valid Values Integer Optional No status Status to be updated Integer(0 - Enable, 1 - Disable, 2 - No

149 3.5. State and Status Information 143 Parameter Sample Code Valid Values Revoke) Optional 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 changecontractstatus.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpGet get = new HttpGet (" query = new StringBuffer(); setparameter("entid", ""); setparameter("status", ""); 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 <?xml version="1.0" encoding="utf-8" standalone="yes"?> <emsresponse> <stat>ok</stat> </emsresponse>

150 144 Chapter 3: Web Service Interfaces See Also: Output Format for Failure Error Codes Error Code 100 Invalid request parameter. 101 Not authorized to use this product. 102 Invalid data entered 107 An internal error occurred! Please report the error to System administrator. 118 {field should be of datatype Integer. [Note: This error code is applicable for the fields - License modelid, entid, ftrid, customerid, lmid, templatetype, lineitemid, CustomerId, stationcount,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, 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, and granularity.] 128 You should log on first. 132 The URL address does not exist. 621 Entitlement does not exist. Retry with a correct ID. 658 Entitlement is not in complete state, please contact Administrator Entitlement is not marked complete Invalid value for status Valid values are 0(enable), 1(Disable), 2(Revoke) Status not updated as the status specified is already set Entitlement is already Revoked 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 Retrieve Contract Line Item Status Retrieves the status of the line item corresponding to the lineitemid provided. The contract line item status can be: 0: Enabled 1: Disabled

151 3.5. State and Status Information 145 2: Revoked The entitlement should be in Draft or Complete lifecycle stage. Default Protocol Method Type URI HTTPS GET retrievecontractlineitemstatus.xml Query Parameters Parameter Valid Values Optional lineitemid Specify line item ID. Integer No 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 retrievecontractlineitemstatus.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpGet get = new HttpGet (" query = new StringBuffer(); setparameter("lineitemid", ""); 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 + "&");

152 146 Chapter 3: Web Service Interfaces Sample Response <?xml version="1.0" encoding="utf-8" standalone="yes"?> <emsresponse> <stat>ok</stat> <status>0</status> </emsresponse> See Also: Output Format for Failure Error Codes Error Code 100 Invalid request parameter. 101 Not authorized to use this product. 102 Invalid data entered 107 An internal error occurred! Please report the error to System administrator. 118 {field should be of datatype Integer. [Note: This error code is applicable for the fields - License modelid, entid, ftrid, customerid, lmid, templatetype, lineitemid, CustomerId, stationcount,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, and granularity.] 128 You should log on first. 132 The URL address does not exist. 618 Could not find the entitlement line item Entitlement is not marked complete 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 Change Contract Line Item Status Changes the line item status for the given line item ID. The status of line item can be: 0: Enabled 1: Disabled 2: Revoked The entitlement should be in the Complete lifecycle stage.

153 3.5. State and Status Information 147 Default Protocol Method Type URI HTTPS POST changecontractlineitemstatus.xml Post Parameters Parameter Valid Values Optional lineitemid Specify line item ID. Integer No status Sample Code Specify the required line item status. Integer (0 - Enable, 1 - Disable, 2 - Revoke) No 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 changecontractlineitemstatus.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpGet get = new HttpGet (" query = new StringBuffer(); setparameter("status", ""); setparameter("lineitemid", ""); 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 + "&");

154 148 Chapter 3: Web Service Interfaces Sample Response <?xml version="1.0" encoding="utf-8"?> <emsresponse> <code>618</code> <desc>could not find the entitlement line item.</desc> <stat>fail</stat> </emsresponse> See Also: Output Format for Failure Error Codes Error Code 100 Invalid request parameter. 101 Not authorized to use this product. 102 Invalid data entered 107 An internal error occurred! Please report the error to System administrator. 118 {field should be of datatype Integer. [Note: This error code is applicable for the fields - License modelid, entid, ftrid, customerid, lmid, templatetype, lineitemid, CustomerId, stationcount,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, 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, and granularity.] 128 You should log on first. 132 The URL address does not exist. 618 Could not find the entitlement line item. 658 Entitlement is not in complete state, please contact Administrator Entitlement is not marked complete Invalid value for status Valid values are 0(enable), 1(Disable), 2(Revoke) LineItem does not exist in the given entitlement Cannot Enable line item of a Disabled Contract Status not updated as the status specified is already set Line Item is already Revoked Invalid Web service version provided 1084 No Web service version provided

155 3.6. Usage Information 149 Error Code 1088 The EMS system is running on HTTPS. Please provide the correct Web service URL Usage Information This section explains the Web services that you can use to view usage bills, logs, concurrent sessions, usage count, and peak capacity. This section includes the following Web Services: Method URI GET retrieveusagelog.xml Retrieve Usage Log GET getcustomerusagelog.xml Retrieve Customer Usage Log GET getcustomerusagelogbasedonvendorinfo Retrieve Customer Usage Log for Vendor Information GET retrieveusagebilling.xml Retrieve Usage Bill GET retrievecurrentsessions.xml View Concurrent Sessions GET retrievecurrentusagecount.xml Retrieve Current Usage Count POST retrievepeakcapacity.xml Retrieve Peak Capacity Retrieve Usage Log Retrieves the usage log details for a given product of an entitlement. The entitlement must be deployed on Sentinel Cloud Connect. You can view usage of an entitlement only if it has been aggregated by Data Engine. Default Protocol Method Type URI HTTPS GET retrieveusagelog.xml Query Parameters Parameter entid Identifier of the entitlement. 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. Valid Values Optional Integer No productname Name of the product. String No productversion Version of the product. String No

156 150 Chapter 3: Web Service Interfaces Parameter startdate Start date from when the usage log is to be obtained. The startdate should be earlier than or same as the enddate. Valid Values Optional String (yyyymmdd) enddate End date till when the usage log is to be obtained. String (yyyymmdd) pageindex Index of the currently displayed page. Integer Yes pagesize Number of records to be displayed on a page. Integer Yes Sample Code No No 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 retrieveusagelog.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpGet get = new HttpGet(" query = new StringBuffer(); setparameter("startdate", ""); setparameter("entid", ""); setparameter("pagesize", ""); setparameter("enddate", ""); setparameter("productversion", ""); setparameter("productname", ""); setparameter("pageindex", ""); 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);

157 3.6. Usage Information 151 static void setparameter(string key, String value) { if (query.tostring().equals("")) { query.append("?" + key + "=" + value + "&"); else { query.append(key + "=" + value + "&"); Sample Response <?xml version="1.0" encoding="utf-8" standalone="yes"?> <emsresponse> <stat>ok </stat> <total>1</total> <usagerecords> <usagerecord> <featurename>addition</featurename> <userid>pre</userid> <startdate>fri Jan 01 00:00:00 IST 2010</startDate> <enddate>sun Jan 01 23:59:59 IST 2012</endDate> <totalconsumption>6</totalconsumption> <usagetype>countbased</usagetype> <recordcount>6</recordcount> </usagerecord> </usagerecords> </emsresponse> See Also: Output Format for Failure Error Codes Error Code 101 Not authorized to use this product. 107 An internal error occurred! Please report the error to System administrator. 118 {field should be of datatype Integer. [Note: This error code is applicable for the fields - License modelid, entid, ftrid, customerid, lmid, templatetype, lineitemid, CustomerId, stationcount,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, and granularity.] 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. 132 The URL address does not exist. 302 No product exists for given Name and Version.

158 152 Chapter 3: Web Service Interfaces Error Code 617 Start date cannot be greater than end date 621 Entitlement does not exist. Retry with a correct ID. 658 Entitlement is not in complete state, please contact administrator Unable to retrieve Usage Data Entitlement is not marked complete 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 Maximum pageindex allowed for specified size is Retrieve Customer Usage Log Returns the usage log details for a given customer. It obtains details of the entitlements that are deployed on the Sentinel Cloud Connect. Default Protocol Method Type URI HTTPS GET getcustomerusagelog.xml Query Parameters Parameter Valid Values Optional customerid startdate The unique record ID of the customer in EMS database. Start date from when the usage log is to be obtained. The startdate should be earlier than or same as the enddate. Integer String (yyyymm-dd) enddate End date till when the usage bill is to be obtained. String (yyyymm-dd) pageindex Index of the currently displayed page. Integer Yes pagesize Number of records to be displayed on a page Integer Yes Sample Code No No No import java.io.ioexception; import java.net.urldecoder;

159 3.6. Usage Information 153 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 getcustomerusagelog.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpGet get = new HttpGet(" query = new StringBuffer(); setparameter("startdate", ""); setparameter("customerid", ""); setparameter("pagesize", ""); setparameter("enddate", ""); setparameter("pageindex", ""); 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 <?xml version="1.0" encoding="utf-8" standalone="yes"?> <emsresponse> <stat>ok</stat> <total>4</total> <customer> <customername>cus209</customername> <entitlements> <entitlement> <entid>9</entid> <lineitems> <lineitem> <itemproduct> <product> <productname>pro_1</productname>

160 154 Chapter 3: Web Service Interfaces <productversion>209_1</productversion> </product> </itemproduct> <usagerecords> <usagerecord> <featurename>f3</featurename> <userid>vikas2</userid> <startdate>02/01/2012</startdate> <enddate>02/29/2012</enddate> <totalconsumption>23</totalconsumption> <usagetype>timebased</usagetype> <recordcount>1</recordcount> </usagerecord> </usagerecords> </lineitem> </lineitems> </entitlement> <entitlement> <entid>5</entid> <lineitems> <lineitem> <itemproduct> <product> <productname>pro_1</productname> <productversion>209_1</productversion> </product> </itemproduct> <usagerecords> <usagerecord> <featurename>f1</featurename> <userid>vikas</userid> <startdate>02/01/2012</startdate> <enddate>02/29/2012</enddate> <totalconsumption>15</totalconsumption> <usagetype>timebased</usagetype> <recordcount>1</recordcount> </usagerecord> <usagerecord> <featurename>f2</featurename> <userid>vikas1</userid> <startdate>02/01/2012</startdate> <enddate>02/29/2012</enddate> <totalconsumption>0</totalconsumption> <usagetype>countbased</usagetype> <recordcount>1</recordcount> </usagerecord> </usagerecords> </lineitem> </lineitems> </entitlement> <entitlement> <entid>4</entid> <lineitems> <lineitem> <itemproduct> <product> <productname>pro_2</productname> <productversion>209_2</productversion> </product> </itemproduct>

161 3.6. Usage Information 155 <usagerecords /> </lineitem> </lineitems> </entitlement> <entitlement> <entid>1</entid> <lineitems> <lineitem> <itemproduct> <product> <productname>pro_1</productname> <productversion>209_1</productversion> </product> </itemproduct> <usagerecords> <usagerecord> <featurename>f2</featurename> <userid>identity</userid> <startdate>02/01/2012</startdate> <enddate>02/29/2012</enddate> <totalconsumption>0</totalconsumption> <usagetype>timebased</usagetype> <recordcount>2</recordcount> </usagerecord> </usagerecords> </lineitem> </lineitems> </entitlement> </entitlements> </customer> </emsresponse> See Also: Output Format for Failure Error Codes Error Code 101 Not authorized to use this product. 107 An internal error occurred! Please report the error to System administrator. 118 {field should be of datatype Integer. [Note: This error code is applicable for the fields - License modelid, entid, ftrid, customerid, lmid, templatetype, lineitemid, CustomerId, stationcount,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, and granularity.] 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. 512 The customer does not exist

162 156 Chapter 3: Web Service Interfaces Error Code 617 Start date cannot be greater than end date 1081 Invalid Web service version provided 1082 No entitlement exists for the given customer No Web service version provided 1088 The EMS system is running on HTTPS. Please provide the correct Web service URL Maximum pageindex allowed for specified size is Retrieve Customer Usage Log for Vendor Information Returns the usage log details of a customer grouped by vendor information. Default Protocol Method Type URI HTTPS GET getcustomerusagelogbasedonvendorinfo.xml Query Parameters Parameter Valid Values customerid The unique record ID of the customer in EMS database. Integer No startdate Start date from when the usage log is to be obtained. The startdate should be earlier than or same as the enddate. Date enddate End date till when the usage log is to be obtained. Date No usagetype Type of data aggregation. Possible values are 1 (Count Based) and 2 (Time Based). Integer pageindex Index of the currently displayed page. Integer Yes pagesize Number of records to be displayed on a page Integer Yes Sample Code Optional No Yes 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;

163 3.6. Usage Information 157 public static String getcustomerusagelogbasedonvendorinfo.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpGet get = new HttpGet (" query = new StringBuffer(); setparameter("startdate", ""); setparameter("customerid", ""); setparameter("pagesize", ""); setparameter("usagetype", ""); setparameter("enddate", ""); setparameter("pageindex", ""); 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 <emsresponse> <customername>lm</customername> <customerrefid>e </customerrefid> <stat>ok</stat> <total>6</total> <usagedata> <usageinfolist> <usageinfo> <features> <feature> <featureid>2</featureid> <featurename>feat</featurename> <usagetype>2</usagetype> <usagevalue>5</usagevalue> </feature> </features>

164 158 Chapter 3: Web Service Interfaces <vendorinfo>sample vendor datasample sample vendor datasample vendor datasample vendor datasample vendor datasample vendor datasample vendor datasample vendor datasample vendor datasample vendor datasample vendor datasample vendor datasample vendor datasample vendor</vendorinfo> </usageinfo> <usageinfo> <features> <feature> <featureid>2</featureid> <featurename>feat</featurename> <usagetype>1</usagetype> <usagevalue>100</usagevalue> </feature> <feature> <featureid>2</featureid> <featurename>feat</featurename> <usagetype>2</usagetype> <usagevalue>107</usagevalue> </feature> </features> <vendorinfo>vendor1</vendorinfo> </usageinfo> <usageinfo> <features> <feature> <featureid>2</featureid> <featurename>feat</featurename> <usagetype>1</usagetype> <usagevalue>100</usagevalue> </feature> <feature> <featureid>2</featureid> <featurename>feat</featurename> <usagetype>2</usagetype> <usagevalue>100</usagevalue> </feature> </features> <vendorinfo>vendor2</vendorinfo> </usageinfo> <usageinfo> <features> <feature> <featureid>2</featureid> <featurename>feat</featurename> <usagetype>1</usagetype> <usagevalue>100</usagevalue> </feature> <feature> <featureid>2</featureid> <featurename>feat</featurename> <usagetype>2</usagetype> <usagevalue>100</usagevalue> </feature> </features> <vendorinfo>vendor3</vendorinfo> </usageinfo> <usageinfo> <features>

165 3.6. Usage Information 159 <feature> <featureid>2</featureid> <featurename>feat</featurename> <usagetype>1</usagetype> <usagevalue>100</usagevalue> </feature> </features> <vendorinfo>vendor4</vendorinfo> </usageinfo> <usageinfo> <features> <feature> <featureid>2</featureid> <featurename>feat</featurename> <usagetype>2</usagetype> <usagevalue>100</usagevalue> </feature> </features> <vendorinfo>vendor5</vendorinfo> </usageinfo> </usageinfolist> </usagedata> </emsresponse> See Also: Output Format for Failure Error Codes Error Code 101 Not authorized to use this product. 107 An internal error occurred! Please report the error to System administrator. 118 {field should be of datatype Integer. [Note: This error code is applicable for the fields - License modelid, entid, ftrid, customerid, lmid, templatetype, lineitemid, CustomerId, stationcount,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, and granularity.] 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. 512 The customer does not exist 617 Start date cannot be greater than end date 1081 Invalid Web service version provided 1084 No Web service version provided 1102 Maximum pageindex allowed for specified size is 1.

166 160 Chapter 3: Web Service Interfaces Retrieve Usage Bill Retrieve the billing data for a specific product included in an entitlement. Different type of bills that you can view are: Itemized Bill: A descriptive bill that provides consumption details for a product on per feature per user basis. Detailed Bill: It is less descriptive than the itemized bill and provides consumption details per feature. Brief Bill: It provides a brief summary of the products consumed within a specified period. This data is partially processed data that can be used as the basis of generating bills, but is not the actual bill. This will need further processing before it can be used for billing purposes. Default Protocol Method Type URI HTTPS GET retrieveusagebilling.xml Query Parameters Parameter Valid Values entid Identifier of the entitlement. 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 Default Value Optional No billtype Bill type. The options are: Integer No 1: Brief bill 2: Detailed bill 3: Itemized bill productname Name of the product String No productversion Version of the product String No startdate Start date from when the usage bill is to be obtained. The startdate should be earlier than or same as the enddate. String (yyyy-mmdd) No enddate End date till when the usage bill is to be obtained. String (yyyy-mmdd) No

167 3.6. Usage Information 161 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 retrieveusagebilling.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpGet get = new HttpGet (" query = new StringBuffer(); setparameter("billtype", ""); setparameter("startdate", ""); setparameter("entid", ""); setparameter("enddate", ""); setparameter("productversion", ""); setparameter("productname", ""); 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 Brief Billing <!--This is an automated/formatted XML output for the queried ISV aggregation information.--> <BriefBillingInformation> <ProductInformation>

168 162 Chapter 3: Web Service Interfaces <ProductName>Pro_1</ProductName> <ProductVersion>209_1</ProductVersion> <ContractID>5519dded-51e9-46cf-b6b cac6</ContractID> <TenantIdentifier>1</TenantIdentifier> </ProductInformation> <BreakUpInformation> <ProductConsumption> <ConsumptionPattern> <Consumption> <Duration> <From>Not-Specified</From> <Till>Mon, 27 Feb :44:46 000</Till> </Duration> <Value>15000</Value> <TotalRecords>1</TotalRecords> </Consumption> </ConsumptionPattern> </ProductConsumption> </BreakUpInformation> <BreakUpInformation> <ProductConsumption> <ConsumptionPattern> <Consumption> <Duration> <From>Not-Specified</From> <Till>Mon, 27 Feb :44:45 000</Till> </Duration> <Value>0</Value> <TotalRecords>1</TotalRecords> </Consumption> </ConsumptionPattern> </ProductConsumption> </BreakUpInformation> </BriefBillingInformation> Detailed Billing <emsresponse> <stat>ok</stat> <!--This is an automated/formatted XML output for the queried ISV aggregation information.--> <DetailedBillingInformation> <ProductInformation> <ProductName>Post</ProductName> <ProductVersion>1</ProductVersion> <ContractID>0134cdc6-fb1f-4494-aa8f-c ddf0</ContractID> <TenantIdentifier>1</TenantIdentifier> </ProductInformation> <BreakUpInformation> <FeatureConsumption> <FeatureIdentifier>2</FeatureIdentifier> <FeatureName>Post_1</FeatureName> <ConsumptionPattern> <Consumption> <Duration> <From>Mon, 18 Nov :11:25 000</From> <Till>Mon, 18 Nov :41:25 000</Till> </Duration>

169 3.6. Usage Information 163 <Value> </Value> <TotalRecords>1</TotalRecords> </Consumption> <Consumption> <Duration> <From>Mon, 18 Nov :09:12 000</From> <Till>Mon, 18 Nov :41:25 000</Till> </Duration> <Value> </Value> <TotalRecords>1</TotalRecords> </Consumption> </ConsumptionPattern> </FeatureConsumption> </BreakUpInformation> </DetailedBillingInformation> </emsresponse> Itemized Billing <emsresponse> <stat>ok</stat> <!--This is an automated/formatted XML output for the queried ISV aggregation information.--> <ItemizedBillingInformation> <ProductInformation> <ProductName>Post</ProductName> <ProductVersion>1</ProductVersion> <ContractID>0134cdc6-fb1f-4494-aa8f-c ddf0</ContractID> <TenantIdentifier>1</TenantIdentifier> </ProductInformation> <BreakUpInformation> <FeatureConsumption> <FeatureIdentifier>2</FeatureIdentifier> <FieldMajor>1</FieldMajor> <FeatureName>Post_1</FeatureName> <CustomerConsumption> <CustomerRefID>hcl</CustomerRefID> <IdentityConsumption> <IdentityName>c1</IdentityName> <ConsumptionPattern> <Consumption> <Duration> <From>Mon, 18 Nov :11:25 000</From> <Till>Mon, 18 Nov :41:25 000</Till> </Duration> <Value> </Value> <TotalRecords>1</TotalRecords> </Consumption> </ConsumptionPattern> </IdentityConsumption> <IdentityConsumption> <IdentityName>null</IdentityName> <ConsumptionPattern> <Consumption> <Duration> <From>Mon, 18 Nov :09:12 000</From> <Till>Mon, 18 Nov :41:25 000</Till> </Duration>

170 164 Chapter 3: Web Service Interfaces <Value> </Value> <TotalRecords>1</TotalRecords> </Consumption> </ConsumptionPattern> </IdentityConsumption> </CustomerConsumption> </FeatureConsumption> </BreakUpInformation> </ItemizedBillingInformation> </emsresponse> See Also: Output Format for Failure Understanding Billing Response The following table lists the meaning of tags used in the billing response: Tag ProductName ProductVersion ContractID TenantIdentifier Duration Value TotalRecords Product name Product version Entitlement ID Unique identifier assigned to an ISV Bill duration Total feature usage count (sum of all sessions usage), in <From> and <Till> time span. Number of sessions FeatureIdentifier Feature ID FeatureName FieldMajor Unique name of the feature Specifies if the feature is time-based or count-based. 1 : Time-based 2: Count-based CustomerRefID IdentityName Customer reference ID User ID Error Codes Error Code 100 Invalid request parameter. 101 Not authorized to use this product. 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, and granularity.]

171 3.6. Usage Information 165 Error Code 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, and granularity.] 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. 132 The URL address does not exist. 617 Start date cannot be greater than end date 1015 Invalid bill type preference. Valid values are 1(Brief bill), 2(Detail bill),3(itemized bill) Data Unavailable 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 View Concurrent Sessions Used to view concurrent sessions. This Web service can be used only for the line items having concurrent license model. Default Protocol Method Type URI HTTPS GET retrievecurrentsessions.xml Post Parameters Parameter entid Identifier of the entitlement. 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. Valid Values Optional Integer No productname Name of the product. String No productversion Version of the product. String No Sample Code import java.io.ioexception; import java.net.urldecoder;

172 166 Chapter 3: Web Service Interfaces 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 retrievecurrentsessions.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpGet get = new HttpGet (" query = new StringBuffer(); setparameter("entid", ""); setparameter("productversion", ""); setparameter("productname", ""); 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 <emsresponse> <stat>ok</stat> <total>1</total> <featuresdetail> <featuredetail> <featurename>f5</featurename> <maxlimit>200</maxlimit> <consumed>5</consumed> <available>195</available> <currentsessions> <currentsession> <logintime> :53:07</loginTime> <user>f5_i5</user> </currentsession>

173 3.6. Usage Information 167 </currentsessions> </featuredetail> </featuresdetail> </emsresponse> See Also: Output Format for Failure Error Codes Error Code 101 Not authorized to use this product. 112 The input string is not valid. 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, and granularity.] 128 You should log on first. 132 The URL address does not exist. 302 No product exists for given Name and Version. 621 Entitlement does not exist. Retry with a correct ID. 658 Entitlement is not in complete state, please contact Administrator Not supported for On-Premise entitlement 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 Retrieve Current Usage Count Retrieves total usage and actual consumption of features having prepaid license model. Default Protocol Method Type URI HTTPS GET retrievecurrentusagecount.xml Query Parameters Parameter entid Identifier of the entitlement. Note: The entid is the handle returned by the createentitlement.xml web service. You can use the Valid Values Optional Integer No

174 168 Chapter 3: Web Service Interfaces Parameter searchentitlements.xml web service to retrieve entid for an entitlement. Valid Values Optional productname Name of the product. String No productversion Version of the product. String No 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 retrievecurrentusagecount.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpGet get = new HttpGet (" query = new StringBuffer(); setparameter("entid", "1"); setparameter("productversion", "1"); setparameter("productname", "mix3"); 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 + "&");

175 3.6. Usage Information 169 Sample Response <?xml version="1.0" encoding="utf-8" standalone="yes"?> <emsresponse> <stat>ok</stat> <currentusagecounts> <currentusagecount> <featurename>feat_prepaid</featurename> <totalcount>100</totalcount> <usagecount>3</usagecount> </currentusagecount> </currentusagecounts> </emsresponse> See Also: Output Format for Failure Error Codes Error Code 101 Not authorized to use this product. 112 The input string is not valid. 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, and granularity.] 128 You should log on first. 132 The URL address does not exist. 302 No product exists for given Name and Version. 621 Entitlement does not exist. Retry with a correct ID. 658 Entitlement is not in complete state, please contact administrator No PrePaid license model found associated with the product {ProductName Not supported for On-Premise entitlement 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 Retrieve Peak Capacity This Web service reports maximum capacity of a 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 Runtime, as an optional parameter of the login API.

176 170 Chapter 3: Web Service Interfaces Default Protocol Method Type URI HTTPS GET retrievepeakcapacity.xml This Web service can be used for entitlements in complete stage only. To learn more about capacity and peak capacity, refer to EMS User's Guide. Query Parameters Parameter Valid Values customerid Customer for whom you want to determine peak capacity. Integer No entid ftrids 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. List of unique record IDs of features (as stored in EMS database), separated by commas Integer String 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 (yyyymm-dd) Optional Yes Yes No enddate End date of the duration for which the report is required String (yyyymm-dd) granularity Granularity of time interval, in hours, at which pack capacity is to be reported. Its value can range from 1 to 24 hours. Integer > 0 No No 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 customerid Only customerid and selected ftrids customerid and featurenames customerid and entid customerid, entid, and ftrids customerid, entid, and featurenames Output Report for all features across all entitlements for a customer. Report for selected features across all entitlement for a customer. Report for all features in an entitlement. Report for selected features in an entitlement.

177 3.6. Usage Information 171 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(" query = new StringBuffer(); setparameter("startdate", " "); setparameter("customerid", "1"); setparameter("entid", ""); setparameter("granularity", "2"); setparameter("enddate", " "); setparameter("featurenames", ""); setparameter("ftrids", ""); 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.

178 172 Chapter 3: Web Service Interfaces 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: : : : : : : 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 Indicates no capacity specified This equals The logout at 07:59 is not considered. To calculate maximum capacity utilized during a time interval, logouts are ignored No capacity recorded between 8-9. So the peak capacity during this interval is actual capacity until 09:00, that is ( ) till 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

179 3.6. Usage Information 173 Time Slice (granularity is 1 hour) Peak Capacity Remarks 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: <?xml version="1.0" encoding="utf-8"?> <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> <stat>ok</stat> </emsresponse> In the above response, peak capacity 0 depicts no load on the feature. 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:

180 174 Chapter 3: Web Service Interfaces 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 100 Invalid request parameter. 101 Not authorized to use this product. 102 Invalid data entered 107 An internal error occurred! Please report the error to System administrator. 118 {field should be of datatype Integer. [Note: This error code is applicable for the fields - License modelid, entid, ftrid, customerid, lmid, templatetype, lineitemid, CustomerId, stationcount,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, and granularity.]

181 3.6. Usage Information 175 Error Code 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, and granularity.] 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 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 Error in retrieving capacity information. Please contact the system administrator for further assistance Invalid capacity value.capacity value between is allowed.

182 176 Chapter 3: Web Service Interfaces 3.7. Managing Customers and Contacts This section lists the Web services provided for managing customers and contacts. Following Web Services are available: Method URI POST createcustomer.xml Create Customer POST createcontact.xml Create Contact GET searchcustomers.xml Search Customers GET getcustomerbyid.xml Retrieve Customer Details by ID GET getcustomerbycustomername.xml Retrieve Customer Details by Name GET getcustomerbycustomerrefid.xml Retrieve Customer by Customer Ref ID GET isduplicatecustomername.xml Check Duplicate Customer Names GET getcustomerrefidbycustomername.xml Retrieve Customer Reference ID by Customer Name POST deletecustomerbyid.xml Delete Customer GET timezonelist.xml Retrieve Time Zone List Create Customer Create a customer with the given parameters. Default Protocol Method Type URI HTTPS POST createcustomer.xml Post Parameters Parameter Valid Values customername Specify the customer name. String No isenabled customerrefid Specify if the customer is to be enabled. Valid values are True or False. The unique reference ID of the customer. You can enter it manually. If left blank, this is generated by system automatically. Boolean String refid Reference ID. String Yes description of the customer. String Yes timezoneid ID of the time zone in which the customer belongs. This ID is retrieved from the output of timezonelist.xml Web service. Integer (0 to Optional No No Yes

183 3.7. Managing Customers and Contacts 177 Parameter Valid Values Optional In absence of the timezoneid parameter, the GMT time zone is set for a customer. 100) Sample Code import java.io.ioexception; import org.apache.http.params.httpparams; public class EMSSample { private static DefaultHttpClient httpclient = new DefaultHttpClient(); private static Principal principal = null; public static String createcustomer.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpPost post = new HttpPost (" List<NameValuePair> nvps = new ArrayList<NameValuePair>(); nvps.add(new BasicNameValuePair("customerName", "sample")); nvps.add(new BasicNameValuePair("customerRefId", "sample1")); nvps.add(new BasicNameValuePair("description", "samplecust")); nvps.add(new BasicNameValuePair("refId", "ref-1")); nvps.add(new BasicNameValuePair("isEnabled", "true")); nvps.add(new BasicNameValuePair("timeZoneId", "38")); post.setentity(new UrlEncodedFormEntity(nvps, HTTP.UTF_8)); HttpResponse response = httpclient.execute(post, 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); Sample Response <?xml version="1.0" encoding="utf-8"?> <EMSResponse> <customerid>5</customerid> <stat>ok</stat> </EMSResponse>e>

184 178 Chapter 3: Web Service Interfaces See Also: Output Format for Failure Error Codes Error Code 100 Invalid request parameter. 101 Not authorized to use this product. 107 An internal error occurred! Please report the error to System administrator. 113 Specify a valid Boolean value for {field. Valid values are true or false. [Note: This error code is applicable for the fields - fetchcompleteeid, loginallowed, isenabled, and optional.]. 118 {field should be of datatype Integer. [Note: This error code is applicable for the fields - License modelid, entid, ftrid, customerid, lmid, templatetype, lineitemid, CustomerId, stationcount,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, 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, and granularity.] 132 The URL address does not exist. 531 Customer CRMId {actual Value already exists. Try again with a different CRMId 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 Invalid TimeZone Id provided Id Create Contact Create a contact with the given parameters. Default Protocol Method Type URI HTTPS POST createcontact.xml Post Parameters Parameter Valid Values id Contact ID String No Optional

185 3.7. Managing Customers and Contacts 179 Parameter Valid Values contactname Contact name String Yes contactnumber Contact number String Yes contactpassword Login password String Yes loginallowed customerid Set to one of the following to specify if login is required for the contact: True: Login is required. False: Login is not required. Default Value: True The unique record ID of the customer in EMS database. Boolean Integer shipaddr Shipping address String Yes shipaddrcity Shipping address - city String Yes shipaddrcountry Shipping address - country String Yes shipaddrstate Shipping address - state String Yes shipaddrzip Shipping address - zip String Yes billaddr Billing address - billing address String Yes billaddrcity Billing address - city String Yes billaddrcountry Billing address - country String Yes billaddrstate Billing address - state String Yes billaddrzip Billing address - zip String Yes refid1 Information that uniquely identifies the contact in a different ERP system. String refid2 A second unique reference ID, similar to Ref ID 1. String Yes Sample Code Optional Yes Yes Yes import java.io.ioexception; import org.apache.http.params.httpparams; public class EMSSample { private static DefaultHttpClient httpclient = new DefaultHttpClient(); private static Principal principal = null; public static String createcontact.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext();

186 180 Chapter 3: Web Service Interfaces context.setattribute(clientcontext.user_token, principal); HttpPost post = new HttpPost(" List<NameValuePair> nvps = new ArrayList<NameValuePair>(); nvps.add(new BasicNameValuePair("billAddr", "")); nvps.add(new BasicNameValuePair("contactNumber", "")); nvps.add(new BasicNameValuePair("billAddrCity", "")); nvps.add(new BasicNameValuePair("shipAddrCountry", "")); nvps.add(new BasicNameValuePair("shipAddrCity", "")); nvps.add(new BasicNameValuePair("billAddrZip", "")); nvps.add(new BasicNameValuePair("shipAddr", "")); nvps.add(new BasicNameValuePair("billAddrState", "")); nvps.add(new BasicNameValuePair("loginAllowed", "")); nvps.add(new BasicNameValuePair("shipAddrState", "")); nvps.add(new BasicNameValuePair("contactPassword", "")); nvps.add(new BasicNameValuePair("refId2", "")); nvps.add(new BasicNameValuePair(" Id", "")); nvps.add(new BasicNameValuePair("billAddrCountry", "")); nvps.add(new BasicNameValuePair("customerId", "")); nvps.add(new BasicNameValuePair("refId1", "")); nvps.add(new BasicNameValuePair("contactName", "")); nvps.add(new BasicNameValuePair("shipAddrZip", "")); post.setentity(new UrlEncodedFormEntity(nvps, HTTP.UTF_8)); HttpResponse response = httpclient.execute(post, 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); Sample Response <?xml version="1.0" encoding="utf-8"?> <EMSResponse> <contactid>10</contactid> <stat>ok</stat> </EMSResponse> See Also: Output Format for Failure Error Codes Error Code 100 Invalid request parameter. 101 Not authorized to use this product. 107 An internal error occurred! Please report the error to System administrator. 113 Specify a valid Boolean value for {field. Valid values are true or false. [Note: This

187 3.7. Managing Customers and Contacts 181 Error Code error code is applicable for the fields - fetchcompleteeid, loginallowed, isenabled, and optional.]. 115 Length of {field is {actual value. It cannot be more Than {max value. [Note: This error code is applicable for the fields - billaddr, billaddrcity, billaddrcountry, billaddrstate, billaddrzip, shipaddr, shipaddrcity, shipaddrcountry, shipaddrstate, shipaddrzip, refid1, refid2, contactpassword, description, and default value.] 117 Regular Expression validation failed for contact id 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, 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, and granularity.] 132 The URL address does not exist. 519 Customer not found for the given customerid. 529 Given ID {actual Value is not unique. Please try again with different ID 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 Search Customers Search customers/view all customers for the given query parameters. Default Protocol Method Type URI HTTPS GET searchcustomers.xml Query Parameters Parameter Valid Values Optional customername Specify the customer name. String Yes customerrefid The unique reference ID of the customer. String refid Reference ID. String Yes pageindex The starting page number. Integer (>0) Yes pagesize The number of customers retrieved by one request. Integer (>0) Default Value: 200 Yes Yes

188 182 Chapter 3: Web Service Interfaces Parameter Valid Values Optional sortcol Sort against the column. String (crmid, cstmrid, customername, refid, status) Default Value: cstmrid sortorder The order to sort. String (asc, desc) lastmodified Creation or Modification time stamp. Default Value:desc Long Yes Yes Yes If none of the parameters is specified, all the customer records are retrieved. 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 searchcustomers.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpGet get = new HttpGet(" query = new StringBuffer(); setparameter("customername", "ashwini"); setparameter("lastmodified", ""); setparameter("customerrefid", ""); setparameter("sortorder", ""); setparameter("pagesize", ""); setparameter("refid", ""); setparameter("sortcol", ""); setparameter("pageindex", ""); 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) {

189 3.7. Managing Customers and Contacts 183 if (query.tostring().equals("")) { query.append("?" + key + "=" + value + "&"); else { query.append(key + "=" + value + "&"); Sample Response <emsresponse> <customers> <customer> <creationtime> </creationtime> <customerid>1</customerid> <customername>alaska</customername> <customerrefid>alaska</customerrefid> <desc /> <enabled>true</enabled> <modificationtime> </modificationtime> <refid /> <timezone>(gmt-09:00) Alaska</timezone> </customer> </customers> <stat>ok</stat> <total>1</total> </emsresponse> See Also: Output Format for Failure Error Codes Error Code 100 Invalid request parameter. 101 Not authorized to use this product. 102 Invalid data entered 107 An internal error occurred! Please report the error to System administrator. 109 "Invalid sortorder.valid values are 'asc' or 'desc'. 110 Invalid pageindex. Valid value can be any positive integer greater than Invalid pagesize.valid value can be any positive integer greater than Invalid sortcolumn. Valid values are startdate,enddate,state,totalcredit,status,contact id, customername,id. 128 You should log on first. 132 The URL address does not exist {field should be of datatype long. [Note: This error code is applicable for the field - lastmodified.]

190 184 Chapter 3: Web Service Interfaces Error Code 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 Retrieve Customer Details by ID Retrieve details for a customer using customer ID. Please note that customerid and customerrefid are different. customerid: It is an auto-generated record ID that identifies a customer in EMS database. customerrefid: It is the unique identification code provided by software provider for a customer. It is used in license enforcement. Default Protocol Method Type URI HTTPS GET getcustomerbyid.xml Query Parameters 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 getcustomerbyid.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpGet get = new HttpGet(" query = new StringBuffer(); setparameter("customerid", ""); 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();

191 3.7. Managing Customers and Contacts 185 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 <emsresponse> <customer> <contacts> <contact> <admin>false</admin> <contact >[email protected]</contact > <contactid>1</contactid> <contactname>alaska</contactname> <contactnumber /> <creationtime> </creationtime> <customername>alaska</customername> <modificationtime> </modificationtime> <status>true</status> </contact> </contacts> <creationtime> </creationtime> <customerid>1</customerid> <customername>alaska</customername> <customerrefid>alaska</customerrefid> <desc /> <enabled>true</enabled> <modificationtime> </modificationtime> <refid /> <timezone>(gmt-09:00) Alaska</timezone> </customer> <stat>ok</stat> </emsresponse> See Also: Output Format for Failure Error Codes Error Code 100 Invalid request parameter. 101 Not authorized to use this product. 107 An internal error occurred! Please report the error to System administrator.

192 186 Chapter 3: Web Service Interfaces Error Code 118 {field should be of datatype Integer. [Note: This error code is applicable for the fields - License modelid, entid, ftrid, customerid, lmid, templatetype, lineitemid, CustomerId, stationcount,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, 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, and granularity.] 128 You should log on first. 132 The URL address does not exist. 512 The customer does not exist 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 Retrieve Customer Details by Name Retrieve details of a customer using exact customer name. Default Protocol Method Type URI HTTPS GET getcustomerbycustomername.xml Query Parameters Parameter Valid Values Optional customername Specify the customer name. String No 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;

193 3.7. Managing Customers and Contacts 187 public static String getcustomerbycustomername.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpGet get = new HttpGet (" query = new StringBuffer(); setparameter("customername", ""); 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 <emsresponse> <customers> <customer> <contacts> <contact> <admin>false</admin> <contact >[email protected]</contact > <contactid>1</contactid> <contactname>alaska</contactname> <contactnumber /> <creationtime> </creationtime> <customername>alaska</customername> <modificationtime> </modificationtime> <status>true</status> </contact> </contacts> <creationtime> </creationtime> <customerid>1</customerid> <customername>alaska</customername> <customerrefid>alaska</customerrefid> <desc /> <enabled>true</enabled> <modificationtime> </modificationtime> <refid /> <timezone>(gmt-09:00) Alaska</timezone> </customer>

194 188 Chapter 3: Web Service Interfaces </customers> <stat>ok</stat> <total>1</total> </emsresponse> See Also: Output Format for Failure Error Codes Error Code 100 Invalid request parameter. 101 Not authorized to use this product. 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, and granularity.] 128 You should log on first. 132 The URL address does not exist. 512 The customer does not exist 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 Retrieve Customer by Customer Ref ID Retrieves customer details by using customer reference ID. Please note that customerid and customerrefid are different. customerid: It is an auto-generated record ID that identifies a customer in EMS database. customerrefid: It is the unique identification code provided by software provider for a customer. It is used in license enforcement. Default Protocol Method Type URI HTTPS GET getcustomerbycustomerrefid.xml Query Parameters Parameter Valid Values Optional customerrefid The unique reference ID of the customer. String No

195 3.7. Managing Customers and Contacts 189 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 getcustomerbycustomerrefid.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpGet get = new HttpGet(" query = new StringBuffer(); setparameter("customerrefid", "123"); 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 <emsresponse> <customer> <contacts> <contact> <admin>false</admin> <contact >[email protected]</contact > <contactid>14</contactid> <contactname /> <contactnumber /> <creationtime> </creationtime>

196 190 Chapter 3: Web Service Interfaces <customername>retail</customername> <modificationtime> </modificationtime> <status>true</status> </contact> </contacts> <creationtime> </creationtime> <customerid>15</customerid> <customername>retail</customername> <customerrefid>retail001</customerrefid> <desc /> <enabled>true</enabled> <modificationtime> </modificationtime> <refid /> <timezone>(gmt) Coordinated Universal Time</timezone> </customer> <stat>ok</stat> </emsresponse> See Also: Output Format for Failure Error Codes Error Code 100 Invalid request parameter. 101 Not authorized to use this product. 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, and granularity.] 128 You should log on first. 512 The customer does not exist 1081 Invalid Web service version provided Check Duplicate Customer Names Checks if a customer name is duplicate or not. Default Protocol Method Type URI HTTPS GET isduplicatecustomername.xml GET Parameters Parameter Valid Values Optional customername Customer name. String No

197 3.7. Managing Customers and Contacts 191 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 isduplicatecustomername.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpGet get = new HttpGet(" query = new StringBuffer(); setparameter("customername", "ashwini"); 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 <emsresponse> <exist>true</exist> <stat>ok</stat> </emsresponse> See Also: Output Format for Failure

198 192 Chapter 3: Web Service Interfaces Error Codes Error Code 101 Not authorized to use this product. 107 An internal error occurred! Please report the error to System administrator 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 Retrieve Customer Reference ID by Customer Name Retrieves the customer reference ID for the given customer name. Default Protocol Method Type URI HTTPS GET getcustomerrefidbycustomername.xml GET Parameters Parameter Valid Values Optional customername Customer name. String No 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 getcustomerrefidbycustomername.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpGet get = new HttpGet (" query = new StringBuffer(); setparameter("customername", "ashwini"); get.seturi(new URI(URLDecoder.decode(get.getURI() + query.tostring(),"utf-8"))); HttpResponse response = httpclient.execute(get, context);

199 3.7. Managing Customers and Contacts 193 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 <emsresponse> <customers> <customer> <cstmrcrmid>smplcustretail13264</cstmrcrmid> <customerid>7</customerid> </customer> </customers> <stat>ok</stat> <total>1</total> </emsresponse> See Also: Output Format for Failure Error Codes Error Code 101 Not authorized to use this product. 107 An internal error occurred! Please report the error to System administrator. 512 The customer does not exist 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 Delete Customer Delete a customer using customer ID.

200 194 Chapter 3: Web Service Interfaces Default Protocol Method Type URI HTTPS POST deletecustomerbyid.xml Post Parameters Parameter Valid Values Optional customerid The unique record ID of the customer in EMS database. Integer No Sample Code import java.io.ioexception; import org.apache.http.params.httpparams; public class EMSSample { private static DefaultHttpClient httpclient = new DefaultHttpClient(); private static Principal principal = null; public static String deletecustomerbyid.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpPost post = new HttpPost (" List<NameValuePair> nvps = new ArrayList<NameValuePair>(); nvps.add(new BasicNameValuePair("customerId", "")); post.setentity(new UrlEncodedFormEntity(nvps, HTTP.UTF_8)); HttpResponse response = httpclient.execute(post, 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); Sample Response <?xml version="1.0" encoding="utf-8"?> <emsresponse> <stat>ok</stat> </emsresponse> See Also: Output Format for Failure

201 3.7. Managing Customers and Contacts 195 Error Codes Error Code 100 Invalid request parameter. 101 Not authorized to use this product. 107 An internal error occurred! Please report the error to System administrator. 118 {field should be of datatype Integer. [Note: This error code is applicable for the fields - License modelid, entid, ftrid, customerid, lmid, templatetype, lineitemid, CustomerId, stationcount,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, 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, and granularity.] 128 You should log on first. 132 The URL address does not exist. 519 Customer not found for the given customerid. 694 Customer cannot be deleted as entitlement exists for this Customer 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 Retrieve Time Zone List Retrieves the list of supported time zones. The output contains a unique ID corresponding to each time zone. The output of this Web service can be used to select the time zone and pass the corresponding ID in createcustomer.xml Web service. Default Protocol Method Type URI HTTPS GET timezonelist.xml Post Parameters No parameters. Sample Code import java.io.ioexception; import java.net.urldecoder;

202 196 Chapter 3: Web Service Interfaces 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 timezonelist.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpGet get = new HttpGet(" query = new StringBuffer(); 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 <emsresponse> <timezones> <timezone> <id>1</id> <desc>(gmt-12:00) International Date Line West</desc> </timezone> <timezone> <id>2</id> <desc>(gmt-11:00) Coordinated Universal Time-11</desc> </timezone> <timezone> <id>3</id> <desc>(gmt-11:00) Samoa</desc> </timezone> <timezone> <id>4</id> <desc>(gmt-10:00) Hawaii</desc>

203 </timezone> <timezone> <id>5</id> <desc>(gmt-09:00) Alaska</desc> </timezone> <timezone> <id>6</id> <desc>(gmt-08:00) Baja California</desc> </timezone> <timezone> <id>7</id> <desc>(gmt-08:00) Pacific Time (US & Canada)</desc> </timezone> <timezone> <id>8</id> <desc>(gmt-07:00) Chihuahua, La Paz, Mazatlan - New</desc> </timezone> <timezone> <id>9</id> <desc>(gmt-07:00) Arizona</desc> </timezone> <timezone> <id>10</id> <desc>(gmt-07:00) Mountain Time (US & Canada)</desc> </timezone> <timezone> <id>11</id> <desc>(gmt-07:00) Chihuahua, La Paz, Mazatlan - Old</desc> </timezone> <timezone> <id>12</id> <desc>(gmt-06:00) Central Time (US & Canada)</desc> </timezone> <timezone> <id>13</id> <desc>(gmt-06:00) Central America</desc> </timezone> <timezone> <id>14</id> <desc>(gmt-06:00) Guadalajara, Mexico City, Monterrey - New</desc> </timezone> <timezone> <id>15</id> <desc>(gmt-06:00) Saskatchewan</desc> </timezone> <timezone> <id>16</id> <desc>(gmt-06:00) Guadalajara, Mexico City, Monterrey - Old</desc> </timezone> <timezone> <id>17</id> <desc>(gmt-05:00) Bogota, Lima, Quito</desc> </timezone> <timezone> <id>18</id> <desc>(gmt-05:00) Eastern Time (US & Canada)</desc> </timezone> <timezone> 3.7. Managing Customers and Contacts 197

204 198 Chapter 3: Web Service Interfaces <id>19</id> <desc>(gmt-05:00) Indiana (East)</desc> </timezone> <timezone> <id>20</id> <desc>(gmt-04:30) Caracas</desc> </timezone> <timezone> <id>21</id> <desc>(gmt-04:00) Atlantic Time (Canada)</desc> </timezone> <timezone> <id>22</id> <desc>(gmt-04:00) Asuncion</desc> </timezone> <timezone> <id>23</id> <desc>(gmt-04:00) Cuiaba</desc> </timezone> <timezone> <id>24</id> <desc>(gmt-04:00) Santiago</desc> </timezone> <timezone> <id>25</id> <desc>(gmt-04:00) Georgetown, La Paz, Manaus, San Juan</desc> </timezone> <timezone> <id>26</id> <desc>(gmt-03:30) Newfoundland</desc> </timezone> <timezone> <id>27</id> <desc>(gmt-03:00) Buenos Aires</desc> </timezone> <timezone> <id>28</id> <desc>(gmt-03:00) Brasilia</desc> </timezone> <timezone> <id>29</id> <desc>(gmt-03:00) Cayenne, Fortaleza</desc> </timezone> <timezone> <id>30</id> <desc>(gmt-03:00) Montevideo</desc> </timezone> <timezone> <id>31</id> <desc>(gmt-03:00) Greenland</desc> </timezone> <timezone> <id>32</id> <desc>(gmt-02:00) Coordinated Universal Time-02</desc> </timezone> <timezone> <id>33</id> <desc>(gmt-02:00) Mid-Atlantic</desc> </timezone> <timezone>

205 <id>34</id> <desc>(gmt-01:00) Azores</desc> </timezone> <timezone> <id>35</id> <desc>(gmt-01:00) Cape Verde Is.</desc> </timezone> <timezone> <id>36</id> <desc>(gmt) Casablanca</desc> </timezone> <timezone> <id>37</id> <desc>(gmt) Monrovia, Reykjavik</desc> </timezone> <timezone> <id>38</id> <desc>(gmt) Coordinated Universal Time</desc> </timezone> <timezone> <id>39</id> <desc>(gmt) Greenwich Mean Time, : Dublin, Edinburgh, Lisbon, London</desc> </timezone> <timezone> <id>40</id> <desc>(gmt+01:00) Sarajevo, Skopje, Warsaw, Zagreb</desc> </timezone> <timezone> <id>41</id> <desc>(gmt+01:00) West Central Africa</desc> </timezone> <timezone> <id>42</id> <desc>(gmt+01:00) Belgrade, Bratislava, Budapest, Ljubljana, Prague</desc> </timezone> <timezone> <id>43</id> <desc>(gmt+01:00) Brussels, Copenhagen, Madrid, Paris</desc> </timezone> <timezone> <id>44</id> <desc>(gmt+01:00) Amsterdam, Berlin, Bern, Rome, Stockholm, Vienna</desc> </timezone> <timezone> <id>45</id> <desc>(gmt+02:00) Harare, Pretoria</desc> </timezone> <timezone> <id>46</id> <desc>(gmt+02:00) Damascus</desc> </timezone> <timezone> <id>47</id> <desc>(gmt+02:00) Helsinki, Kyiv, Riga, Sofia, Tallinn, Vilnius</desc> </timezone> <timezone> 3.7. Managing Customers and Contacts 199

206 200 Chapter 3: Web Service Interfaces <id>48</id> <desc>(gmt+02:00) Windhoek</desc> </timezone> <timezone> <id>49</id> <desc>(gmt+02:00) Minsk</desc> </timezone> <timezone> <id>50</id> <desc>(gmt+02:00) Athens, Bucharest, Istanbul</desc> </timezone> <timezone> <id>51</id> <desc>(gmt+02:00) Amman</desc> </timezone> <timezone> <id>52</id> <desc>(gmt+02:00) Beirut</desc> </timezone> <timezone> <id>53</id> <desc>(gmt+02:00) Jerusalem</desc> </timezone> <timezone> <id>54</id> <desc>(gmt+02:00) Cairo</desc> </timezone> <timezone> <id>55</id> <desc>(gmt+03:00) Kuwait, Riyadh</desc> </timezone> <timezone> <id>56</id> <desc>(gmt+03:00) Moscow, St. Petersburg, Volgograd</desc> </timezone> <timezone> <id>57</id> <desc>(gmt+03:00) Baghdad</desc> </timezone> <timezone> <id>58</id> <desc>(gmt+03:00) Nairobi</desc> </timezone> <timezone> <id>59</id> <desc>(gmt+03:30) Tehran</desc> </timezone> <timezone> <id>60</id> <desc>(gmt+04:00) Caucasus Standard Time</desc> </timezone> <timezone> <id>61</id> <desc>(gmt+04:00) Port Louis</desc> </timezone> <timezone> <id>62</id> <desc>(gmt+04:00) Tbilisi</desc> </timezone> <timezone>

207 <id>63</id> <desc>(gmt+04:00) Baku</desc> </timezone> <timezone> <id>64</id> <desc>(gmt+04:00) Yerevan</desc> </timezone> <timezone> <id>65</id> <desc>(gmt+04:00) Abu Dhabi, Muscat</desc> </timezone> <timezone> <id>66</id> <desc>(gmt+04:30) Kabul</desc> </timezone> <timezone> <id>67</id> <desc>(gmt+05:00) Ekaterinburg</desc> </timezone> <timezone> <id>68</id> <desc>(gmt+05:00) Islamabad, Karachi</desc> </timezone> <timezone> <id>69</id> <desc>(gmt+05:00) Tashkent</desc> </timezone> <timezone> <id>70</id> <desc>(gmt+05:30) Chennai, Kolkata, Mumbai, New Delhi</desc> </timezone> <timezone> <id>71</id> <desc>(gmt+05:30) Sri Jayawardenepura</desc> </timezone> <timezone> <id>72</id> <desc>(gmt+05:45) Kathmandu</desc> </timezone> <timezone> <id>73</id> <desc>(gmt+06:00) Dhaka</desc> </timezone> <timezone> <id>74</id> <desc>(gmt+06:00) Novosibirsk</desc> </timezone> <timezone> <id>75</id> <desc>(gmt+06:00) Astana</desc> </timezone> <timezone> <id>76</id> <desc>(gmt+06:30) Yangon (Rangoon)</desc> </timezone> <timezone> <id>77</id> <desc>(gmt+07:00) Krasnoyarsk</desc> </timezone> <timezone> 3.7. Managing Customers and Contacts 201

208 202 Chapter 3: Web Service Interfaces <id>78</id> <desc>(gmt+07:00) Bangkok, Hanoi, Jakarta</desc> </timezone> <timezone> <id>79</id> <desc>(gmt+08:00) Ulaanbaatar</desc> </timezone> <timezone> <id>80</id> <desc>(gmt+08:00) Perth</desc> </timezone> <timezone> <id>81</id> <desc>(gmt+08:00) Taipei</desc> </timezone> <timezone> <id>82</id> <desc>(gmt+08:00) Kuala Lumpur, Singapore</desc> </timezone> <timezone> <id>83</id> <desc>(gmt+08:00) Beijing, Chongqing, Hong Kong, Urumqi</desc> </timezone> <timezone> <id>84</id> <desc>(gmt+08:00) Irkutsk</desc> </timezone> <timezone> <id>85</id> <desc>(gmt+09:00) Seoul</desc> </timezone> <timezone> <id>86</id> <desc>(gmt+09:00) Osaka, Sapporo, Tokyo</desc> </timezone> <timezone> <id>87</id> <desc>(gmt+09:00) Yakutsk</desc> </timezone> <timezone> <id>88</id> <desc>(gmt+09:30) Darwin</desc> </timezone> <timezone> <id>89</id> <desc>(gmt+09:30) Adelaide</desc> </timezone> <timezone> <id>90</id> <desc>(gmt+10:00) Hobart</desc> </timezone> <timezone> <id>91</id> <desc>(gmt+10:00) Vladivostok</desc> </timezone> <timezone> <id>92</id> <desc>(gmt+10:00) Guam, Port Moresby</desc> </timezone>

209 3.7. Managing Customers and Contacts 203 <timezone> <id>93</id> <desc>(gmt+10:00) Brisbane</desc> </timezone> <timezone> <id>94</id> <desc>(gmt+10:00) Canberra, Melbourne, Sydney</desc> </timezone> <timezone> <id>95</id> <desc>(gmt+11:00) Magadan, Solomon Is., New Caledonia</desc> </timezone> <timezone> <id>96</id> <desc>(gmt+12:00) Fiji</desc> </timezone> <timezone> <id>97</id> <desc>(gmt+12:00) Petropavlovsk-Kamchatsky - Old</desc> </timezone> <timezone> <id>98</id> <desc>(gmt+12:00) Auckland, Wellington</desc> </timezone> <timezone> <id>99</id> <desc>(gmt+12:00) Coordinated Universal Time,+12</desc> </timezone> <timezone> <id>100</id> <desc>(gmt+13:00) Nukualofa</desc> </timezone> </timezones> <total>100</total> </emsresponse> See Also: Output Format for Failure Error Codes Error Code 100 Invalid request parameter. 101 Not authorized to use this product. 107 An internal error occurred! Please report the error to System administrator. 128 You should log on first. 132 The URL address does not exist 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.

210 204 Chapter 3: Web Service Interfaces 3.8. Custom Attributes Custom attributes allow you to create placeholders for storing additional information for an entity.you can create custom attributes for the following entities: Feature Product Customer Contact Entitlement The custom attributes defined for an entity become part of all instances of that entity, irrespective of its lifecycle stage. You can assign a default value to each custom attribute. The user can change these default values and assign new values to the attributes while creating an instance of an entity. This section includes the following Web Services: Method URI POST createtemplateattribute.xml Create Template Attribute GET getentitycustomattributes.xml Find a Custom Attribute by Template Type and Entity ID GET searchentitybycustomattribute.xml Search Entity By Custom Attribute POST updatecustomattribute.xml Update Custom Attribute POST removetemplateattribute.xml Delete Custom Attribute Create Template Attribute Create a custom attribute using the parameters provided. Default Protocol Method Type URI HTTPS POST createtemplateattribute.xml Post Parameters Parameter templatetype EMS Entity for which you want to define a custom attribute. Possible values are: 1(Feature) 2(Product) 4(Customer) Valid Values Integer Optional No

211 3.8. Custom Attributes 205 Parameter 5(Contact) 6(Entitlement) Valid Values attrname Name of the custom attribute. String No datatype Data Type of the custom attribute. Possible values are: 1(STRING) 2(DATE) 3(NUMERIC) 4(BOOLEAN) Integer defaultvalue Specifies a default value of the custom attribute. String Yes descr of the custom attribute. String Yes optional regex Indicates that the field is mandatory or optional. Valid values are True or False. Regular Expression that you want to use for validating the custom attribute values. For example, the following regular expression helps validate the Address custom attribute: Boolean String Optional No No Yes ^([a-za-z0-9\xa0-\xff_\-\.]+)@((\[[0-9]{1,3\.[0-9]{1,3\. [0-9]{1,3\.) (([a-za-z0-9\xa0-\xff\-]+\.)+))([a-za-z\xa0- \xff]{2,4 [0-9]{1,3)(\]?)$ Sample Code import java.io.ioexception; import org.apache.http.params.httpparams; public class EMSSample { private static DefaultHttpClient httpclient = new DefaultHttpClient(); private static Principal principal = null; public static String createtemplateattribute.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpPost post = new HttpPost(" List<NameValuePair> nvps = new ArrayList<NameValuePair>(); nvps.add(new BasicNameValuePair("dataType", "1")); nvps.add(new BasicNameValuePair("templateType", "1")); nvps.add(new BasicNameValuePair("optional", "true")); nvps.add(new BasicNameValuePair("attrName", "Custom"));

212 206 Chapter 3: Web Service Interfaces nvps.add(new BasicNameValuePair("defaultValue", "test")); nvps.add(new BasicNameValuePair("descr", "sample")); nvps.add(new BasicNameValuePair("regEx", "")); post.setentity(new UrlEncodedFormEntity(nvps, HTTP.UTF_8)); HttpResponse response = httpclient.execute(post, 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); Sample Response <emsresponse> <attribid>20</attribid> <stat>ok</stat> </emsresponse> See Also: Output Format for Failure Error Codes Error Code 100 Invalid request parameter. 102 Invalid data entered 107 An internal error occurred! Please report the error to System administrator. 113 Specify a valid Boolean value for {field. Valid values are true or false. [Note: This error code is applicable for the fields - fetchcompleteeid, loginallowed, isenabled, and optional.]. 115 Length of {field is {actual value. It cannot be more Than {max value. [Note: This error code is applicable for the fields - billaddr, billaddrcity, billaddrcountry, billaddrstate, billaddrzip, shipaddr, shipaddrcity, shipaddrcountry, shipaddrstate, shipaddrzip, refid1, refid2, contactpassword, description, and default value.] 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, 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, and granularity.]

213 3.8. Custom Attributes 207 Error Code 711 Invalid Template Type! 713 Invalid Boolean value {value passed. Provide a valid value(0 or 1). 714 Invalid Numeric value(x) passed. Please provide a valid value. 715 Invalid Date value(x) passed. Please provide a valid value(in yyyy-mm-dd format). 716 No data type exists for the value (value) Invalid Web service version provided 1084 No Web service version provided 1086 template attribute (x) already exists. Try again with a different name The EMS system is running on HTTPS. Please provide the correct Web service URL Find a Custom Attribute by Template Type and Entity ID Finds a custom attribute by template type and entity ID. Default Protocol Method Type URI HTTPS GET getentitycustomattributes.xml Query Parameters Parameter templatetype EMS Entity for which the custom attribute is defined. Possible values are: 1(Feature) 2(Product) 4(Customer) 5(Contact) 6(Entitlement) Valid Values Integer Optional No entityid Id of the entity for which you the custom attribute is being retrieved. Integer No 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();

214 208 Chapter 3: Web Service Interfaces private static Principal principal = null; private static StringBuffer query; public static String getentitycustomattributes.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpGet get = new HttpGet(" query = new StringBuffer(); setparameter("templatetype", "1"); setparameter("entityid", "3"); 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 <emsresponse> <entityid>1</entityid> <entityname>feature1</entityname> <stat>ok</stat> <template> <templat> <attributeid>1</attributeid> <attributename>display Name</attributename> <datatype>string</datatype> <datatypecode>1</datatypecode> <optional>true</optional> <regularexpression /> <value>sentinel Cloud</value> </templat> </template> <templatetype>feature</templatetype> </emsresponse> See Also: Output Format for Failure

215 3.8. Custom Attributes 209 Error Codes Error Code 100 Invalid request parameter. 101 Not authorized to use this product. 102 Invalid data entered 107 An internal error occurred! Please report the error to System administrator. 118 {field should be of datatype Integer. [Note: This error code is applicable for the fields - License modelid, entid, ftrid, customerid, lmid, templatetype, lineitemid, CustomerId, stationcount,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, and granularity.] 128 You should log on first. 301 Unable to find product for ID Id 309 Unable to find feature. 711 Invalid Template Type! 712 Entity not found 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 Search Entity By Custom Attribute Retrieves an entity by custom attribute and its value. Default Protocol Method Type URI HTTPS GET searchentitybycustomattribute.xml Query Parameters Parameter Valid Values Optional templatetype EMS Entity for which you want to define a custom attribute. Possible values are: Integer No 1(Feature) 2(Product) 4(Customer) 5(Contact)

216 210 Chapter 3: Web Service Interfaces Parameter 6(Entitlement) Valid Values attributename Name of the custom attribute. String No attributevalue Value of the custom attribute. String No Sample Code Optional 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 searchentitybycustomattribute.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpGet get = new HttpGet(" query = new StringBuffer(); setparameter("attributename", "custom"); setparameter("templatetype", "1"); setparameter("attributevalue", "test"); 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 + "&");

217 3.8. Custom Attributes 211 Sample Response <emsresponse> <attribute>display Name</attribute> <attributevalue>my Sample Feature Name</attributevalue> <entities> <entitie> <description>test</description> <featureid>2</featureid> <featurename>feature2</featurename> <namespaceid>1</namespaceid> <namespacename>microsoft</namespacename> </entitie> <entitie> <description>test</description> <featureid>3</featureid> <featurename>sonu</featurename> <namespaceid>1</namespaceid> <namespacename>microsoft</namespacename> </entitie> <entitie> <description>test</description> <featureid>4</featureid> <featurename>sonu11</featurename> <namespaceid>1</namespaceid> <namespacename>microsoft</namespacename> </entitie> </entities> <stat>ok</stat> <templatetype>feature</templatetype> <total>3</total> </emsresponse> See Also: Output Format for Failure Error Codes Error Code 100 Invalid request parameter. 101 Not authorized to use this product. 102 Invalid data entered 107 An internal error occurred! Please report the error to System administrator. 118 {field should be of datatype Integer. [Note: This error code is applicable for the fields - License modelid, entid, ftrid, customerid, lmid, templatetype, lineitemid, CustomerId, stationcount,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, and granularity.] 128 You should log on first.

218 212 Chapter 3: Web Service Interfaces Error Code 711 Invalid Template Type! 718 Attribute not found 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 Update Custom Attribute Updates the custom attributes of an entity.its input is the XML string returned by the getentitycustomattributes Web service. In the input XML, only the <value> tag can be modified and the remaining information is treated as read-only. If the custom attribute is created for a Boolean data type, the <value> tag can have only two values 0 or 1, where 0 = False and 1 = True. Default Protocol Method Type URI HTTPS POST updatecustomattribute.xml POST Parameters Parameter Valid Values Optional customattribute XML string returned by getentitycustomattributes String No Sample Code import java.io.ioexception; import org.apache.http.params.httpparams; public class EMSSample { private static DefaultHttpClient httpclient = new DefaultHttpClient(); private static Principal principal = null; public static String updatecustomattribute.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpPost post = new HttpPost(" List<NameValuePair> nvps = new ArrayList<NameValuePair>(); nvps.add(new BasicNameValuePair("customAttribute", "")); post.setentity(new UrlEncodedFormEntity(nvps, HTTP.UTF_8)); HttpResponse response = httpclient.execute(post, context); HttpEntity entity = response.getentity();

219 3.8. Custom Attributes 213 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); Sample Response <emsresponse> <stat>ok</stat> </emsresponse> See Also: Output Format for Failure Error Codes Error Code 100 Invalid request parameter. 101 Not authorized to use this product. 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, and granularity.] 128 You should log on first. 711 Invalid Template Type! 713 Invalid Boolean value {value passed. Provide a valid value(0 or 1). 717 Invalid entityid or custom attribute Invalid Web service version provided 1084 No Web service version provided 1086 template attribute (x) already exists. Try again with a different name No custom attribute exists for attributeid {Id The EMS system is running on HTTPS. Please provide the correct Web service URL.

220 214 Chapter 3: Web Service Interfaces Delete Custom Attribute Delete a custom attribute by its template type and attribute name. Default Protocol Method Type URI HTTPS POST removetemplateattribute.xml POST Parameters Parameter templatetype EMS Entity for which you want to delete a custom attribute. Possible values are: 1(Feature) 2(Product) 4(Customer) 5(Contact) 6(Entitlement) Valid Values Optional Integer No attributename Name of the custom attribute. String No Sample Code import java.io.ioexception; import org.apache.http.params.httpparams; public class EMSSample { private static DefaultHttpClient httpclient = new DefaultHttpClient(); private static Principal principal = null; public static String removetemplateattribute.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpPost post = new HttpPost(" List<NameValuePair> nvps = new ArrayList<NameValuePair>(); nvps.add(new BasicNameValuePair("attributeName", "F1")); nvps.add(new BasicNameValuePair("templateType", "1")); post.setentity(new UrlEncodedFormEntity(nvps, HTTP.UTF_8)); HttpResponse response = httpclient.execute(post, context); HttpEntity entity = response.getentity(); byte[] b = null; if (entity!= null) { long l = entity.getcontentlength();

221 3.9. On-premise Machine Registration 215 b = new byte[(int) l]; entity.getcontent().read(b); entity.consumecontent(); return new String(b); Sample Response <emsresponse> <stat>ok</stat> </emsresponse> See Also: Output Format for Failure Error Codes Error Code 100 Invalid request parameter. 101 Not authorized to use this product. 102 Invalid data entered 107 An internal error occurred! Please report the error to System administrator. 118 {field should be of datatype Integer. [Note: This error code is applicable for the fields - License modelid, entid, ftrid, customerid, lmid, templatetype, lineitemid, CustomerId, stationcount,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, and granularity.] 128 You should log on first. 711 Invalid Template Type! 718 Attribute not found 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 On-premise Machine Registration Machine registration is required to implement device-based licensing. It enables you to restrict the use of your application on those machines only that are registered with Cloud Connect. The

222 216 Chapter 3: Web Service Interfaces information that can be used to identify a machine is called its fingerprint. The fingerprint of the client machine needs to be obtained and registered with Cloud Connect. For information on obtaining machine fingerprint, please refer to Sentinel Cloud Run-time Guide. For machine registration, you need to use EMS Web services that are described in this section. Method URI POST addfingerprint.xml Add Fingerprint GET retrievefingerprint.xml Retrieve Fingerprint POST deletefingerprint.xml Delete Fingerprint POST addentitlementfingerprint.xml Add Entitlement Fingerprint GET retrieveentitlementfingerprint.xml Retrieve Entitlement Fingerprint POST deleteentitlementfingerprint.xml Delete Entitlement Fingerprint Add Fingerprint This Web service adds fingerprints of customer s machines to Cloud Connect database. This Web service is available only for on-premise feature level licensing. A machine for a customer is registered only if an entitlement for that customer is present in EMS in committed stage. For a customer, fingerprint value and its friendly name cannot be duplicate. Default Protocol Method Type URI HTTPS POST addfingerprint.xml Post Parameters Parameter Valid Values Optional fingerprintinfo Fingerprint XML of customer s machine. String No Input XML The input of this Web service should be properly encoded to handle special characters. <fingerprintdetails> <entitlementlist> <entitlement> <eid>ce6a c-4c19-89e0-37f9c726cec0</eid> <fingerprintlist> <fingerprint> <fingerprintfriendlyname>fingerprint1</fingerprintfriendlyname>

223 3.9. On-premise Machine Registration 217 <fingerprintvalue> <hasp_info> <host_fingerprint type="sl-adminmode" crc=" ">mxhjsspcqvwsia2aasdcjswoxteuotgzdnwq4yn7iyxkaqk+ukpyhrgdohl8iaknba1x5qguykuqkjas- Qr8IeTEsVUYY0SLCWDBxhQNIRQ==</host_fingerprint> <host_fingerprint type="sl-usermode" crc=" ">mnhjsqobgkbo1hecanog4vhjfc8mid27uf1oxthe4bgitix6rqaulazn4etcglaibhjysslgai6pajor- PHcIqHBsClCRac4pBFQcWpYszxZDAPTin6gzJWKBdgSL</host_fingerprint> </hasp_info> </fingerprintvalue> </fingerprint> <fingerprint> <fingerprintfriendlyname>fingerprint1</fingerprintfriendlyname> <fingerprintvalue> <hasp_info> <host_fingerprint type="sl-adminmode" crc=" ">mxhjsspcqvwsia2aasdcjswoxteuotgzdnwq4yn7iyxkaqk+ukpyhrgdohl8iaknba1x5qguykuqkjas- Qr8IeTEsVUYY0SLCWDBxhQNIRQ==</host_fingerprint> <host_fingerprint type="sl-usermode" crc=" ">mnhjsqobgkbo1hecanog4vhjfc8mid27uf1oxthe4bgitix6rqaulazn4etcglaibhjysslgai6pajor- PHcIqHBsClCRac4pBFQcWpYszxZDAPTin6gzJWKBdgSL</host_fingerprint> </hasp_info> </fingerprintvalue> </fingerprint> </fingerprintlist> </entitlement> </entitlementlist> </fingerprintdetails> Sample Code import java.io.ioexception; import org.apache.http.params.httpparams; public class EMSSample { private static DefaultHttpClient httpclient = new DefaultHttpClient(); private static Principal principal = null; public static String addfingerprint.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpPost post = new HttpPost(" List<NameValuePair> nvps = new ArrayList<NameValuePair>(); nvps.add(new BasicNameValuePair("fingerPrintInfo", "")); post.setentity(new UrlEncodedFormEntity(nvps, HTTP.UTF_8)); HttpResponse response = httpclient.execute(post, context); HttpEntity entity = response.getentity(); byte[] b = null; if (entity!= null) { long l = entity.getcontentlength(); b = new byte[(int) l];

224 218 Chapter 3: Web Service Interfaces entity.getcontent().read(b); entity.consumecontent(); return new String(b); Sample Response <emsresponse> <saved>true</saved> <stat>ok</stat> </emsresponse> See Also: Output Format for Failure Error Codes Error Code 101 Not authorized to use this product. 128 You should log on first Customer does not exist. Provide a valid Customer Reference Id Fingerprint friendly name cannot be blank. Provide a valid XML Either the FingerprintValue or FingerprintFriendlyName is not unique for the customer. Please provide the unique values Invalid XML string provided. Provide a valid XML Fingerprint friendly name cannot be greater than 255 characters Error occurred while decoding the fingerprint value. Please contact the system administrator for further assistance VendorCode is either null or empty for the tenant Invalid Tenant Id in use Retrieve Fingerprint This Web service retrieves a list of fingerprints for the specified customers. This Web service is available only for on-premise feature level licensing. Retrieve fingerprint(s) for the customer(s). Default Protocol Method Type URI HTTPS GET retrievefingerprint.xml

225 3.9. On-premise Machine Registration 219 Query Parameters Parameter Valid Values Optional CustInfo Customer reference IDs String No Input XML <CustomerDetails> <CustomerList> <Customer> <CustomerRefId>CNew</CustomerRefId> </Customer> </CustomerList> </CustomerDetails> 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 retrievefingerprint.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpGet get = new HttpGet(" query = new StringBuffer(); setparameter("customerinfo", ""); 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 {

226 220 Chapter 3: Web Service Interfaces query.append(key + "=" + value + "&"); Sample Response <?xml version="1.0" encoding="utf-8" standalone="yes"?> <emsresponse> <stat>ok</stat> <FingerPrintDetails> <CustomerList> <Customer> <CustomerRefId>Detach</CustomerRefId> <FingerprintList> <Fingerprint> <FingerprintId>2</FingerprintId> <FingerprintFriendlyName> fingerprint1</fingerprintfriendlyname> <FingerprintValue><?xml version="1.0" encoding="utf-8"?><hasp_info><host_fingerprint type="sl-adminmode" crc=" ">mxhjsspcqvwsia2aasdcjswoxteuotgzdnwq4yn7iyxkaqk+ukpyhrgdohl8iaknba1x5qguykuqkjasqr8ietesvuyy0slcwdbxhqnirq==</host_fingerprint> <host_fingerprint type="sl-usermode" crc=" ">mnhjsqobgkbo1hecanog4vhjfc8mid27uf1oxthe4bgitix6rqaulazn4etcglaibhjysslgai6pajorphciqhbsclcrac4pbfqcwpyszxzdaptin6gzjwkbdgsl</host_fingerprint></hasp_ info></fingerprintvalue> </Fingerprint> </FingerprintList> </Customer> </CustomerList> </FingerPrintDetails> </emsresponse> See Also: Output Format for Failure Error Codes Error Code 101 Not authorized to use this product. 128 You should log on first Customer does not exist. Provide a valid Customer Reference Id Invalid XML string provided. Provide a valid XML CustomerRefId cannot be blank. Provide a valid XML Error occurred while decoding the fingerprint value. Please contact the system administrator for further assistance.

227 3.9. On-premise Machine Registration Delete Fingerprint This Web service deletes fingerprints of customer s machines from Cloud Connect database. This Web service is available only for on-premise feature level licensing. Default Protocol Method Type URI HTTPS POST deletefingerprint.xml Post Parameters Parameter Valid Values Optional fingerprintinfo Fingerprint of customer s machine String No Input XML <FingerPrintDetails> <FingerprintList> <Fingerprint> <FingerprintId>1</FingerprintId> </Fingerprint> </FingerprintList> </FingerPrintDetails> Sample Code import java.io.ioexception; import org.apache.http.params.httpparams; public class EMSSample { private static DefaultHttpClient httpclient = new DefaultHttpClient(); private static Principal principal = null; public static String deletefingerprint.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpPost post = new HttpPost(" List<NameValuePair> nvps = new ArrayList<NameValuePair>(); nvps.add(new BasicNameValuePair("fingerPrintInfo", "")); post.setentity(new UrlEncodedFormEntity(nvps, HTTP.UTF_8)); HttpResponse response = httpclient.execute(post, context); HttpEntity entity = response.getentity(); byte[] b = null; if (entity!= null) {

228 222 Chapter 3: Web Service Interfaces long l = entity.getcontentlength(); b = new byte[(int) l]; entity.getcontent().read(b); entity.consumecontent(); return new String(b); Sample Response <emsresponse> <stat>ok</stat> </emsresponse> See Also: Output Format for Failure Error Codes Error Code 101 Not authorized to use this product. 128 You should log on first Fingerprint Id does not exist. Provide a valid Fingerprint Id Invalid XML string provided. Provide a valid XML Error occurred while decoding the fingerprint value. Please contact the system administrator for further assistance Add Entitlement Fingerprint This Web service registers machine fingerprints for given entitlement IDs. A machine fingerprint can be registered with only one entitlement ID. Notes This Web service is available only for on-premise entitlements created with detach mode. The Customer Contact Login by User ID and Password is required to use this Web service. Default Protocol Method Type URI HTTPS POST addentitlementfingerprint.xml

229 3.9. On-premise Machine Registration 223 Post Parameters Parameter fingerprintcontractinfo Input XML containing list of fingerprints and respective EIDs. Input XML Valid Values String Optional No The input of this Web service should be properly encoded to handle special characters. <FingerPrintDetails> <EntitlementList> <Entitlement> <Eid>ce6a c-4c19-89e0-37f9c726cec0</Eid> <FingerprintList> <Fingerprint> <FingerprintFriendlyName> fingerprint1</fingerprintfriendlyname> <FingerprintValue> <hasp_info> <host_fingerprint type="sl-adminmode" crc=" "> MXhJSSPcqVWSIA2aASDcJsWoxTeuotGzdNWq4Yn7IyxKaQk+UKpYHRGDoHl8IaKnBA1x5qguykuQKjaSQr8IeTEsVUYY0SLCW- DBxhQNIRQ==</host_fingerprint> <host_fingerprint type="sl-usermode" crc=" "> MnhJSQOBgkBO1HECAnOg4vHJFC8mId27UF1oxThE4bgITIx6RqaUlaZN4eTCGLAiBhJYSSlGAI6pAjOrPHcIqHBsClCRac4pB- FQcWpYszxZDAPTin6gzJWKBdgSL</host_fingerprint> </hasp_info> </FingerprintValue> </Fingerprint> <Fingerprint> <FingerprintFriendlyName> fingerprint1</fingerprintfriendlyname> <FingerprintValue> <hasp_info> <host_fingerprint type="sl-adminmode" crc=" "> MXhJSSPcqVWSIA2aASDcJsWoxTeuotGzdNWq4Yn7IyxKaQk+UKpYHRGDoHl8IaKnBA1x5qguykuQKjaSQr8IeTEsVUYY0SLCW- DBxhQNIRQ==</host_fingerprint> <host_fingerprint type="sl-usermode" crc=" "> MnhJSQOBgkBO1HECAnOg4vHJFC8mId27UF1oxThE4bgITIx6RqaUlaZN4eTCGLAiBhJYSSlGAI6pAjOrPHcIqHBsClCRac4pB- FQcWpYszxZDAPTin6gzJWKBdgSL</host_fingerprint> </hasp_info> </FingerprintValue> </Fingerprint> </FingerprintList> </Entitlement> </EntitlementList> </FingerPrintDetails>

230 224 Chapter 3: Web Service Interfaces Sample Code import java.io.ioexception; import org.apache.http.params.httpparams; public class EMSSample { private static DefaultHttpClient httpclient = new DefaultHttpClient(); private static Principal principal = null; public static String addentitlementfingerprint.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpPost post = new HttpPost(" List<NameValuePair> nvps = new ArrayList<NameValuePair>(); nvps.add(new BasicNameValuePair("fingerPrintContractInfo", "")); post.setentity(new UrlEncodedFormEntity(nvps, HTTP.UTF_8)); HttpResponse response = httpclient.execute(post, 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); Sample Response <emsresponse> <saved>true</saved> <stat>ok</stat> </emsresponse> See Also: Output Format for Failure Error Codes Error Code 101 Not authorized to use this product. 128 You should log on first Invalid XML string provided. Provide a valid XML

231 3.9. On-premise Machine Registration 225 Error Code 1110 Fingerprint friendly name cannot be blank. Provide a valid XML Fingerprint value cannot be blank. Provide a valid XML Invalid XML string provided. Provide a valid XML The FingerprintValue or friendlyname is not unique for the contract.please provide the unique values Entitlement does not exist. Provide a valid EID Entitlement is not of type On-premise Detach Mode EID cannot be blank.please provide a valid xml fingerprintcontractinfo cannot be empty.please provide a valid input Fingerprint friendly name cannot be greater than 255 characters Fingerprint cannot be registered for a revoked contract Error occurred while decoding the fingerprint value. Please contact the system administrator for further assistance VendorCode is either null or empty for the tenant Invalid Tenant Id in use Retrieve Entitlement Fingerprint This Web service retrieves a list of machine fingerprints associated with given entitlements. Notes This Web service is available only for on-premise entitlements created with detach mode. The Customer Contact Login by User ID and Password is required to use this Web service. Default Protocol Method Type URI HTTPS GET retrieveentitlementfingerprint.xml Query Parameters Parameter Valid Values Optional contractinfo Input XML containing list of EIDs. String No Input XML <EntitlementDetails> <EntitlementList> <Entitlement> <Eid>fe9a7eec abc-6171efdaa883</Eid>

232 226 Chapter 3: Web Service Interfaces </Entitlement> </EntitlementList> </EntitlementDetails> 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 retrieveentitlementfingerprint.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpGet get = new HttpGet(" query = new StringBuffer(); setparameter("contractinfo", ""); 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 <?xml version="1.0" encoding="utf-8" standalone="yes"?> <FingerPrintDetails> <EntitlementList> <Entitlement> <Eid>81ef45b0-1d6a-46d8-abfc-0f79cbf7f918</Eid>

233 3.9. On-premise Machine Registration 227 <FingerprintList> <Fingerprint> <FingerprintId>8</FingerprintId> <FingerprintFriendlyName> fingerprint1</fingerprintfriendlyname> <FingerprintValue><?xml version="1.0" encoding="utf-8"?><hasp_info><host_fingerprint type="sl-adminmode"crc=" ">bababab==</host_fingerprint><host_ fingerprint type="sl-usermode"crc=" ">qqqqq+asq5k=</host_fingerprint></hasp_ info></fingerprintvalue> <isactive>true</isactive> </Fingerprint> <Fingerprint> <FingerprintId>7</FingerprintId> <FingerprintFriendlyName> fingerprint2</fingerprintfriendlyname> <FingerprintValue><?xml version="1.0" encoding="utf-8"?><hasp_info><host_fingerprint type="sl-adminmode"crc=" ">123==</host_fingerprint><host_ fingerprint type="sl-usermode"crc=" ">qwer+asq5k=</host_fingerprint></hasp_ info></fingerprintvalue> <isactive>false</isactive> </Fingerprint> </FingerprintList> </Entitlement> </EntitlementList> </FingerPrintDetails> See Also: Output Format for Failure Error Codes Error Code 101 Not authorized to use this product. 128 You should log on first Invalid XML string provided. Provide a valid XML 1121 Entitlement does not exist. Provide a valid EID Entitlement is not of type On-premise Detach Mode EID cannot be blank.please provide a valid xml contractinfo cannot be empty.please provide a valid input Error occurred while decoding the fingerprint value. Please contact the system administrator for further assistance Delete Entitlement Fingerprint This Web service deletes the given machine fingerprint(s) from associated entitlement IDs.

234 228 Chapter 3: Web Service Interfaces Notes This Web service is available only for on-premise entitlements created with detach mode. The Customer Contact Login by User ID and Password is required to use this Web service. Default Protocol Method Type URI HTTPS POST deleteentitlementfingerprint.xml Post Parameters Parameter Valid Values Optional fingerprintcontractinfo Input XML containing fingerprint IDs. String No Input XML <FingerPrintDetails> <FingerprintList> <Fingerprint> <FingerprintId>1</FingerprintId> </Fingerprint> </FingerprintList> </FingerPrintDetails> Sample Code import java.io.ioexception; import org.apache.http.params.httpparams; public class EMSSample { private static DefaultHttpClient httpclient = new DefaultHttpClient(); private static Principal principal = null; public static String deleteentitlementfingerprint.xml()throws Exception { if(!verifylogin()){ return "login failed"; HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); HttpPost post = new HttpPost (" List<NameValuePair> nvps = new ArrayList<NameValuePair>(); nvps.add(new BasicNameValuePair("fingerPrintContractInfo", "")); post.setentity(new UrlEncodedFormEntity(nvps, HTTP.UTF_8)); HttpResponse response = httpclient.execute(post, context); HttpEntity entity = response.getentity(); byte[] b = null; if (entity!= null) {

235 3.9. On-premise Machine Registration 229 long l = entity.getcontentlength(); b = new byte[(int) l]; entity.getcontent().read(b); entity.consumecontent(); return new String(b); Sample Response <emsresponse> <stat>ok</stat> </emsresponse> See Also: Output Format for Failure Error Codes Error Code 101 Not authorized to use this product. 128 You should log on first Invalid XML string provided. Provide a valid XML 1106 Fingerprint Id does not exist. Provide a valid Fingerprint Id Error occurred while decoding the fingerprint value. Please contact the system administrator for further assistance.

236

237 4 Error Codes Given below is a master list of the Web services error codes: Error Code 100 Invalid request parameter. 101 Not authorized to use this product. 107 An internal error occurred! Please report the error to System administrator. 109 "Invalid sortorder.valid values are 'asc' or 'desc'. 110 Invalid pageindex. Valid value can be any positive integer greater than Invalid pagesize.valid value can be any positive integer greater than Specify a valid Boolean value for {field. Valid values are true or false. [Note: This error code is applicable for the fields - fetchcompleteeid, loginallowed, isenabled, and optional.]. 115 Length of {field is {actual value. It cannot be more Than {max value. [Note: This error code is applicable for the fields - billaddr, billaddrcity, billaddrcountry, billaddrstate, billaddrzip, shipaddr, shipaddrcity, shipaddrcountry, shipaddrstate, shipaddrzip, refid1, refid2, contactpassword, description, and default value.] 117 Regular Expression validation failed for contact id 118 {field should be of datatype Integer. [Note: This error code is applicable for the fields - License modelid, entid, ftrid, customerid, lmid, templatetype, lineitemid, CustomerId, stationcount,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, 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, and granularity.] 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. 124 Invalid sortcolumn. Valid values are startdate,enddate,state,totalcredit,status,contact id, customername,id. 128 You should log on first. 132 The URL address does not exist. 133 Invalid namespace.

238 232 Error Codes Error Code 213 User name cannot be blank. 214 Password cannot be blank. 215 Either username or password is incorrect Id or Password is incorrect, please retry to login. 218 Your account has been disabled. Please contact Administrator! 301 Unable to find product for ID Id 302 No product exists for given Name and Version. 304 Mentioned feature ids are not correct. 305 Mentioned feature id should belong to same Namespace As product. 308 Entitlement's lifecyclestage is not valid. 309 Unable to find feature. 311 Feature featurename already a part of Entitlement and cannot be deleted. 312 Product ${productname already exists. Please try again with different name and version. 319 The feature does not exist. 320 A deployed feature cannot be updated. 321 Namespace EMS_NMS already exists. Please try again with different name 322 This Namespace does not exists in the system. 323 Feature {feature already exists. Try again with different name. 325 This product is already part of Entitlement! 327 Can be deleted only if it is in draft state. 328 product is not in lifeycle stage complete 333 Product already in complete state and cannot be updated. 343 Feature name is inside a completed/eol product and cannot be deleted. 344 Product already in End Of Life state and cannot be Updated/deleted. 345 featureid is mandatory. 411 License model does not exist. 412 Default license model is not from license Model list. 413 LicenseModel <LicenseModel name> already exists. Try again with different name. 512 The customer does not exist 513 The contact does not exist. 515 Invalid contact for this customer. 519 Customer not found for the given customerid. 521 Customer {actual Value already exists. Please try again with different name. 529 Given ID {actual Value is not unique. Please try again with different ID.

239 233 Error Code 612 Entitlement cannot be completed as it does not contain line Items. 613 Already committed. 615 End date and Start date cannot be null 617 Start date cannot be greater than end date 618 Could not find the entitlement line item. 621 Entitlement does not exist. Retry with a correct ID. 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). 647 Cannot update entitlement with lifecyclestate=complete. 650 eid cannot be null 656 Entitlement not yet started, please contact administrator 657 Entitlement expired, please contact administrator. 658 Entitlement is not in complete state, please contact Administrator. 661 The entitlement item cannot be updated because the entitlement is in the complete stage. 668 Could not find the entitlement license model for id={actual value 682 The line item does not exist 692 Entitlement already in Complete state and cannot be Updated/Deleted. 694 Customer cannot be deleted as entitlement exists for this Customer. 695 Mentioned feature ids are not present in the Entitlement with id 696 Entitlement with id entid does not exists. 697 No Attribute exists for given attribute Id. 701 Invalid operation: cannot obtain Entitlement Certificate for an entitlement(id- 317 ) which is Not complete. 704 The entitlement item does not have this product. 711 Invalid Template Type! 712 Entity not found. 713 Invalid Boolean value {value passed. Provide a valid value(0 or 1). 714 Invalid Numeric value(x) passed. Please provide a valid value. 715 Invalid Date value(x) passed. Please provide a valid value(in yyyy-mm-dd format). 716 No data type exists for the value (value). 717 Invalid entityid or custom attribute. 718 Attribute not found. 801 Feature Ids should have a numeric value. 810 Error in reading xx.tpl file. Please contact administrator.

240 234 Error Codes Error Code 1002 Entitlement is not Activated Entitlement is for a Retail Customer Enterprise UserIDs not added Enterprise UserID not removed productname is already in End Of Life state Unable to retrieve Usage Data Entitlement is for an unnamed enterprise Customer Service Agreement not found UserId can not be blank Identity(s) not added. [Note: The reason is dynamic, such as total number of permitted identities exceeded.] 1015 Invalid bill type preference. Valid values are 1(Brief bill), 2(Detail bill),3(itemized bill) Data Unavailable Please enter a valid value ftrid(s) should be of type integer The specified featureid already exists 1028 Entitlement is not marked complete Product does not exist for the given name and version Service agreement attribute value can be updated only for 'Draft' entitlement The entitlement item does not have this product Invalid value for numberofusers. Valid values are -1(for unnamed contract), greater than 0 for Named contract Invalid value for status Valid values are 0(enable), 1(Disable), 2(Revoke) LineItem does not exist in the given entitlement Cannot Enable line item of a Disabled Contract Status not updated as the status specified is already set The sort column is not valid. Valid values are productid,productname,productversion,lifecyclestage,deployed,namespacename,product Invalid attribute value The given attributeid attribute is not updatable EntitlementServiceAgreement not found for passed ID={ XML schema Validation Failed Entitlement is already Revoked Line Item is already Revoked.

241 235 Error Code 1047 Entitlement not deployed on SAAS server Entitlement is already in Reconfigure State 1051 The attribute value {value is not available in the predefined list of values. Provide a valid value only { Number User(s) already added Enterprise UserIDs cannot be added/deleted in reconfigure stage 1067 An On-Premise entitlement can not be retail Valid values for deploymenttype are 1(Cloud) and 2(On-Premise) Selected License Model for feature - <featurename>, is not supported for On-Premise deployment 1071 Not supported for On-Premise entitlement Only Per Login counting type is allowed in concurrent license model for On-Premise (Entitlement level and Detach Mode) entitlement Only days between 1 and 1825 are accepted Invalid concurrent limit.concurrent limit between is allowed FeatureID out of range for feature <featurename>. FeatureID can range from for On-premise deployment Deployment type change not allowed.please delete the entitlement and create a new one with the desired deployment type Please enter a valid Feature ID, in the range {field should be of datatype long. [Note: This error code is applicable for the field - lastmodified.] 1081 Invalid Web service version provided 1082 No entitlement exists for the given customer No Web service version provided 1086 template attribute (x) already exists. Try again with a different name No custom attribute exists for attributeid {Id The EMS system is running on HTTPS. Please provide the correct Web service URL Invalid TimeZone Id provided Id The product does not have feature {feature Id Invalid value {value given for On.Valid values are 0(off) and 1(on) Allow at least one feature nvalid value {0 for selected. Valid values are 0 and Only one license model can be set for a feature License Model of an already deployed feature {Name cannot be changed Unable to find feature with Id{ID 1099 Unable to find License Model with Id {ID.

242 236 Error Codes Error Code 1100 Invalid max usage limit. Max usage limit between is allowed No License Model exist for the featureid {0, which is supported for on-premise Maximum pageindex allowed for specified size is Valid values for deploymenttype are 1(Cloud),2(On-Premise Entitlement Level), 3(On-Premise Feature Level), 4(On-Premise Detach Mode) Customer does not exist. Provide a valid Customer Reference Id Fingerprint Id does not exist. Provide a valid Fingerprint Id Fingerprint friendly name cannot be blank. Provide a valid XML Fingerprint value cannot be blank. Provide a valid XML Either the FingerprintValue or FingerprintFriendlyName is not unique for the customer. Please provide the unique values Only Per Identity Per Station counting type is allowed in concurrent license model for On-Premise Feature level entitlement Invalid XML string provided. Provide a valid XML CustomerRefId cannot be blank. Provide a valid XML Only "Per Identity Per Station" counting type in Concurrent license type is allowed for the Feature Level caching mode of on-premise entitlements.please change the license model associated with this feature The FingerprintValue or friendlyname is not unique for the contract.please provide the unique values Entitlement does not exist. Provide a valid EID Entitlement is not of type On-premise Detach Mode EID cannot be blank.please provide a valid xml fingerprintcontractinfo cannot be empty.please provide a valid input contractinfo cannot be empty.please provide a valid input Invalid value for stationcount.valid values are between Fingerprint friendly name cannot be greater than 255 characters Fingerprint cannot be registered for a revoked contract Error occurred while decoding the fingerprint value. Please contact the system administrator for further assistance VendorCode is either null or empty for the tenant Error in retrieving capacity information. Please contact the system administrator for further assistance Invalid Tenant Id in use Invalid capacity value.capacity value between is allowed.

243 Glossary A Administrator Administrator is a person having local administrator rights on the Web server. Apache Tomcat Tomcat is an open source JSP and Servlet container from the Apache Foundation. Sentinel EMS makes use of Apache Tomcat 6 as its default Web server. C Capacity Indicator of load on a feature during a login session. The load can have different meanings in different environments. It could be number of users consuming the application at a given time or the number of cores. Capacity Attribute A license attribute that is used to enable processing of capacity values recorded by an application for postpaid features. You must set Capacity Attribute in EMS if you want to be notified when your customers approach or reach a specified limit. Contact The individual who is the single point of contact for an entitlement. This contact may be pre-existing, and be associated at time of entitlement creation; or a new contact may be created along with the entitlement. A contact may or may not belong to a customer. Customer Represents the organization/end user which owns an entitlement or needs license to run the licensed application(s). D Detach Mode Detach mode allows an on-premise application to checkout a license for a specified duration, as configured by ISV. Once a license is checked out, the application can

244 238 Glossary work in completely offline mode for the duration of detach. E Enterprise Entitlement Entitlement created for an organization. It can either be named or unnamed. Entitlement It is the right granted by law or contract to use a particular software (or a group of software packages) within its set limits. Entitlement certificate An entitlement certificate is generated when an entitlement is created for a customer. It contains information like entitlement details and the list of associated products. Entitlement ID The identification code that EMS generates when an entitlement is created. This ID is used as a reference for retrieving or editing an entitlement after creation. Entitlement Management System Entitlement management system is a centralized Web application that allows you to generate, manage, and fulfill licenses. F Feature A feature is a functionality of any product an ISV wants to sell. Feature ID A unique digit assigned to every feature. It is used by a service (or, an ISV application) to enforce authorization at the feature level. Feature Name A unique name assigned to every feature. It can be used by an ISV application to enforce authorization at the feature level (for on-premise deployments). Fingerprint Information that uniquely identifies an on-premise machine.

245 239 L License certificate After an entitlement is deployed on server, a License Certificate is generated and is sent to the customer via . It contains entitlement details, product details, EID, etc. License Model A logical collection of attributes that define a template for selling a feature of a product in a particular manner. Line Item Refers to the product added to an entitlement. N Named Entitlement Allows product usage to a specific retail user or assigned users in an enterprise. Namespace A container for products and features in EMS. P Peak Capacity The cumulative value of capacity. It indicates the cumulative load across a number of simultaneous sessions that are in use by a customer. Product A product is the entity which an ISV wants to sell to end user. A product may have multiple features in it. R RESTful Systems that follow Representational State Transfer (REST) principles are referred to as RESTful. For more information on REST web services see Retail Entitlement Entitlement created for an individual.

246 240 Glossary S Service Agreement A mutual agreement between a software provider and a customer. This agreement defines various attributes of products being offered, such as level of quality, performance, availability, etc. In Sentinel EMS, service agreement is used to record customer preferences for billing cycle. State Specifies the state of a feature/license on Sentinel Cloud Connect. It can be: Not Active, Active, Expired, or Exhausted. Station Count Maximum number of on-premise machines on which an entitlement can be used at a time, in the case of entitlement level licensing. Status Applies to an entitlement and its line item(s). It can be: Enabled, Disabled, or Revoked. The change in status of entitlement/line item is initiated by a software provider. U Unnamed Entitlement Allows product usage to any user in the enterprise group user ID Identifies a user in case of a named entitlements (both retail and enterprise). User ID is same as the identifier coming from the ISV application after authorizing a user of named entitlement. W Web server A computer program that can accept HTTP requests from client computers (or web browsers), and serve them with HTTP responses along with optional data contents.

247 Index Index authentication 13 bill type 160 call syntax 6 Capacity 169 client session 13 close session 20 concurrent sessions 165 contact us vi custom attributes 204 add 204 delete 214 search 207, 209 update 212 customer add 176 delete 193 search 181, 184, 186 customer login 15 customer usage log 152 emswsdemo 3 enterprise user ID 127 add 127 remove 129 retrieve 131 error codes 10, 231 error handling 10 feedback vi A B C E F fingerprint add 216, 222 delete 221, 227 retrieve 218, 225 HTTPS request 1 input parameters 10 license model associate 32 copy 63 search 57, 59 license state 138 log in 13 log out 20 login by contact 18 H I L M managing catalog elements 22 managing customers and contacts 176 managing entitlements 68 password 13 Peak Capacity 169 query parameters 10 reconfiguration 135 sample code 10 P Q R S

248 242 Index sample response 10 sessionid 13 status entitlement 140, 142 line item 144, 146 technical support vi time zone 195 URI 6 usage bill 160 usage count 167 usage log 149 username 13 vendor login 13 version 7 retrieve 11 T U V W web service APIs addenterpriseuserids.xml 127 addentitlementfingerprint.xml 222 addentitlementitem.xml 79 addfeature.xml 27 addfingerprint.xml 216 addnamespace.xml 23 associatefeatureswithproduct.xml 44 changecontractlineitemstatus.xml 147 changecontractstatus.xml 142 changeproducttlifecyclestage.xml 48 closesession.xml 20 commitentitlement.xml 85 copylicensemodel.xml 63 createcontact.xml 178 createcustomer.xml 176 createentitlement.xml 70 createservice.xml 42 createtemplateattribute.xml 204 deletecustomerbyid.xml 194 deleteentitlementfingerprint.xml 228 deletefeature.xml 40 deletefingerprint.xml 221 disassociatefeaturesfromproduct.xml 46 featurelist.xml 36 getcustomerbycustomername.xml 186 getcustomerbycustomerrefid.xml 188 getcustomerbyid.xml 184 getcustomerrefidbycustomername 192 getcustomerusagelog.xml 152 getcustomerusagelogbasedonvendorinfo 156 getentfeaturelmattributes.xml 117 getentitlementcertificatehtml.xml 90 getentitlementdetailsbyid.xml 73 getentitlementitembycriteria.xml 105 getentitlementitembyid.xml 96 getentitycustomattributes.xml 207 getlicensemodelbyid.xml 59 getproductbyid.xml 50 getproductbynameandver.xml 55 getserviceagreementattributes.xml 123 getwebserviceversion.xml 11 initiatereconfigure.xml 135 isduplicatecustomername 190 licensemodellist.xml 57 loginbycontact.xml 18 loginbyeid.xml 15 namespacelist.xml 25 removeenterpriseuserids.xml 129 removeentitlementitem.xml 103 removetemplateattribute.xml 214 retrievecontractlineitemstatus.xml 145 retrievecontractstatus.xml 140 retrievecurrentsessions.xml 165 retrievecurrentusagecount.xml 167 retrieveenterpriseidentities.xml 131 retrieveentitlementfingerprint.xml 225 retrievefeaturelineitemassociation 107 retrievefingerprint.xml 218 retrievelicensestate.xml 138 retrievelineitemfeaturelmassociation 112 retrievepeakcapacity.xml 170 retrieveusagebilling.xml 160 retrieveusagelog.xml 149 searchcustomers.xml 181 searchentitlements.xml 86 searchentitybycustomattribute.xml 209

249 searchproducts.xml 52 serviceagreementlist.xml 65 setentfeaturelmattributes.xml 121 timezonelist.xml 195 updatecustomattribute.xml 212 updateentitlement.xml 82 updateentitlementattributeforallfeatures.xml 93 updateentitlementitem.xml 101 updatefeature.xml 30 updatefeaturelineitemassociation 110 updatefeaturelmassociation.xml 32 updatelineitemfeaturelmassociation 115 updateserviceagreementattributes.xml 125 verifylogin.xml 13 viewfeaturebyid.xml 33 web services 1 Index 243

250