Sentinel EMS v7.1 Web Services Guide

Transcription

1 Sentinel EMS v7.1 Web Services Guide

2 ii Sentinel EMS Web Services Guide Document Revision History Part Number , Revision E. Software versions 7.1 and later. Revision Action/Change Date A Initial release December 2011 B Updated for release May 2012 C Updated for release 6.3. September 2012 D Updated for release 6.4. March 2013 E Updated for release 7.0. August 2013 F Updated for release 7.1. March 2014 Disclaimer and Copyrights Copyright 2014, 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 Contents Preface vii Chapter 1: Introduction Development Platforms 2 Chapter 2: Web Service Call Basics Creating a REST Request Base URL HTTP GET Get Details of a Resource Search Resources HTTP PUT URL Pattern Example HTTP POST URL Pattern Example HTTP DELETE URL Pattern Example 6 Chapter 3: Authentication Publisher Login Sample Input (XML) Sample Response Sample Code to Fetch Session ID from Response Headers Customer Login by Product Key Post Parameters Sample Response Log Out Response User Roles and Related Permissions on Resources 9 Chapter 4: Web Service Interfaces Vendor Get All Enforcements 12

4 iv Sentinel EMS Web Services Guide Get All Vendors by Enforcement ID Get All Vendors Get All Vendors by User ID Export Definition Bundle Provisional Namespaces (Deprecated) Get Namespace Details by ID (Deprecated) Get Namespaces by Vendor (Deprecated) Sample XML for Namespace Web Services Viewing License Model Details Retrieve License Model by ID Retrieve All License Models Features Create a Feature for a Given Vendor ID Create a Feature for Given Vendor ID and Namespace (Deprecated) Edit Feature Properties Delete Feature Retrieve Feature Details by ID Search Features Retrieve All Features by Vendor and Namespace (Deprecated) Sample XML for Feature Web Services Products Create Product for Vendor ID Create Product for Vendor ID and Namespace (Deprecated) Edit Product Properties Delete Product Retrieve Product Details Search Products Search Products by Vendor and Namespace (Deprecated) Sample XML for Product Web Services Managing Entitlements Create an Entitlement Update Entitlement Details Delete an Entitlement Get Entitlement Details (XML) by entid Search Entitlements Get Product Key Details (XML) Update Product Key Creating/Producing an Protection Key Update type Entitlement Sample XML for Entitlement Web Services Sample XML for Product Key Product Key Activation Generate License Get License by Activation ID (aid) Protection Key 69

5 v Update Protection Key (Checkin/Read/Format/Force Introduce/Enable/Disable/Finger Print/Locate/Convert v2c to exe) Get Protection Key by Capable Devices Get Protection Key Capable Devices by Product Key Get Entitlements by Protection Key ID Get Protection Key Fingerprint by Key ID Get Protection Key History by Key ID Remove Pending Updates Sample XML for Protection Key Web Services Customers and Contacts Create Customer Update Customer Details Delete Customer Retrieve Customer Details Search Customers Get Contact by Customer ID Create Contact Update Contact Details Delete Contact Retrieve Contact Details Get Contact Details by Search Contacts Sample XML for Customer Web Services Sample XML for Contact Web Services 94 Chapter 5: Backward Compatibility Modified XSDs in Sentinel EMS Modified and New XSDs in Sentinel EMS Web Services that Were Deprecated in Sentinel EMS Changes in 2.2 XSDs over Chapter 6: emswsdemo: A Client Application to Test the Web Services Deploying emswsdemo Accessing the emswsdemo URL 99 Chapter 7: A Sample Application using Java Getting Ready The Concept Read Properties Set System Properties Log In Call the Web Services 102

6 vi Sentinel EMS Web Services Guide Handling Response 103 Chapter 8: Data Model Activation Objects Entitlement Objects Catalog Objects 107 Appendix A: Request/Response Schemas for Web Services Resources 109 A.1. XSD for Authentication Details 110 A.2. XSD for Namespace Web Services 110 A.3. XSD for License Model Web Services 111 A.4. XSD for Feature Web Services 113 A.5. XSD for Product Web Services 114 A.6. XSD for Entitlement Web Services 121 A.7. XSD for Product Key Web Services 125 A.8. XSD for Activation Web Services 127 A.9. XSD for Protection Key Web Services 128 A.10. XSD for Contact Web Services 133 A.11. XSD for Customer Web Services 134 A.12. XSD for License String 136 A.13. XSD for List Response 137 A.14. XSD for Entitlement List Response 138 Appendix B: HTTP Status Codes 141 Glossary 143 Index 153

7 Preface Who Should Read This Document? This document is intended for administrators and users who want to use the Sentinel EMS Web service interfaces. Conventions Used in This Document Convention Bold lettering Courier Italic lettering Description 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 User's Guide Configuration Guide Web Services Guide (this document) What's in it? Provides details about the functionalities available in Sentinel EMS and demonstrates the steps to perform various tasks using the graphical interface. Provides information about customizing the Sentinel EMS Server. Details the web service resources available to facilitate integration of EMS data and transactions with external IT systems like CRM and ERP. Acknowledgments Contains acknowledgments for the third-party software used. Support Contacts You can contact us using any of the following options: 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) support@safenet-inc.com URL: Downloads - You may want to explore updated installers and other components here:

8 viii Sentinel EMS Web Services Guide 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:

9 Chapter 1: Introduction Sentinel EMS is a powerful role-based application designed to manage the business activities required to implement and maintain Sentinel LDK in your organization. Sentinel EMS handles three major work flows: license planning, entitlement generation and production, and software activation. Sentinel LDK separates the software protection process (implemented with Sentinel Licensing API or Sentinel LDK Envelope) from the licensing and production processes (implemented with Sentinel EMS), enabling you to modify your company s licensing strategy as necessary when circumstances change, and to implement these changes quickly and efficiently. The primary component of Sentinel EMS is its Web Server. Users in your organization can access the application from client machines in the network using a web browser or via the web service interfaces provided. The Sentinel EMS Web Services are designed to enable you to integrate various functionalities of Sentinel EMS in your organizational management software (for example, ERP or CRM). This document specifies the RESTful Web Services provided for managing Sentinel EMS resources, for example, Features, Products, Entitlements, and Customers. You can manage (for example, create, update, delete) the resources using HTTP methods GET, PUT, POST, or DELETE. Resource representations are in XML. The following table lists the functionalities of Sentinel EMS for which web services have been exposed. 1 Resource Vendor Namespace (deprecated) Feature License Model Product Customer Contact Entitlement Target (or Protection key) Activation Methods GET PUT (create) POST (update) DELETE

10 2 Chapter 1: Introduction 1.1. Development Platforms The web services work with most of the development environments, including, but not limited to, Visual Studio.NET 2005, and Java. In this document, we have provided samples for Java.

11 2 Chapter 2: Web Service Call Basics The Sentinel EMS uses REST principle for web services. You can construct request URLs that will work in your browser, on the command line, and in your code Creating a REST Request The web services operate on the resource types Feature, Product, License Models, Entitlement, Customer, and Contact. The starting point for all web service calls is a URI, which identifies the Sentinel EMS Server Base URL All request URLs start with a fixed string which resembles the following. This is called the base URL. http(s)://<hostname>:<port>/ems/v71/ws/ where Hostname Host name of the Sentinel EMS Server. Port Port of the Sentinel EMS Server. ems Starting directory. v71 Version of Sentinel EMS web services. ws A mandatory part of the string HTTP GET The GET method is used to (i) retrieve details of a resource or (ii) search resources Get Details of a Resource URL Pattern type>/<object Id>.ws

12 4 Chapter 2: Web Service Call Basics Example For <ObjectType> = product <ObjectId> = 1 the URL becomes This request will return the details of a product with ProductId = Search Resources URL Pattern Object Id>/<Object Type>.ws?<SearchPar am>=<searchvalue> The question mark (?) denotes the starting point for optional parameters. You need to separate multiple optional parameters by semi-colons (;). If you remove the question mark along with the parameters that follow, all records will be returned. Example For <RootObjectType> = vendor <RootObjectId> = 1 <ObjectType> = product <SearchParam>=productName <SearchValue>=print the URL becomes This request will return all records for vendor ID = 1 and Product name starting with 'print'. You can remove or repeat the <RootObjectType>/<RootObjectId>/ part in the URL depending on the nesting of the resource. Example: vendor/{vendorid}/product.ws

13 2.3. HTTP PUT HTTP PUT The PUT method is used to create a new resource URL Pattern Object Id>/<Object Type> Example For <RootObjectType> = vendor <RootObjectId>=1 <ObjectType>=Product the URL becomes This request will create a Product for vendor ID = 1. In the request body, you need to provide a valid input XML (validated by the XSD provided). By REST convention, repeated HTTP PUT requests should replace existing objects. However, Sentinel EMS does not allow complete replacement of any object, because it internally uses an Auto-ID, which cannot be updated HTTP POST The POST method is used to edit the details of a resource URL Pattern Example For <ObjectType>= product <ObjectId>=1 the URL becomes

14 6 Chapter 2: Web Service Call Basics This request will update details of the product with product ID = 1. In the request body, you need to provide a valid input XML (validated by the XSD provided). The URL for this request is simple as it is based on the Auto-ID generated by Sentinel EMS, which is unique in all conditions for a given object type HTTP DELETE DELETE method is used to delete a resource URL Pattern Example For <ObjectType> = product <ObjectId> = 1 the URL becomes This request will delete the product with ID = 1. The URL for this request is simple as it is based on the Auto-ID generated by Sentinel EMS, which is unique in all conditions for a given object type.

15 Chapter 3: Authentication Before making any web service calls, a client application must log in to Sentinel EMS Server and obtain a sessionid. This section lists the web services provided to log in and log out of Sentinel EMS Server. The client application can use the logout web service to log out of Sentinel EMS Server. 3 You can configure login for your customers/end users by using the method loginbyproductkey. The logout method is common for both user and Product key log in Publisher Login Use this method to log in to the Sentinel EMS Server and start a client session. A client application must log on and obtain a sessionid before making any web services calls. To call the login method, the client application needs to provide a user name and password in XML format. The Sentinel EMS Server authenticates the credentials and returns a session ID in response header to be used in subsequent calls. Method Type POST URI v71/ws/login.ws Sample Input (XML) <?xml version="1.0" encoding="utf-8"?> <authenticationdetail> <username>admin</username> <password>admin</password> </authenticationdetail> The input/output XML comply with a common XSD schema. See "XSD for Authentication Details" on page Sample Response HTTP Status Code: 200 Response Body:

16 8 Chapter 3: Authentication <?xml version="1.0" encoding="utf-8"?> <authenticationdetail> <username>admin</username> <version>7.1.0</version> </authenticationdetail> Sample Code to Fetch Session ID from Response Headers Session ID is returned in the response header (Set-Cookie). Following is a sample code to fetch the session ID from the response header. DefaultHttpClient httpclient= new DefaultHttpClient(); StringEntity se = new StringEntity(inputString,"UTF-8"); HttpContext localcontext = new BasicHttpContext(); HttpPost httppost = new HttpPost(uri); httppost.setentity(se); HttpResponse emsresponse = httpclient.execute(httppost,localcontext); Header[] cookieheader=emsresponse.getheaders("set-cookie"); if(cookieheader!=null && cookieheader.length>0) { for(header header:cookieheader) { for(headerelement element:header.getelements()) { if(element.getname().equalsignorecase("jsessionid")) { sessionid=element.getvalue(); break; } } } } 3.2. Customer Login by Product Key Login by Product key and get session ID. Method Type POST URI v71/ws/loginbyproductkey.ws Post Parameters Parameter Description Type productkey Sample Response HTTP Status Code: 200 Specify the Product Key to log on to Sentinel EMS. When logged in by Product Key, the customer can perform certain activities only on one Product corresponding to the key. String

17 3.3. Log Out 9 Response Body: <?xml version="1.0" encoding="utf-8"?> <EMSResponse> <regrequired>1</regrequired> <sessionid>8dff9a5071e4be930c8fc89e8bb8bd35</sessionid> <stat>ok</stat> </EMSResponse> 3.3. Log Out This web service is common for both vendor log in and log-in by Product key. You can use this web service to close the session and log out from Sentinel EMS. Method Type POST URI v71/ws/logout.ws Response HTTP Status Code: User Roles and Related Permissions on Resources The methods available on different resources for a user depend on the role assigned to him. The following table provides a detailed list of resource permissions available for different roles. Resource Product Group Feature Product Manager Entitlement Manager GET, PUT, POST, DEL GET, PUT, POST, DEL Roles and Associated Permissions GET GET License Model GET GET Product GET, PUT, POST, DEL GET Production Customer Services Customer GET, PUT, POST, DEL GET GET, PUT, POST, DEL Contact GET, PUT, POST, DEL GET GET, PUT, POST, DEL Entitlement GET, PUT, POST, DELETE GET, POST Product Key GET, POST GET GET, POST Activation GET, POST GET, POST

18 10 Chapter 3: Authentication The following roles are not listed in this table as they have either all or no permission on all the resources. Super User All permissions (GET, PUT, POST, DELETE) on all the resources in all available Batch Codes. Batch Code Admin All permissions (GET, PUT, POST, DELETE) on all the resources in the assigned Batch Codes. Development No permission is available on the resources for this role.

19 Chapter 4: Web Service Interfaces This chapter lists the web services available in Sentinel EMS and explains how to use REST to make requests. REST allows you to make calls to EMS by passing parameters. EMS returns its response in XML format. Sentinel EMS supports both HTTP and HTTPS, the default protocol being HTTP. However, the administrator can change the protocol during or after installation. Contact your EMS admin to know the protocol in use. The query/input parameters are listed for each web service. The query parameters are case sensitive. Their data type and allowed values are mentioned in the column 'Type' for each web service. Required parameters must be provided for the request to succeed. The XMLs follow standard XSDs. You can find the XSDs and sample XMLs in the following directories on the Sentinel EMS Server locally: Sample XMLs %EMS_HOME%\EMSServer\webapps\ems\RestXmlSamples XSDs %EMS_HOME%\EMSServer\webapps\ems\xsd 4

20 12 Chapter 4: Web Service Interfaces 4.1. Vendor This section lists the web services provided for Vendor management. The following interfaces are supported for the Vendor: Method URI Template Description GET v71/ws/enforcement.ws?vendorid={vendorid} Get All Enforcements GET v71/ws/enforcement/{enforcementid}/vendor.ws Get all Vendors by Enforcement ID GET v71/ws/vendor.ws Get all Vendors GET v71/ws/vendor.ws?userid={userid} Get Vendors by User ID GET v71/ws/vendor/{vendorid}/exportdefinition.ws Export definition GET v71/ws/vendor/{vendorid} /bundleprovisional.ws?prodids={prodids} Bundle provisional Get All Enforcements Returns the list of available Enforcements. Method Type GET URI v71/ws/enforcement.ws?vendorid={vendorid} Example URL: URI Parameters Parameter Description Type vendorid Identifier of the Vendor in the database. Integer Sample Response Success HTTP Status Code: 200 Response Body: <listresponse type="enforcement" count="2"> <instance id="1" name="sentinel LDK" /> <instance id="2" name="sentinel Cloud" /> </listresponse> Failure HTTP Status Code: 404 Response Body: You should log on first.

21 4.1. Vendor Get All Vendors by Enforcement ID Returns the list of available Vendor IDs. Method Type GET URI v71/ws/enforcement/{enforcementid}/vendor.ws URI Parameters Parameter Description Type enforcementid Identifier of the Enforcement in the database. Sample Response Success HTTP Status Code: 200 Response Body: In this release of Sentinel EMS, the only Enforcement ID available is Sentinel LDK (with enforcementid = 1). In future releases, other Enforcements like Sentinel RMS will also be supported. Integer <listresponse type="vendor" count="1"> <instance id="1" name="demoma" identifier="37515"/> </listresponse> Failure HTTP Status Code: 404 Response Body: The specified Enforcement with ID 8 does not exist Get All Vendors Returns a list of all Vendor IDs available in Sentinel EMS. Method Type GET URI v71/ws/vendor.ws URI Parameters Not applicable. Sample Response Success HTTP Status Code: 200 Response Body:

22 14 Chapter 4: Web Service Interfaces <listresponse type="vendor" count="1" searchparameters="{userid=brown}"> <instance id="1" name="demoma" identifier="37515" batchcode="demoma"/> </listresponse> Failure HTTP Status Code: 401 Response Body: You should log on first Get All Vendors by User ID Returns a list of Vendor IDs for a given User ID. Method Type GET URI v71/ws/vendor.ws?userid={userid} Example URL: URI Parameters Parameter Description Type userid Identifier of the User in the database. String Sample Response Success HTTP Status Code: 200 Response Body: <listresponse type="vendor" count="1" searchparameters="{userid=brown}"> <instance id="1" name="demoma" identifier="37515" batchcode="demoma"/> </listresponse> Failure HTTP Status Code: 401 Response: You should log on first Export Definition Returns a file containing the Feature Name and Feature ID of all defined Features, together with the Product Names and Product IDs in which they are incorporated. Method Type GET URI v71/ws/vendor/{vendorid}/exportdefinition.ws?filetype={filetype}

23 4.1. Vendor 15 URI Parameters Parameter Description vendorid filetype Enter the Identifier of the Vendor in the database. for which you want to retrieve the catalog definition. The output file type. The options are: CSV Returns Features in CSV format. XML Returns Features and Products in XML format. C Returns Features and Products in C-style header. CPP Returns Features and Products in CPP-style header. Type Integer String Sample Request Not applicable. Sample Response Success HTTP Status Code: 200 Response Body:: <?xml version="1.0" encoding="utf-8"?> <definitions> <type>csv</type> <data> <Feature Name, Feature ID"CleanDrive",4"ReportOption",3"ZipOption",2"ProtectDrive",1Product Name, Product ID"Protect Drive",2"Clean Drive",3> </data> </definitions> Failure HTTP Status Code: 400 Response Body: Illegal file type Bundle Provisional Bundle Provisional Products. Method Type GET URI v71/ws/vendor/{vendorid}/bundleprovisional.ws?prodids={prodids} Example URL:

24 16 Chapter 4: Web Service Interfaces URI Parameters Parameter Description Type vendorid (Required) The Vendor ID for the Provisional Product. Integer prodids (Required) Product IDs for which you are creating the bundle. Integer, comma separat ed Sample Response Success HTTP Status Code: 200 Response Body: <hasp_info> <haspscope> <vendor id="37515"> <hasp id=" " /> </vendor> </haspscope> <v2c> yoijpaccczyabhz0yzkbggimln5e89nlxr0wmrce9ibsfu8axezbdjpy8l2durz4atdmovt4buke6dgrh51cw3/ </v2c> </hasp_info> Failure HTTP Status Code: 404 Response Body: Some of the Product IDs sent are not connected to the Vendor Namespaces (Deprecated) This section provides information about the web services available to manage Namespaces. The web services for Namespace have been deprecated for EMS 6.3. Method URI Template Description GET v71/ws/namespace/{namespaceid}.ws Get Namespace details by ID v71/ws/vendor/{vendorid}/namespace.ws Get Namespace Details by ID (Deprecated) Retrieval the details of a Namespace by namespaceid. Get Namespaces by Vendor

25 4.2. Namespaces (Deprecated) 17 Method Type GET URI v71/ws/namespace/{namespaceid}.ws URI Parameters Parameter Description Type namespaceid Identifier of the Namespace in the database Integer Sample Response Success HTTP Status Code: 200 Response Body <namespace> <namespacename>softpro</namespacename> <namespacedescription>softpro dept</namespacedescription> <refid1>one</refid1> </namespace> Failure HTTP Status Code: 404 Response Body: The specified Namespace with ID 3 was not found Get Namespaces by Vendor (Deprecated) Retrieve the list of Namespaces available in a vendorid. Method Type GET URI v71/ws/vendor/{vendorid}/namespace.ws URI Parameters Parameter Description Type vendorid Identifier of the Vendor in the database. Integer Sample Request Not applicable. Sample Response Success HTTP Status Code: 200 Response Body:

26 18 Chapter 4: Web Service Interfaces <listresponse type="namespace" count="3"> <instance id="11" name="softpro" refid1="1231" /> <instance id="8" name="compusol" refid1="1123" /> <instance id="1" name="hardware" refid1="1345" /> </listresponse> Failure HTTP Status Code: 404 Response Body: The specified Vendor with ID 7 was not found Sample XML for Namespace Web Services <namespace> <namespacename>driversoftware</namespacename> <namespacedescription>all driver software</namespacedescription> <refid1>r225</refid1> </namespace> 4.3. Viewing License Model Details This section lists the web services available for retrieving license models and their details for given query parameters. The following web services are provided: "Retrieve License Model by ID" on page 18 "Retrieve All License Models" on page Retrieve License Model by ID Retrieve the license model details for a given License Model ID. Method Type GET URI v71/ws/licensemodel/{licensemodelid}.ws URI Parameters Parameter Description Type licensemodelid Identifier of the License Model in the database. Integer (>0) Sample Response Success HTTP Status Code: 200 Response Body: <licensemodel> <licensemodelid>1</licensemodelid> <licensemodelname>execution Count</licenseModelName>

27 <licensetype>0</licensetype> <lmattribute> <attribute> <attributeid>8</attributeid> <attributename>remote_desktop_access</attributename> <attributetype>4</attributetype> <attributedefaultvalue></attributedefaultvalue> <displayorder>8</displayorder> <attributelevel>1</attributelevel> <associatedlockcriteria></associatedlockcriteria> <associatedlockcriteriavalue></associatedlockcriteriavalue> <enduserpermission>0</enduserpermission> <parametergroupname>accessibility</parametergroupname> <parametersubgroupname></parametersubgroupname> <isvpermission>write</isvpermission> <nullable>false</nullable> <saotallowed>false</saotallowed> </attribute> <attributevalue>false</attributevalue> <saot>false</saot> </lmattribute> <lmattribute> <attribute> <attributeid>5</attributeid> <attributename>enable_concurrency</attributename> <attributetype>4</attributetype> <attributedefaultvalue></attributedefaultvalue> <displayorder>5</displayorder> <attributelevel>1</attributelevel> <associatedlockcriteria></associatedlockcriteria> <associatedlockcriteriavalue></associatedlockcriteriavalue> <enduserpermission>0</enduserpermission> <parametergroupname>concurrency</parametergroupname> <parametersubgroupname></parametersubgroupname> <isvpermission>write</isvpermission> <nullable>false</nullable> <saotallowed>false</saotallowed> </attribute> <attributevalue>false</attributevalue> <saot>false</saot> </lmattribute> <lmattribute> <attribute> <attributeid>11</attributeid> <attributename>virtual_machine_access</attributename> <attributetype>4</attributetype> <attributedefaultvalue></attributedefaultvalue> <displayorder>11</displayorder> <attributelevel>1</attributelevel> <associatedlockcriteria></associatedlockcriteria> <associatedlockcriteriavalue></associatedlockcriteriavalue> <enduserpermission>0</enduserpermission> <parametergroupname>accessibility</parametergroupname> <parametersubgroupname></parametersubgroupname> <isvpermission>write</isvpermission> <nullable>false</nullable> <saotallowed>false</saotallowed> </attribute> <attributevalue>true</attributevalue> <saot>false</saot> 4.3. Viewing License Model Details 19

28 20 Chapter 4: Web Service Interfaces </lmattribute> <lmattribute> <attribute> <attributeid>9</attributeid> <attributename>network_enabled</attributename> <attributetype>4</attributetype> <attributedefaultvalue></attributedefaultvalue> <displayorder>9</displayorder> <attributelevel>1</attributelevel> <associatedlockcriteria></associatedlockcriteria> <associatedlockcriteriavalue></associatedlockcriteriavalue> <enduserpermission>0</enduserpermission> <parametergroupname>accessibility</parametergroupname> <parametersubgroupname></parametersubgroupname> <isvpermission>write</isvpermission> <nullable>false</nullable> <saotallowed>false</saotallowed> </attribute> <attributevalue>false</attributevalue> <saot>false</saot> </lmattribute> <lmattribute> <attribute> <attributeid>1</attributeid> <attributename>license_type</attributename> <attributetype>7</attributetype> <attributevaluechoice> <valueoption>time Period</valueOption> <valueoption>executions</valueoption> <valueoption>expiration Date</valueOption> <valueoption>perpetual</valueoption> </attributevaluechoice> <attributedefaultvalue></attributedefaultvalue> <displayorder>1</displayorder> <attributelevel>1</attributelevel> <associatedlockcriteria></associatedlockcriteria> <associatedlockcriteriavalue></associatedlockcriteriavalue> <enduserpermission>0</enduserpermission> <parametergroupname>license Terms</parameterGroupName> <parametersubgroupname></parametersubgroupname> <isvpermission>write</isvpermission> <nullable>false</nullable> <saotallowed>true</saotallowed> </attribute> <attributevalue>1</attributevalue> <saot>true</saot> </lmattribute> <lmattribute> <attribute> <attributeid>7</attributeid> <attributename>count_criteria</attributename> <attributetype>7</attributetype> <attributevaluechoice> <valueoption>login</valueoption> <valueoption>process</valueoption> <valueoption>station</valueoption> </attributevaluechoice> <attributedefaultvalue></attributedefaultvalue> <displayorder>7</displayorder> <attributelevel>1</attributelevel>

29 4.3. Viewing License Model Details 21 <associatedlockcriteria></associatedlockcriteria> <associatedlockcriteriavalue></associatedlockcriteriavalue> <enduserpermission>0</enduserpermission> <parametergroupname>concurrency</parametergroupname> <parametersubgroupname></parametersubgroupname> <isvpermission>write</isvpermission> <nullable>false</nullable> <saotallowed>false</saotallowed> </attribute> <attributevalue>0</attributevalue> <saot>false</saot> </lmattribute> <lmattribute> <attribute> <attributeid>2</attributeid> <attributename>execution_count</attributename> <attributetype>3</attributetype> <attributedefaultvalue></attributedefaultvalue> <displayorder>2</displayorder> <attributelevel>1</attributelevel> <associatedlockcriteria></associatedlockcriteria> <associatedlockcriteriavalue></associatedlockcriteriavalue> <enduserpermission>0</enduserpermission> <parametergroupname>license Terms</parameterGroupName> <parametersubgroupname></parametersubgroupname> <isvpermission>write</isvpermission> <nullable>false</nullable> <saotallowed>true</saotallowed> </attribute> <attributevalue>1</attributevalue> <saot>true</saot> </lmattribute> <lmattribute> <attribute> <attributeid>6</attributeid> <attributename>concurrent_instances</attributename> <attributetype>6</attributetype> <attributedefaultvalue></attributedefaultvalue> <displayorder>6</displayorder> <attributelevel>1</attributelevel> <associatedlockcriteria></associatedlockcriteria> <associatedlockcriteriavalue></associatedlockcriteriavalue> <enduserpermission>0</enduserpermission> <parametergroupname>concurrency</parametergroupname> <parametersubgroupname></parametersubgroupname> <isvpermission>write</isvpermission> <nullable>false</nullable> <saotallowed>true</saotallowed> </attribute> <attributevalue> </attributevalue> <saot>true</saot> </lmattribute> </licensemodel> Failure HTTP Status Code: 404 (Not Found) Response Body: The License Model does not exist.

30 22 Chapter 4: Web Service Interfaces Retrieve All License Models Retrieve the license model details for a given License Model ID. Method Type GET URI v71/ws/enforcement/{enforcementid}/licensemodel.ws URI Parameters Parameter Description Type enforcementid Identifier of the Enforcement in the database. Integer ( >0) Sample Response Success HTTP Status Code: 200 Response Body: <listresponse type="licensemodel" count="6"> <instance id="1" name="execution Count"/> <instance id="2" name="expiration Date"/> <instance id="4" name="perpetual"/> <instance id="6" name="provisional (Perpetual)"/> <instance id="5" name="provisional (Time Period)"/> <instance id="3" name="time Period"/> </listresponse> Failure HTTP Status Code: 404 Response Body: The specified Enforcement with ID 434 does not exist Features This section provides information about the web services available to manage Features. The following interfaces are available for Feature: Method URI Template Description GET v71/ws/feature/{featureid}.ws Retrieve Feature details by ID v71/ws/vendor/{vendorid}/feature.ws PUT v71/ws/vendor/{vendorid}/feature.ws Create a Feature Search Features for given parameters POST v71/ws/feature/{featureid}.ws Edit Feature properties DELETE v71/ws/feature/{featureid}.ws Delete a Feature Deprecated web services PUT v71/ws/vendor/{vendorid}/namespace/ Create a Feature (deprecated in

31 4.4. Features 23 Method URI Template GET Description {namespaceid}/feature.ws Sentinel EMS 6.3) v71/ws/vendor/{vendorid}/namespace/ {namespaceid}/feature.ws Retrieve Features by Vendor and Namespace (Deprecated) Create a Feature for a Given Vendor ID Create a new Feature for specified Vendor. Method Type PUT URI v71/ws/vendor/{vendorid}/feature.ws URI Parameters Parameter Description Type vendorid Identifier of the Vendor in the database. Integer Sample Request See "Sample XML for Feature Web Services" on page 28. The XML must comply with the schema provided for Feature (see "XSD for Feature Web Services" on page 113). Sample Response Success HTTP Status Code: 201 Header-Location: feature ID Failure HTTP Status Code: 404 Response Body: The Vendor ID is wrong Create a Feature for Given Vendor ID and Namespace (Deprecated) Create a new Feature for specified Vendor and Namespace. Method Type PUT URI v71/ws/vendor/{vendorid}/namespace/{namespaceid}/feature.ws URI Parameters Parameter Description Type vendorid Identifier of the Vendor in the database. Integer namespaceid Identifier of the Namespace in the database Integer

32 24 Chapter 4: Web Service Interfaces Sample Request See "Sample XML for Feature Web Services" on page 28. The XML must comply with the schema provided for Feature (see "XSD for Feature Web Services" on page 113). Sample Response Success HTTP Status Code: 201 Header-Location: feature ID Failure HTTP Status Code: 404 Response Body: The specified Namespace with ID 11 was not found Edit Feature Properties Edit the properties of a Feature. Consider the following points before editing a Feature: If the Feature is not deployed (not included in a Product yet), you can edit the Feature properties like Name, Feature ID, Ref IDs, and Description. If the Feature is deployed (included in one or more Products), you can change only the Ref IDs and Description. Method Type POST URI v71/ws/feature/{featureid}.ws URI Parameters Parameter Description Type featureid The feature ID. Integer Sample Request See "Sample XML for Feature Web Services" on page 28. The XML must comply with the schema provided for Feature (see "XSD for Feature Web Services" on page 113). Sample Response Success HTTP Status Code: 200 Response Body:

33 4.4. Features 25 <feature> <featurename>print</featurename> <featuredescription>printing software</featuredescription> <refid1>crm25</refid1> <featureidentifier>10</featureidentifier> </feature> Failure HTTP Status Code: 404 Response Body: The specified Feature with ID 11 was not found Delete Feature Delete a feature for a given Feature ID. Method Type DELETE URI v71/ws/feature/{featureid}.ws URI Parameters Parameter Description Type featureid Identifier of the Feature in the database. Integer Sample Request Not applicable. Sample Response Success HTTP Status Code: 204 Header-Location: Deleted Failure HTTP Status Code: 404 Response Body: not found Retrieve Feature Details by ID Retrieve the details of a Feature for a given Feature ID. Method Type GET URI v71/ws/feature/{featureid}.ws URI Parameters Parameter Description Type featureid The Feature ID. Integer

34 26 Chapter 4: Web Service Interfaces Sample Response Success HTTP Status Code: 200 Response Body: <feature> <featurename>feature10</featurename> <featuredescription>commercial</featuredescription> <refid1></refid1> <refid2></refid2> <featureidentifier>5</featureidentifier> </feature> Failure HTTP Status Code: 404 Response Body: The specified Feature with ID 1 was not found Search Features Search Features in a vendorid for the given parameters. Method Type GET URI /v71/ws/vendor/{vendorid}/feature.ws?featurename={featurename} &refid1={refid1} &refid2={refid2} Example URL: &refid2=crmn35 URI Parameters Parameter Description Type vendorid Identifier of the Vendor in the database. Integer featurename (Optional) Feature name. String refid1 (Optional) Reference ID 1. Identifier of the Feature in another system like CRM/ERP. String refid2 (Optional) Reference ID 2. String Sample Request Not applicable.

35 4.4. Features 27 Sample Response Success HTTP Status Code: 200 Response Body <listresponse type="feature" count="8"> <instance id="15" name="feature sample name13" identifier="8" /> <instance id="13" name="feature sample name11" identifier="7" /> <instance id="11" name="feature sample name9" identifier="6" /> <instance id="9" name="feature sample name7" identifier="5" /> <instance id="7" name="feature sample name6" identifier="4" /> <instance id="6" name="feature sample name16" identifier="3" /> <instance id="5" name="feature sample name1" identifier="2" /> <instance id="1" name="feature sample name0" identifier="1" /> </listresponse> Failure HTTP Status Code: 401 Response Body: You should log on first Retrieve All Features by Vendor and Namespace (Deprecated) Retrieve a list Features for given Vendor ID and Namespace ID. Method Type GET URI v71/ws/vendor/{vendorid}/namespace/{namespaceid}/feature.ws URI Parameters Parameter Description Type vendorid Identifier of the Vendor in the database. Integer namespaceid Identifier of the Namespace in the database Integer Sample Request Not applicable. Sample Response Success HTTP Status Code: 200 Response Body <listresponse type="feature" count="3"> <instance id="4" name="print" identifier="4"/>

36 28 Chapter 4: Web Service Interfaces <instance id="3" name="scan" identifier="3"/> <instance id="2" name="copy" identifier="2"/> </listresponse> Failure HTTP Status Code: 404 Response Body: The specified Namespace with ID 54 was not found Sample XML for Feature Web Services <feature> <featurename><![cdata[feature Name]]></featureName> <featureidentifier>22</featureidentifier> <featuredescription></featuredescription> <refid1>one</refid1> <refid2>two</refid2> </feature> 4.5. Products This section provides information about the web services available to manage Products. The following interfaces are supported for the Product resource: Method URI Template Description GET v71/ws/product/{productid}.ws Retrieve Product details v71/ws/vendor/{vendorid}/product.ws Search Products PUT v71/ws/vendor/{vendorid}/product.ws Create a Product POST v71/ws/product/{productid}.ws Edit Product details DELETE v71/ws/product/{productid}.ws Delete a Product Deprecated web services PUT GET v71/ws/vendor/{vendorid}/namespace/ {namespaceid}/product.ws v71/ws/vendor/{vendorid}/namespace/ {namespaceid}/product.ws Create a Product (Deprecated) Search Products by Vendor and Namespace (Deprecated) Create Product for Vendor ID Create a new Product for specified Vendor. Method Type PUT URI v71/ws/vendor/{vendorid}/product.ws

37 4.5. Products 29 URI Parameters Parameter Description Type vendorid Sample Request Identifier of the Vendor in the database. Integer See "Sample XML for Product Web Services" on page 43. The XML element names are selfexplanatory. However, some of the important elements are as follows: The XML must comply with the schema provided for Product (see "XSD for Product Web Services" on page 114). XML Elements Description Type baseproductid For Modification and Cancellation Products, provide the productid of the Base Product. productidentifier enforcement ProductType memorysegment For Base Products, set the value to 0 or remove this tag. Required only for Modification and Cancellation Products. The system generates an unique identifier for the Product (i.e., the Sentinel LDK Product ID) if you leave this blank or remove the tag from the XML. To provide a different identifier instead, provide a value for this. (Required) The Product type. Valid values: BASE, MODIFICATION, or CANCELLATION Default: BASE (Optional) Specify memory data for the Product. It contains the following elements: name, description, text, size, offset, color, saot, and memorytype. Following are some important elements: text Specify as BASE 16 (hexadecimal) encoded string. saot Can the memory data be specified during Entitlement generation? Valid values: TRUE/FALSE memorytype Read-write (1) or Read-only (2). offset The starting point of the memory segment. Always provide this value in hexadecimal. Example of memory segment in a Product XML: String Integer String <memorysegment> <name></name> <description></description> <text> </text>

38 30 Chapter 4: Web Service Interfaces XML Elements Description Type <size>5</size> <offset>0x0000</offset> <color>#8b008b</color> <saot>true</saot> <memorytype> <id>1</id> </memorytype> </memorysegment> enforcementid (Optional) The enforcement technology, for example, Sentinel Cloud or Sentinel LDK. Valid values: 1 - Sentinel LDK; 2- Sentinel Cloud Default: 1 upgradetodriverless (Optional) Enable to upgrade from Sentinel HL keys to HID keys. Integer Boolean Sample Response Success HTTP Status Code: 201 Header-Location: {product Id} Failure HTTP Status Code: 404 Response Body: The Vendor ID is wrong Create Product for Vendor ID and Namespace (Deprecated) Create a new Product for specified Vendor and Namespace. Method Type PUT URI v71/ws/vendor/{vendorid}/namespace/{namespaceid}/product.ws URI Parameters Parameter Description Type vendorid Identifier of the Vendor in the database. Integer namespaceid Identifier of the Namespace in the database Integer Sample Request See "Sample XML for Product Web Services" on page 43. The XML element names are selfexplanatory. However, some of the important elements are as follows:

39 4.5. Products 31 The XML must comply with the schema provided for Product (see "XSD for Product Web Services" on page 114). XML Elements Description Type baseproductid For Modification and Cancellation Products, provide the productid of the Base Product. productidentifier enforcement ProductType For Base Products, set the value to 0 or remove this tag. Required only for Modification and Cancellation Products. The system generates an unique identifier for the Product (i.e., the Sentinel LDK Product ID) if you leave this blank or remove the tag from the XML. To provide a different identifier instead, provide a value for this. (Required) The Product type. Valid values: BASE, MODIFICATION, or CANCELLATION Default: BASE memorysegment (Optional) Specify memory data for the Product. It contains the following elements: name, description, text, size, offset, color, saot, and memorytype. Following are some important elements: text Specify as BASE 16 (hexadecimal) encoded string. saot Can the memory data be specified during Entitlement generation? Valid values: TRUE/FALSE memorytype Read-write (1) or Read-only (2). offset The starting point of the memory segment. Always provide this value in hexadecimal. Example of memory segment in a Product XML: String Integer String <memorysegment> <name></name> <description></description> <text> </text> <size>5</size> <offset>0x0000</offset> <color>#8b008b</color> <saot>true</saot> <memorytype> <id>1</id> </memorytype> </memorysegment>

40 32 Chapter 4: Web Service Interfaces Sample Response Success HTTP Status Code: 201 Header-Location: {product Id} Failure HTTP Status Code: 404 Response Body: The specified Namespace with ID 11 was not found Edit Product Properties Edit the properties of a Product. Consider the following points before editing: If the Product is not deployed (not included in a Entitlement yet), you can edit the Product properties like Name, Product ID, Ref IDs, and Description. If the Product is deployed (included in one or more Entitlements), you can change only the Ref IDs and Description. Method Type POST URI v71/ws/product/{productid}.ws URI Parameters Parameter Description Type productid Identifier of the Product as stored in database. Integer Sample Request See "Sample XML for Product Web Services" on page 43. The XML element names are selfexplanatory. However, some of the important elements are as follows: The XML must comply with the schema provided for Product (see "XSD for Product Web Services" on page 114). XML Elements Description Type baseproductid For Modification and Cancellation Products, provide the productid of the Base Product. productidentifier For Base Products, set the value to 0 or remove this tag. Required only for Modification and Cancellation Products. The system generates an unique identifier for the Product (i.e., the Sentinel LDK Product ID) if you leave this blank or remove the tag from the XML. To provide a different identifier instead, provide a value for this. String Integer enforcement (Required) The Product type. String

41 4.5. Products 33 XML Elements Description Type ProductType memorysegment Valid values: BASE, MODIFICATION, or CANCELLATION Default: BASE (Optional) Specify memory data for the Product. It contains the following elements: name, description, text, size, offset, color, saot, and memorytype. Following are some important elements: text Specify as BASE 16 (hexadecimal) encoded string. saot Can the memory data be specified during Entitlement generation? Valid values: TRUE/FALSE memorytype Read-write (1) or Read-only (2). offset The starting point of the memory segment. Always provide this value in hexadecimal. Example of memory segment in a Product XML: <memorysegment> <name></name> <description></description> <text> </text> <size>5</size> <offset>0x0000</offset> <color>#8b008b</color> <saot>true</saot> <memorytype> <id>1</id> </memorytype> </memorysegment> enforcementid (Optional) The enforcement technology, for example, Sentinel Cloud or Sentinel LDK. Valid values: 1 - Sentinel LDK; 2- Sentinel Cloud Default: 1 upgradetodriverless (Optional) Enable to upgrade from Sentinel HL keys to HID keys. Integer Boolean Sample Response Success HTTP Status Code: 200 Response Body: <product> <productname>updateproductwsxcvb :25</productName> <baseproductid>0</baseproductid>

42 34 Chapter 4: Web Service Interfaces <productidentifier>0</productidentifier> <enforcementproducttype>base</enforcementproducttype> <enforcementprotectiontype>hl</enforcementprotectiontype> <productdescription>demo test</productdescription> <refid1></refid1> <refid2></refid2> <productfeaturerefs> <productfeatureref> <actionname>none</actionname> <featureid>1</featureid> <productfeaturelicensemodel> <actionname>none</actionname> <licensemodel> <lmattributes> <lmattribute> <attribute> <attributeid>9</attributeid> <attributename>network_enabled</attributename> <associatedlockcriteria></associatedlockcriteria> <associatedlockcriteriavalue></associatedlockcriteriavalue> <attributetype>4</attributetype> <attributedefaultvalue></attributedefaultvalue> <displayorder>9</displayorder> <enduserpermission>0</enduserpermission> <associatedattributemaster></associatedattributemaster> <sameattributemaster></sameattributemaster> <sameattributepriority>0</sameattributepriority> <parametergroupname>accessibility</parametergroupname> <parametersubgroupname></parametersubgroupname> <isvpermission>write</isvpermission> <nullable>false</nullable> <soatallowed>false</soatallowed> </attribute> <attributevalue>true</attributevalue> <saot>false</saot> </lmattribute> <lmattribute> <attribute> <attributeid>6</attributeid> <attributename>concurrent_instances</attributename> <associatedlockcriteria></associatedlockcriteria> <associatedlockcriteriavalue></associatedlockcriteriavalue> <attributetype>6</attributetype> <attributedefaultvalue></attributedefaultvalue> <displayorder>6</displayorder> <enduserpermission>0</enduserpermission>

43 4.5. Products 35 <associatedattributemaster></associatedattributemaster> <sameattributemaster></sameattributemaster> <sameattributepriority>0</sameattributepriority> <parametergroupname>concurrency</parametergroupname> <parametersubgroupname></parametersubgroupname> <isvpermission>write</isvpermission> <nullable>false</nullable> <soatallowed>ture</soatallowed> </attribute> <attributevalue> </attributevalue> <saot>false</saot> </lmattribute> </lmattributes> </licensemodel> </productfeaturelicensemodel> <lmstatus>2</lmstatus> <status>0</status> </productfeatureref> </productfeaturerefs> </product> Failure HTTP Status Code: 404 Response Body: product does not exist Delete Product Delete a Product for a given Product ID. Method Type DELETE URI v71/ws/product/{productid}.ws URI Parameters Parameter Description Type productid Specify the Product ID. Integer Sample Response Success HTTP Status Code: 204 Header-Location: Deleted Failure HTTP Status Code: 404 Response Body: Product not found.

44 36 Chapter 4: Web Service Interfaces Retrieve Product Details Retrieve the details of a Product for a given Product ID. Method Type GET URI v71/ws/product/{productid}.ws URI Parameters Parameter Description Type productid The product ID. Integer Sample Response Success HTTP Status Code: 200 Response Body <product> <productname>updateproductwsxcvb :25</productName> <baseproductid>0</baseproductid> <productidentifier>0</productidentifier> <enforcementproducttype>base</enforcementproducttype> <enforcementprotectiontype>hl</enforcementprotectiontype> <cloneprotection>true</cloneprotection> <productdescription>sjdgsjkdsjkdhsk</productdescription> <refid1></refid1> <refid2></refid2> <productfeaturerefs> <productfeatureref> <actionname>none</actionname> <featureid>1</featureid> <productfeaturelicensemodel> <actionname>none</actionname> <licensemodel> <lmattributes> <lmattribute> <attribute> <attributeid>9</attributeid> <attributename>network_enabled</attributename> <associatedlockcriteria></associatedlockcriteria> <associatedlockcriteriavalue></associatedlockcriteriavalue> <attributetype>4</attributetype> <attributedefaultvalue></attributedefaultvalue> <displayorder>9</displayorder> <enduserpermission>0</enduserpermission> <associatedattributemaster></associatedattributemaster> <sameattributemaster></sameattributemaster>

45 4.5. Products 37 <sameattributepriority>0</sameattributepriority> <parametergroupname>accessibility</parametergroupname> <parametersubgroupname></parametersubgroupname> <isvpermission>write</isvpermission> <nullable>false</nullable> <soatallowed>false</soatallowed> </attribute> <attributevalue>true</attributevalue> <saot>false</saot> </lmattribute> <lmattribute> <attribute> <attributeid>6</attributeid> <attributename>concurrent_instances</attributename> <associatedlockcriteria></associatedlockcriteria> <associatedlockcriteriavalue></associatedlockcriteriavalue> <attributetype>6</attributetype> <attributedefaultvalue></attributedefaultvalue> <displayorder>6</displayorder> <enduserpermission>0</enduserpermission> <associatedattributemaster></associatedattributemaster> <sameattributemaster></sameattributemaster> <sameattributepriority>0</sameattributepriority> <parametergroupname>concurrency</parametergroupname> <parametersubgroupname></parametersubgroupname> <isvpermission>write</isvpermission> <nullable>false</nullable> <soatallowed>ture</soatallowed> </attribute> <attributevalue> </attributevalue> <saot>false</saot> </lmattribute> <lmattribute> <attribute> <attributeid>7</attributeid> <attributename>count_criteria</attributename> <associatedlockcriteria></associatedlockcriteria> <associatedlockcriteriavalue></associatedlockcriteriavalue> <attributetype>7</attributetype> <attributedefaultvalue></attributedefaultvalue> <displayorder>7</displayorder> <enduserpermission>0</enduserpermission> <associatedattributemaster></associatedattributemaster> <sameattributemaster></sameattributemaster> <sameattributepriority>0</sameattributepriority> <parametergroupname>concurrency</parametergroupname>

46 38 Chapter 4: Web Service Interfaces <parametersubgroupname></parametersubgroupname> <isvpermission>write</isvpermission> <nullable>false</nullable> <soatallowed>false</soatallowed> </attribute> <attributevalue>0</attributevalue> <saot>false</saot> </lmattribute> <lmattribute> <attribute> <attributeid>5</attributeid> <attributename>enable_concurrency</attributename> <associatedlockcriteria></associatedlockcriteria> <associatedlockcriteriavalue></associatedlockcriteriavalue> <attributetype>4</attributetype> <attributedefaultvalue></attributedefaultvalue> <displayorder>5</displayorder> <enduserpermission>0</enduserpermission> <associatedattributemaster></associatedattributemaster> <sameattributemaster></sameattributemaster> <sameattributepriority>0</sameattributepriority> <parametergroupname>concurrency</parametergroupname> <parametersubgroupname></parametersubgroupname> <isvpermission>write</isvpermission> <nullable>false</nullable> <soatallowed>false</soatallowed> </attribute> <attributevalue>false</attributevalue> <saot>false</saot> </lmattribute> <lmattribute> <attribute> <attributeid>11</attributeid> <attributename>virtual_machine_access</attributename> <associatedlockcriteria></associatedlockcriteria> <associatedlockcriteriavalue></associatedlockcriteriavalue> <attributetype>4</attributetype> <attributedefaultvalue></attributedefaultvalue> <displayorder>11</displayorder> <enduserpermission>0</enduserpermission> <associatedattributemaster></associatedattributemaster> <sameattributemaster></sameattributemaster> <sameattributepriority>0</sameattributepriority> <parametergroupname>accessibility</parametergroupname> <parametersubgroupname></parametersubgroupname> <isvpermission>write</isvpermission>

47 <nullable>false</nullable> <soatallowed>false</soatallowed> </attribute> <attributevalue>true</attributevalue> <saot>false</saot> </lmattribute> <lmattribute> <attribute> <attributeid>10</attributeid> <attributename>detachable</attributename> <associatedlockcriteria></associatedlockcriteria> <associatedlockcriteriavalue></associatedlockcriteriavalue> <attributetype>4</attributetype> <attributedefaultvalue></attributedefaultvalue> <displayorder>10</displayorder> <enduserpermission>0</enduserpermission> <associatedattributemaster></associatedattributemaster> <sameattributemaster></sameattributemaster> <sameattributepriority>0</sameattributepriority> <parametergroupname>concurrency</parametergroupname> <parametersubgroupname></parametersubgroupname> <isvpermission>write</isvpermission> <nullable>false</nullable> <soatallowed>false</soatallowed> </attribute> <attributevalue>false</attributevalue> <saot>false</saot> </lmattribute> <lmattribute> <attribute> <attributeid>1</attributeid> <attributename>license_type</attributename> <associatedlockcriteria></associatedlockcriteria> <associatedlockcriteriavalue></associatedlockcriteriavalue> <attributetype>7</attributetype> <attributedefaultvalue></attributedefaultvalue> <displayorder>1</displayorder> <enduserpermission>0</enduserpermission> <associatedattributemaster></associatedattributemaster> <sameattributemaster></sameattributemaster> <sameattributepriority>0</sameattributepriority> <parametergroupname>license Terms</parameterGroupName> <parametersubgroupname></parametersubgroupname> <isvpermission>write</isvpermission> <nullable>false</nullable> <soatallowed>ture</soatallowed> 4.5. Products 39

48 40 Chapter 4: Web Service Interfaces </attribute> <attributevalue>1</attributevalue> <saot>false</saot> </lmattribute> <lmattribute> <attribute> <attributeid>2</attributeid> <attributename>execution_count</attributename> <associatedlockcriteria></associatedlockcriteria> <associatedlockcriteriavalue></associatedlockcriteriavalue> <attributetype>3</attributetype> <attributedefaultvalue></attributedefaultvalue> <displayorder>2</displayorder> <enduserpermission>0</enduserpermission> <associatedattributemaster></associatedattributemaster> <sameattributemaster></sameattributemaster> <sameattributepriority>0</sameattributepriority> <parametergroupname>license Terms</parameterGroupName> <parametersubgroupname></parametersubgroupname> <isvpermission>write</isvpermission> <nullable>false</nullable> <soatallowed>ture</soatallowed> </attribute> <attributevalue>1</attributevalue> <saot>false</saot> </lmattribute> <lmattribute> <attribute> <attributeid>8</attributeid> <attributename>remote_desktop_access</attributename> <associatedlockcriteria></associatedlockcriteria> <associatedlockcriteriavalue></associatedlockcriteriavalue> <attributetype>4</attributetype> <attributedefaultvalue></attributedefaultvalue> <displayorder>8</displayorder> <enduserpermission>0</enduserpermission> <associatedattributemaster></associatedattributemaster> <sameattributemaster></sameattributemaster> <sameattributepriority>0</sameattributepriority> <parametergroupname>accessibility</parametergroupname> <parametersubgroupname></parametersubgroupname> <isvpermission>write</isvpermission> <nullable>false</nullable> <soatallowed>false</soatallowed> </attribute> <attributevalue>true</attributevalue>

49 4.5. Products 41 <saot>false</saot> </lmattribute> </lmattributes> </licensemodel> </productfeaturelicensemodel> <lmstatus>2</lmstatus> <status>0</status> </productfeatureref> </productfeaturerefs> </product> Failure HTTP Status Code: 404 Response Body: The specified Product with ID 5 was not found Search Products Search the list of Products in a vendorid by the provided parameters. Method Type GET URI /v71/ws/vendor/{vendorid}/product.ws?productname={productname} &lifecyclestage={lifecyclestage} &refid1={refid1} &refid2={refid2} Example URL: /ws/vendor/1/product.ws?productname=print&lifecyclestage=complete&refid1=crm15 &refid2=crmn35 URI Parameters Parameter Description Type vendorid Identifier of the Vendor in the database. Integer productname (Optional) Product name. String refid1 (Optional) Reference ID 1. Identifier of the Product in another system Like CRM/ERP. String refid2 (Optional) Reference ID 2. String identifier System generated unique identifier for the Product. Integer lifecyclestage (Optional) Status of the Product. String enforcementid Identifier of the Enforcement in the database. Integer

50 42 Chapter 4: Web Service Interfaces Sample Response Success HTTP Status Code: 200 Response Body <listresponse type="product" count="4"> <instance id="50" name="vvvvvvvv" identifier="34" type="base" lifecyclestage="commit" descr="" cloneprotection="true" refid1="" locktype="sl-adminmode" enabled="true" deployed="true"/> <instance id="20" name="mynewprd" identifier="16" type="base" lifecyclestage="commit" descr="" cloneprotection="false" refid1="" locktype="sl-adminmode" enabled="true" deployed="true"/> <instance id="21" name="modprd" identifier="16" type="modification" lifecyclestage="commit" de scr="" cloneprotection="true" refid1="" locktype="sl-adminmode" enabled="true" deployed="fals e"/> <instance id="11" name="mybassss" identifier="7" type="base" lifecyclestage="commit" descr="" cloneprotection="true" refid1="" locktype="sl-adminmode" enabled="true" deployed="true"/> </listresponse> Failure HTTP Status Code: 404 Response Body: The specified Vendor with ID 4 was not found Search Products by Vendor and Namespace (Deprecated) Retrieve a list Products for given Vendor ID and Namespace ID. Method Type GET URI v71/ws/vendor/{vendorid}/namespace/{namespaceid}/product.ws URI Parameters Parameter Description Type vendorid Identifier of the Vendor in the database. Integer namespaceid Identifier of the Namespace in the database Integer Sample Response Success HTTP Status Code: 200 Response Body <listresponse type="product" count="12"> <instance id="17" name="um_1" identifier="15" type="base" lifecyclestage="commit"/> <instance id="10" name="ttt" identifier="8" type="base" lifecyclestage="commit"/> <instance id="11" name="ttt2" identifier="8" type="provisional" lifecyclestage="commit"/>

51 4.5. Products 43 <instance id="16" name="prdslusermode" identifier="12" type="base" lifecyclestage="commit"/> <instance id="15" name="prdsladminmode" identifier="11" type="base" lifecyclestage="commi t"/> <instance id="19" name="prdhlsladminsluser" identifier="14" type="base" lifecyclestage="com mit"/> <instance id="18" name="prdhlsladminmode" identifier="13" type="base" lifecyclestage="commi t"/> <instance id="9" name="prd8" identifier="7" type="base" lifecyclestage="commit"/> <instance id="4" name="prd5" identifier="5" type="base" lifecyclestage="commit"/> <instance id="7" name="prdp1" identifier="5" type="provisional" lifecyclestage="commit"/> <instance id="14" name="one_more2" identifier="10" type="base" lifecyclestage="draft"/> <instance id="12" name="one_more" identifier="9" type="base" lifecyclestage="commit"/> Failure HTTP Status Code: 404 Response Body: Invalid Namespace ID Sample XML for Product Web Services <product> <productname><![cdata[print]]></productname> <baseproductid>0</baseproductid> <productidentifier>231</productidentifier> <lifecyclestage>draft</lifecyclestage> <enforcementproducttype>base</enforcementproducttype> <enforcementprotectiontype>hl_or_sl_adminmode_or_sl_usermode</enforcementprotectiontype> <rehost>enable</rehost> <productdescription>9999</productdescription> <refid1></refid1> <refid2></refid2> <productfeatureref> <featureid>1</featureid> <actionname>none</actionname> <productfeaturelicensemodel> <actionname>none</actionname> <licensemodel> <licensemodelid>1</licensemodelid> <licensemodelname>hasp Execution Count</licenseModelName> <licensetype>0</licensetype> <lmattribute> <attribute> <attributeid>1</attributeid> <attributename>license_type</attributename> <attributetype>7</attributetype> <attributevaluechoice> <valueoption>time Period</valueOption> <valueoption>executions</valueoption> <valueoption>expiration Date</valueOption> <valueoption>perpetual</valueoption> </attributevaluechoice> <attributedefaultvalue></attributedefaultvalue> <displayorder>1</displayorder> <attributelevel>1</attributelevel> <associatedlockcriteria></associatedlockcriteria>

52 44 Chapter 4: Web Service Interfaces <associatedlockcriteriavalue></associatedlockcriteriavalue> <enduserpermission>0</enduserpermission> <parametergroupname>license Terms</parameterGroupName> <parametersubgroupname></parametersubgroupname> <isvpermission>write</isvpermission> <nullable>false</nullable> <saotallowed>true</saotallowed> </attribute> <attributevalue>1</attributevalue> <saot>false</saot> </lmattribute> <lmattribute> <attribute> <attributeid>5</attributeid> <attributename>enable_concurrency</attributename> <attributetype>4</attributetype> <attributedefaultvalue></attributedefaultvalue> <displayorder>5</displayorder> <attributelevel>1</attributelevel> <associatedlockcriteria></associatedlockcriteria> <associatedlockcriteriavalue></associatedlockcriteriavalue> <enduserpermission>0</enduserpermission> <parametergroupname>concurrency</parametergroupname> <parametersubgroupname></parametersubgroupname> <isvpermission>write</isvpermission> <nullable>false</nullable> <saotallowed>false</saotallowed> </attribute> <attributevalue>false</attributevalue> <saot>false</saot> </lmattribute> <lmattribute> <attribute> <attributeid>11</attributeid> <attributename>virtual_machine_access</attributename> <attributetype>4</attributetype> <attributedefaultvalue></attributedefaultvalue> <displayorder>11</displayorder> <attributelevel>1</attributelevel> <associatedlockcriteria></associatedlockcriteria> <associatedlockcriteriavalue></associatedlockcriteriavalue> <enduserpermission>0</enduserpermission> <parametergroupname>accessibility</parametergroupname> <parametersubgroupname></parametersubgroupname> <isvpermission>write</isvpermission> <nullable>false</nullable> <saotallowed>false</saotallowed> </attribute> <attributevalue>true</attributevalue> <saot>false</saot> </lmattribute> <lmattribute> <attribute> <attributeid>8</attributeid> <attributename>remote_desktop_access</attributename> <attributetype>4</attributetype> <attributedefaultvalue></attributedefaultvalue> <displayorder>8</displayorder> <attributelevel>1</attributelevel> <associatedlockcriteria></associatedlockcriteria>

53 <associatedlockcriteriavalue></associatedlockcriteriavalue> <enduserpermission>0</enduserpermission> <parametergroupname>accessibility</parametergroupname> <parametersubgroupname></parametersubgroupname> <isvpermission>write</isvpermission> <nullable>false</nullable> <saotallowed>false</saotallowed> </attribute> <attributevalue>false</attributevalue> <saot>false</saot> </lmattribute> <lmattribute> <attribute> <attributeid>7</attributeid> <attributename>count_criteria</attributename> <attributetype>7</attributetype> <attributevaluechoice> <valueoption>login</valueoption> <valueoption>process</valueoption> <valueoption>station</valueoption> </attributevaluechoice> <attributedefaultvalue>0</attributedefaultvalue> <displayorder>7</displayorder> <attributelevel>1</attributelevel> <associatedlockcriteria></associatedlockcriteria> <associatedlockcriteriavalue></associatedlockcriteriavalue> <enduserpermission>0</enduserpermission> <parametergroupname>concurrency</parametergroupname> <parametersubgroupname></parametersubgroupname> <isvpermission>write</isvpermission> <nullable>false</nullable> <saotallowed>false</saotallowed> </attribute> <attributevalue>0</attributevalue> <saot>false</saot> </lmattribute> <lmattribute> <attribute> <attributeid>2</attributeid> <attributename>execution_count</attributename> <attributetype>3</attributetype> <attributedefaultvalue></attributedefaultvalue> <displayorder>2</displayorder> <attributelevel>1</attributelevel> <associatedlockcriteria></associatedlockcriteria> <associatedlockcriteriavalue></associatedlockcriteriavalue> <enduserpermission>0</enduserpermission> <parametergroupname>license Terms</parameterGroupName> <parametersubgroupname></parametersubgroupname> <isvpermission>write</isvpermission> <nullable>false</nullable> <saotallowed>true</saotallowed> </attribute> <attributevalue>1</attributevalue> <saot>false</saot> </lmattribute> <lmattribute> <attribute> <attributeid>9</attributeid> <attributename>network_enabled</attributename> 4.5. Products 45

54 46 Chapter 4: Web Service Interfaces <attributetype>4</attributetype> <attributedefaultvalue></attributedefaultvalue> <displayorder>9</displayorder> <attributelevel>1</attributelevel> <associatedlockcriteria></associatedlockcriteria> <associatedlockcriteriavalue></associatedlockcriteriavalue> <enduserpermission>0</enduserpermission> <parametergroupname>accessibility</parametergroupname> <parametersubgroupname></parametersubgroupname> <isvpermission>write</isvpermission> <nullable>false</nullable> <saotallowed>false</saotallowed> </attribute> <attributevalue>false</attributevalue> <saot>false</saot> </lmattribute> <lmattribute> <attribute> <attributeid>6</attributeid> <attributename>concurrent_instances</attributename> <attributetype>6</attributetype> <attributedefaultvalue></attributedefaultvalue> <displayorder>6</displayorder> <attributelevel>1</attributelevel> <associatedlockcriteria></associatedlockcriteria> <associatedlockcriteriavalue></associatedlockcriteriavalue> <enduserpermission>0</enduserpermission> <parametergroupname>concurrency</parametergroupname> <parametersubgroupname></parametersubgroupname> <isvpermission>write</isvpermission> <nullable>false</nullable> <saotallowed>true</saotallowed> </attribute> <attributevalue> </attributevalue> <saot>false</saot> </lmattribute> </licensemodel> </productfeaturelicensemodel> <lmstatus>defined</lmstatus> <excludable>false</excludable> </productfeatureref> </product>

55 4.6. Managing Entitlements Managing Entitlements This section lists the web services provided for creating and updating Entitlements. The following interfaces are supported for the Entitlement resource: Method URI Template Description GET v71/ws/entitlement/{entid}.ws Get Entitlement details (XML) by entid v71/ws/entitlement.ws v71/ws/productkey/{productkeyid}.ws Search Entitlements Get Product Key details (XML) PUT v71/ws/entitlement.ws Create an Entitlement POST v71/ws/entitlement/{entid}.ws Update Entitlement details v71/ws/productkey/{productkeyid}.ws Update Product key DELETE v71/ws/entitlement/{entid}.ws Delete an Entitlement Create an Entitlement Create an Entitlement using the parameters provided. Method Type PUT URI v71/ws/entitlement.ws Pre-requisites Before calling this web service, make sure the following: The Products for which the entitlement will be created are available. (Base, Provisional, Modification, or Cancellation.) Entitlement type is decided. o o For On-premise: Product_Key, Hardware_Key, or ProtectionKey_Update. For Cloud: Cloud_Named or Cloud_Unnamed. The required Features or Memory Data are added to the Product(s). License Models are configured for the Feature(s). The Products are in Complete state. Sample Request A basic sample XML is provided at "Sample XML for Entitlement Web Services" on page 63. The XML must comply with the schema provided for Entitlement (see "XSD for Entitlement Web Services" on page 121). The XML element names are self-explanatory. Some of the important elements are as follows: XML Elements Description Type entstate (Optional) Specifies the current status of the Entitlement. String

56 48 Chapter 4: Web Service Interfaces XML Elements Description Type action customerid customer Valid values: DRAFT, COMMITTED, PRODUCT_KEY_ GENERATED, PRODUCED, COMPLETED, REVOKED, ACKNOWLEDGED Default: DRAFT (Optional) The action to be taken on the Entitlement. Valid values: SAVE: Saves the Entitlement in DRAFT state. The Entitlement can still be updated. COMMIT: Saves and update the entstate to COMMITTED. The Entitlement cannot be updated anymore. PRODUCE: Generates Product keys (for Product_Key based, Cloud_Named, and Cloud_ Unnamed entitlements). This action will change entstate to PRODUCED. This value is not applicable for Entitlements with lineitemtype= Hardware_Key or ProtectionKey_Update. ENABLE: Enable the entitlement. DISABLE: Disables the entitlement. REOPEN: To Change entstate from COMMITTED or PRODUCED (only for Product_ Key based) to DRAFT and make it available for update. REVOKE: Revoke a Cloud Entitlement. (Optional) Identifier of the Customer in the database. The Entitlement will be associated with this customer ID. customerid can be fetched by using Search Customer web service. (Optional) If customerid is provided provide an ID related to the customerid. If customerid has not been provided provide an ID and the corresponding customerid will be automatically chosen. For Cloud Entitlements, at least one parameter from customerid or Customer is required. String Integer String registrationrequired (Optional) Is Customer registration required before String

57 4.6. Managing Entitlements 49 XML Elements Description Type entitlementitem itemproduct lineitemtype protectionkeyid generating license. Valid values: NOT_REQUIRED: No need to register customer. DESIRED: Registration is desired but not mandatory for activation. MANDATORY: License cannot be generated unless a customer is associated with the Entitlement. Default NOT_REQUIRED (Required) Contains further elements like numproductkeys, numactivationperproductkey, itemtype, Priority, itemproducts, LicensingAttribute (e.g., ACKNOWLEDGMENT_ REQUEST). (Required) Can have two combination of values. only productid if the user wants to add product without changing any values. productid with productdetails (i.e. <product>.</product>) if the user wants to also update some (i) Specify At Entitlement Time values, (ii) exclude feature from product, (iii) update memory data. (Required) Line item type. Valid values: Product_Key: Associates the Entitlement items to one or more Product Keys. Hardware_Key: Writes the Entitlement items to one or more Sentinel HL keys. ProtectionKey_Update: Enables changes to be made to the license data stored in deployed keys. Cloud_Named: You can define multiple end users who can use the Entitlement items. Each end user is identified by a unique Identity. You can define Identities while creating an Entitlement or later. Cloud_Unnamed: The use of the Entitlement items is not limited to any end user. That is, unlimited number of end users associated with the Customer can use the Entitlement items. All the end users have the same access rights. ID of the key to update. It is applicable only for Entitlements with lineitemtype=protectionkey_ Complex Type Complex Type String String

58 50 Chapter 4: Web Service Interfaces XML Elements Description Type numproductkeys Update. Multiple key IDs can be provided. The number of Product keys to generate. Depends on lineitemtype: For lineitemtype=product_key the value can be in the range For lineitemtype= Hardware_Key or ProtectionKey_Update the value can be 1. numactivationperproductkey For lineitemtype=product_key: Number of activation allowed per Product key. enforcementid identity identitycount For lineitemtype=hardware_key: No of key to burn. For lineitemtype=protectionkey_update: Number of updates to generate. (Optional) The enforcement technology, for example, Sentinel Cloud, Sentinel LDK. Valid values: 1 - Sentinel LDK; 2- Sentinel Cloud Default: 1 (Optional) (Applicable only for Cloud Entitlements) Associate identities for Cloud Named Entitlements. (Optional) (Applicable only for Cloud Entitlements) The number of identities to be associated with the Cloud Named Entitlement. Integer Integer Integer String Integer productstatus (Optional) Status of the Product. String Steps to Create an Entitlement Edit the XML for following: 1. Mention the action to be performed (SAVE, COMMIT, PRODUCE, ENABLE, DISABLE, REOPEN). <action>commit</action> 2. Add Product(s). <itemproduct> <productid>2</productid> <product>//this element is optional //Here you can add Product details that are to be specified at order time </product>

59 4.6. Managing Entitlements 51 </itemproduct> <itemproduct> <productid>5</productid> </itemproduct> 3. Update/add memory data in the relevant Product details part in the Entitlement XML. Refer of Product XSD for details. 4. To exclude a Feature from a Product, do not include that Feature in Product details. 5. To add an activation attribute ACKNOWLEDGEMENT_REQUEST, you can add following tag: <activationattribute > <attributename>acknowledgement_request</attributename> <attributevalue>true</attributevalue> </activationattribute> 6. Select the line item type. Possible values are: Product_Key, Hardware_Key, ProtectionKey_ Update, Cloud_Named, and Cloud_Unnamed. <lineitemtype>product_key</lineitemtype> For Entitlements of type ProtectionKey_Update, provide the Protection key ID as follows: <protectionkeyid> </protectionkeyid> You can only add existing Customers and Contacts to an Entitlement. This web service does not support creating new Customers and Contacts. For Cloud_Named Entitlements, the Identity count and the Identities can be updated. To include memory data you need to include the information in the Product(s). You can either COMMIT the entitlement or you can Produce it in one go if the XML provided is complete. Sample Response Success HTTP Status Code: 201 Header (Location) : {entid} Failure HTTP Status Code: 400 Response Body: Cannot find a Product corresponding to ID 55.

60 52 Chapter 4: Web Service Interfaces Update Entitlement Details Update Entitlement details for a given entid. You can edit an Entitlement only if it is not yet produced. Method Type POST URI v71/ws/entitlement/{entid}.ws URI Parameters Parameter Description Type entid Entitlement ID Integer Sample Request See "Sample XML for Entitlement Web Services" on page 63. The XML element names are selfexplanatory. Some of the important elements are as follows: The XML must comply with the schema provided for Entitlements (see "XSD for Entitlement Web Services" on page 121). XML Elements Description Type entstate action (Optional) Specifies the current status of the Entitlement. Valid values: DRAFT, COMMITTED, PRODUCT_KEY_ GENERATED, PRODUCED, COMPLETED, REVOKED, ACKNOWLEDGED Default: DRAFT (Optional) The action to be taken on the Entitlement. Valid values: SAVE: Saves the Entitlement in DRAFT state. The Entitlement can still be updated. COMMIT: Saves and update the entstate to COMMITTED. The Entitlement cannot be updated anymore. PRODUCE: Generates Product keys (for Product_Key based, Cloud_Named, and Cloud_ Unnamed entitlements). This action will change entstate to PRODUCED. This value is not applicable for Entitlements with lineitemtype= Hardware_Key or ProtectionKey_Update. ENABLE: Enable the entitlement. DISABLE: Disables the entitlement. REOPEN: To Change entstate from COMMITTED or PRODUCED (only for Product_ String String

61 4.6. Managing Entitlements 53 XML Elements Description Type Key based) to DRAFT and make it available for update. REVOKE: Revoke a Cloud Entitlement. customerid customer (Optional) Identifier of the Customer in the database. The Entitlement will be associated with this customer ID. customerid can be fetched by using Search Customer web service. (Optional) If customerid is provided provide an ID related to the customerid. If customerid has not been provided provide an ID and the corresponding customerid will be automatically chosen. For Cloud Entitlements, at least one parameter from customerid or Customer is required. Integer String registrationrequired entitlementitem itemproduct (Optional) Is Customer registration required before generating license. Valid values: NOT_REQUIRED: No need to register customer. DESIRED: Registration is desired but not mandatory for activation. MANDATORY: License cannot be generated unless a customer is associated with the Entitlement. Default NOT_REQUIRED (Required) Contains further elements like numproductkeys, numactivationperproductkey, itemtype, Priority, itemproducts, LicensingAttribute (e.g., ACKNOWLEDGMENT_ REQUEST). (Required) Can have two combination of values. only productid if the user wants to add product without changing any values. productid with productdetails (i.e. <product>.</product>) if the user wants to also update some (i) Specify At Entitlement Time values, (ii) exclude feature from product, (iii) update memory data. String Complex Type Complex Type lineitemtype (Required) Line item type. String

62 54 Chapter 4: Web Service Interfaces XML Elements Description Type protectionkeyid numproductkeys Valid values: Product_Key: Associates the Entitlement items to one or more Product Keys. Hardware_Key: Writes the Entitlement items to one or more Sentinel HL keys. ProtectionKey_Update: Enables changes to be made to the license data stored in deployed keys. Cloud_Named: You can define multiple end users who can use the Entitlement items. Each end user is identified by a unique Identity. You can define Identities while creating an Entitlement or later. Cloud_Unnamed: The use of the Entitlement items is not limited to any end user. That is, unlimited number of end users associated with the Customer can use the Entitlement items. All the end users have the same access rights. ID of the key to update. It is applicable only for Entitlements with lineitemtype=protectionkey_ Update. Multiple key IDs can be provided. The number of Product keys to generate. Depends on lineitemtype: For lineitemtype=product_key the value can be in the range For lineitemtype= Hardware_Key or ProtectionKey_Update the value can be 1. numactivationperproductkey For lineitemtype=product_key: Number of activation allowed per Product key. enforcementid identity identitycount For lineitemtype=hardware_key: No of key to burn. For lineitemtype=protectionkey_update: Number of updates to generate. (Optional) The enforcement technology, for example, Sentinel Cloud, Sentinel LDK. Valid values: 1 - Sentinel LDK; 2- Sentinel Cloud Default: 1 (Optional) (Applicable only for Cloud Entitlements) Associate identities for Cloud Named Entitlements. (Optional) (Applicable only for Cloud Entitlements) The number of identities to be associated with the Cloud Named Entitlement. String Integer Integer Integer String Integer

63 4.6. Managing Entitlements 55 XML Elements Description Type productstatus (Optional) Status of the Product. String Steps to Update 1. Get the XML for the Entitlement you want to update Refer to "Get Entitlement Details (XML) by entid" on page 57 for details. 2. Edit the XML for the parameters you want to update. 3. Call this web service. Updating the Entitlement XML You can edit the XML for following: Add the <action> tag to perform the following actions: The XML returned by Get Entitlement Details web service does not contain the <action>. You need to manually add this tag in the XML for update. o Enable or disable the Entitlement. For example: <action>disable</action> o Commit or Produce the Entitlement. For example: <action>commit</action> or <action>produce</action> For Cloud Entitlements, only PRODUCE action is available. o Reopen an Entitlement that is committed or for which Product Key has been generated. For example: <action>reopen</action> o Revoke a Cloud Entitlement that is committed. For example: <action>revoke</action> Add/remove Product(s). For example, <itemproduct> <productid>2</productid> <product>//this element is optional....

64 56 Chapter 4: Web Service Interfaces... //Here you can add Product details that are to be specified at order time </product> </itemproduct> <itemproduct> <productid>5</productid> </itemproduct> Update/add memory data in the relevant Product details part in the Entitlement XML. Refer of Product XSD for details. To exclude a Feature from a Product, you need not to include that Feature in Product details. To add an activation attribute ACKNOWLEDGEMENT_REQUEST, you can add following tag <activationattribute > <attributename>acknowledgement_request</attributename> <attributevalue>true</attributevalue> </activationattribute> Select the line item type. Possible values are: Product_Key, Hardware_Key, ProtectionKey_ Update, Cloud_Named, and Cloud_Unnamed. <lineitemtype>product_key</lineitemtype> For Entitlements of type Protection Key Update, provide the key ID of the Protection Key as follows: <protectionkeyid> </protectionkeyid> Configure license model attribute values. You can only add existing Customers and Contacts to an Entitlement. This web service does not support creating new Customers and Contacts. For Cloud_Named Entitlements, the Identity count and the Identities can be updated. To include memory data you need to include the information in the Product(s). You can either COMMIT the entitlement or you can Produce it in one go if the XML provided is complete. Sample Response Success HTTP Status Code: 200

65 4.6. Managing Entitlements 57 Response Body: XML Response Failure HTTP Status Code: 404 Response Body: Entitlement does not exist. Try again with a correct entitlement ID Delete an Entitlement Delete an Entitlement for given entid. Method Type DELETE URI v71/ws/entitlement/{entid}.ws URI Parameters Parameter Description Type entid Identifier of the Entitlement in the database. Integer Sample Request Not applicable. Sample Response Success HTTP Status Code: 204 Header-Location: Deleted Failure HTTP Status Code: 404 Response Body: Entitlement does not exist. Try again with a correct entitlement ID Get Entitlement Details (XML) by entid Retrieve the list of line items, with Product(s), Features(s), and License Model, for a given Entitlement ID. Method Type GET URI v71/ws/entitlement/{entid}.ws URI Parameters Parameter Description Type entid Specify the entitlement ID. Integer (>0) Sample Request Not applicable.

66 58 Chapter 4: Web Service Interfaces Sample Response Success HTTP Status Code: 200 Response Body: <entitlement> <startdate> </startdate> <enddate> </enddate> <createdate> </createdate> <enabled>true</enabled> <entstate>draft</entstate> <istest>false</istest> <policy> <registrationrequired>not_required</registrationrequired> <revocationallowed>true</revocationallowed> </policy> <entitlementitem> <startdate> </startdate> <enddate> </enddate> <itemstate>draft</itemstate> <numproductkeys>1</numproductkeys> <numactivationperproductkey>10</numactivationperproductkey> <priority>d</priority> <vendorid>1</vendorid> <lineitemtype>product_key</lineitemtype> <licensingattribute> <attributename>enforcement_type</attributename> <attributevalue/> <groupname>license TERMS</groupName> </licensingattribute> <licensingattribute> <attributename>c2v</attributename> <attributevalue/> <groupname>license TERMS</groupName> </licensingattribute> <licensingattribute> <attributename>acknowledgement_request</attributename> <attributevalue/> <groupname>license TERMS</groupName> </licensingattribute> <licensingattribute> <attributename>provisional_flag</attributename> <attributevalue>false</attributevalue> <groupname>license TERMS</groupName> </licensingattribute>

67 4.6. Managing Entitlements 59 <licensingattribute> <attributename>memory_data</attributename> <attributevalue/> <groupname>license TERMS</groupName> </licensingattribute> </entitlementitem> <refid1/> <refid2/> <description/> </entitlement> Failure HTTP Status Code: 404 Response Body: Entitlement does not exist. Try again with a correct Entitlement ID Search Entitlements Search Entitlements by the given query parameters. Method Type GET URI v71/ws/entitlement.ws?entstatus={entstatus} &refid1={refid1} &refid2={refid2} &customerid={customerid} &cstmrname={cstmrname} & id={ id} &vendorid={vendorid} Example URL: DRAFT&refId1=C223&refId2=CRM123&customerId=22&cstmrname= Microsys& Id=abd@example.com&vendorId=2 URL Parameters Parameter Description Type entstatus (Optional) Current status of the Entitlement. String refid1 refid2 (Optional) Reference ID 1. Identifier of the Entitlement in another system like CRM/ERP. (Optional) Reference ID 2. Identifier of the Entitlement in another system like CRM/ERP. String String customerid (Optional) Identifier of the Customer in the database. Integer cstmrname (Optional) The Customer name. String id (Optional) of the customer. String vendorid (Optional) If provided, the Entitlements that are associated with the Integer

68 60 Chapter 4: Web Service Interfaces Parameter Description Type given vendor are returned. (>0) enforcementid (Optional) Identifier of the Enforcement in the database. Integer Sample Response Success HTTP Status Code: 200 Response Body: <listresponse type="entitlement" count="2"> <instance id="3" customer="" state="draft" createdate=" :35:20.333" commitdate="null" /> <instance id="2" customer="" state="draft" createdate=" :12:57.31" commitdate="null" /> </listresponse> Failure HTTP Status Code: 401 Response Body: You should log on first Get Product Key Details (XML) Retrieve the details of a given Product key. Method Type GET URI v71/ws/productkey/{productkeyid}.ws URI Parameters Parameter Description Type productkeyid The Product key. String Sample Response Success HTTP Status Code: HTTP: 200 Response Body: <productkey> <productkeyid>0071eb86-911c-40aa-a07b-552d23ce37a1</productkeyid> <totalentitled>1</totalentitled> <available>1</available> <enabled>true</enabled> <type>product Key-based</type> <registrationrequired>not_required</registrationrequired>

69 4.6. Managing Entitlements 61 <customername>parag Mahajan</customerName> <productinfo id="1" productname="safenet Memo Card Plugin" type="base"/> <activationattribute> <attributename>c2v</attributename> <attributevalue>null</attributevalue> <isvpermission>none</isvpermission> <enduserpermission>write</enduserpermission> </activationattribute> <activationattribute> <attributename>acknowledgement_request</attributename> <attributevalue>false</attributevalue> <isvpermission>write</isvpermission> <enduserpermission>none</enduserpermission> </activationattribute> <activationattribute> <attributename>clear_before_applying_update</attributename> <attributevalue>null</attributevalue> <isvpermission>none</isvpermission> <enduserpermission>write</enduserpermission> </activationattribute> <entitlementid>7</entitlementid> <customerid>5</customerid> </productkey> Failure HTTP Status Code: HTTP: 404 Response Body: The Product Key does not exist Update Product Key This web service enables you to update some Product Key information. Most part of the Product Key details is read only. Method Type POST URI v71/ws/productkey/{productkeyid}.ws Sample Request See "Sample XML for Product Key" on page 63. The following elements of the XML can be updated, rest all are read-only. The XML must comply with the schema provided for Product Key (see "XSD for Product Key Web Services" on page 125). Parameter Description Type totalentitled The total number of activations allowed for this Product Key. You can Integer

70 62 Chapter 4: Web Service Interfaces Parameter Description Type increase or decrease this value. However, you cannot reduce this value below the available number of activations. enabled Enable/disable the Product Key. Boolean customer Update customer associated with the Product Key. Sample Response Success HTTP Status Code: 200 Failure HTTP Status Code: 404 Response Body: The Product key does not exist. String Creating/Producing an Protection Key Update type Entitlement Creating an Entitlement of type Protection Key Update is similar to the Create Entitlement web service. However, you need to specify the following parameters: Specify the line item type as ProtectionKey_Update <lineitemtype>protectionkey_update</lineitemtype> Provide the Protection key ID for which the update is intended as follows: <protectionkeyid> </protectionkeyid> Add the Entitlement to the production queue as follows: <action>commit</action> For more details on parameters and descriptions refer to section "Create an Entitlement" on page 47. Activating the Protection Key Update type Entitlement The Entitlement can be activated by both ISV login and ProductKey Login. To activate, use the Generate License web service. This web service requires either the C2V or ProtectionKeyId. You can get the C2V from the end user machine using the hasp_get_sessioninfo() function in Sentinel Licensing API. To get the Product Key, call the Get Entitlement web service for a given Entitlement ID. For Entitlements of type Protection Key Update, the Product Key is not displayed in the Sentinel EMS portal. Sample request to generate a V2C for a ProtectionKeyId:

71 4.6. Managing Entitlements 63 <activation> <activationinput> <activationattribute> <attributevalue> </attributevalue> <attributename>protectionkeyid</attributename> </activationattribute> <comments /> </activationinput> </activation> The output XML of this web service contains the V2C within the text within <activationstring> tags Sample XML for Entitlement Web Services <entitlement> <enabled>true</enabled> <action>save</action> <istest>false</istest> <customerid>1</customerid> <partnerid /> <partner /> <refid1 /> <refid2 /> <description /> <startdate> </startdate> <enddate> </enddate> <policy> <revocationallowed>true</revocationallowed> <registrationrequired>desired</registrationrequired> </policy> <entitlementitem> <priority>d</priority> <startdate> </startdate> <enddate> </enddate> <itemlicensetype>0</itemlicensetype> <lineitemtype>product_key</lineitemtype> <numactivationperproductkey>1</numactivationperproductkey> <numproductkeys>1</numproductkeys> <vendorid>1</vendorid> <itemproduct> <productid>1</productid> </itemproduct> <activationattribute> <attributename>acknowledgement_request</attributename> <attributevalue>false</attributevalue> </activationattribute> <memorysegments> </memorysegments> </entitlementitem> </entitlement> Sample XML for Product Key <productkey> <productkeyid>92643a67-8fe9-49a2-b2b3-b21024de37e4</productkeyid> <totalentitled>1</totalentitled>

72 64 Chapter 4: Web Service Interfaces <available>1</available> <enabled>true</enabled> <type>product Key-based</type> <productinfo id="1" productname="prd1" type="base" /> <licensingattribute> <attributename>acknowledgement_request</attributename> <attributevalue>true</attributevalue> <isvpermission>write</isvpermission> <enduserpermission>none</enduserpermission> </licensingattribute> <licensingattribute> <attributename>clear_before_applying_update</attributename> <attributevalue>null</attributevalue> <isvpermission>none</isvpermission> <enduserpermission>write</enduserpermission> </licensingattribute> <licensingattribute> <attributename>c2v</attributename> <attributevalue>null</attributevalue> <isvpermission>none</isvpermission> <enduserpermission>write</enduserpermission> </licensingattribute> </productkey>

73 4.7. Product Key Activation Product Key Activation This section lists the web services provided for Product key activation. The following interfaces are available for Product activation: Method URI Template Description POST v71/ws/productkey/{productkeyid}/activation.ws Generate License GET v71/ws/activation/{aid}.ws Get License by Activation ID (aid) Generate License This web service returns the Activation (XML) for a given Product Key. The <activationstring> section contains the V2C in XML-encoded format. Method Type POST URI v71/ws/productkey/{productkeyid}/activation.ws URI Parameters Parameter Description Type productkeyid Identifier of the Product Key in the database. String Sample Request In the input XML, insert the C2V in <activationinput> section as defined in the following example. The C2V should be enclosed in CDATA tag. The XML must comply with Activation.xsd. <activation> <activationinput> <activationattribute> <attributevalue><![cdata[<?xml version="1.0" encoding="utf-8"?> <hasp_info> <host_fingerprint>mxhjsymnpjnybwmqmxcmqpinej1xjk6xgatacnudocilieurzc/ z14ywkbgxxi6ikdbieqtnvdxivhooe1xumzzjf+qy</host_fingerprint> </hasp_info>]]> </attributevalue> <attributename>c2v</attributename> </activationattribute> <comments>new Comments Added By Web Services</comments> </activationinput> </activation> Sample Response Success The response contains the generated V2C and the input C2V. Both V2C and C2V in the response are in the form of encoded XML. The text within <activationstring> tags in the following sample represents the V2C. HTTP Status Code: 200

74 66 Chapter 4: Web Service Interfaces Response Body: <?xml version="1.0" encoding="utf-8"?> <activation> <activationoutput> <AID>c2396d ca6-9f10-682c62bdebfe</AID> <protectionkeyid> </protectionkeyid> <activationstring> <?xml version="1.0" encoding="utf-8"?><hasp_info> <haspscope><vendor id="37515" > <hasp id=" " /></vendor> </haspscope> <v2c> /fzrh+ezakmlgaebgqzqcmludacha 4ABAA==</v2c></hasp_info&g t; </activationstring> </activationoutput> <activationinput> <activationattribute> <attributename>clear_before_applying_update</attributename> <attributevalue>null</attributevalue> <isvpermission>none</isvpermission> <enduserpermission>read_write</enduserpermission> </activationattribute> <activationattribute> <attributename>c2v</attributename> <attributevalue><?xml version="1.0" encoding="utf-8"?><hasp_info> <haspscope> <hasp id=" "> <vendor id="37515"/> </hasp> </haspscope> <c2v> YYIrYoADY3R2oQaABE0Qj4OiCoACAOqB </attributevalue> </activationattribute> <comments>new Comments Added By Web Services</comments> </activationinput> </activation> Failure HTTP Status Code: 404 Response Body: The Product key does not exist Get License by Activation ID (aid) Returns the License in XML format for given Activation ID (aid). Method Type GET URI v71/ws/activation/{aid}.ws

75 4.7. Product Key Activation 67 URI Parameters Parameter Description aid Identifier of the Activation ID in the database. You can get the aidas follows: during activation of product key by calling the get product key details web service for an activated product key. Type String Sample Response Success HTTP Status Code: 200 Response Body: <?xml version="1.0" encoding="utf-8"?> <activation> <activationoutput> <AID>c2396d ca6-9f10-682c62bdebfe</AID> <protectionkeyid> </protectionkeyid> <activationstring> <?xml version="1.0" encoding="utf-8"?><hasp_info> <haspscope><vendor id="37515" > <hasp id=" " /></vendor> </haspscope> <v2c> /fzrh+ezakmlgaebgqzqcmludacha 4ABAA==</v2c></hasp_info&g t; </activationstring> </activationoutput> <activationinput> <activationattribute> <attributename>clear_before_applying_update</attributename> <attributevalue>null</attributevalue> <isvpermission>none</isvpermission> <enduserpermission>read_write</enduserpermission> </activationattribute> <activationattribute> <attributename>c2v</attributename> <attributevalue><?xml version="1.0" encoding="utf-8"?><hasp_info> <haspscope> <hasp id=" "> <vendor id="37515"/> </hasp> </haspscope> <c2v> YYIrYoADY3R2oQaABE0Qj4OiCoACAOqB </attributevalue> </activationattribute>

76 68 Chapter 4: Web Service Interfaces <comments>new Comments Added By Web Services</comments> </activationinput> </activation> Failure HTTP Status Code: HTTP: 404 Response Body: No activation exists for the AID. Provide a valid AID.

77 4.8. Protection Key Protection Key This section lists the web services provided for Protection key (target). The following interfaces are available: Method URI Template GET v71/ws/entitlement/ {entid}/target.ws v71/ws/target/ {protectionkeyid} /entitlement.ws v71/ws/target/ {protectionkeyid}.ws v71/ws/target/ {protectionkeyid} /activation.ws?{aid}={aid} Description Get Protection Key capable devices Get Entitlements by Protection Key ID Get fingerprint of Protection Key by key ID Get Protection Key history by key ID POST v71/ws/target.ws Update Protection Key (Checkin / Read / Format / Force Introduce / Enable / Disable /Finger Print / Locate / Convert v2c to exe) DELETE v71/ws/activation/{aid} /target.ws Remove pending updates Update Protection Key (Checkin/Read/Format/Force Introduce/Enable/Disable/Finger Print/Locate/Convert v2c to exe) Update protection key according to the action specified. Method Type POST URI v71/ws/target.ws Sample Request See "Sample XML for Protection Key Web Services" on page 82. The XML element names are selfexplanatory. Some of the important elements are as follows: The XML must comply with the schema provided for Protection key (see "XSD for Protection Key Web Services" on page 128). XML Elements Description Type action (Required) The action to be taken on the Protection key. Action can be one of the following: Checkin Update key info in the database. If key already exists, check if it has pending updates or if it needs force introduce. Anyway returns key state (Products/Features/memory on the key) String

78 70 Chapter 4: Web Service Interfaces XML Elements Description Type Read Only returns key state Format Clean Products and memory data from the key in c2v. Returns the v2c. ForceIntroduce Override the key info exists in the database (by changing updates state to REMOVED) and insert new info. Enable Change key state to enabled. Disable Change key state to disabled. Fingerprint Get the fingerprint of the Protection key by c2v. Locate Locates the Protection key by c2v. ConvertV2CToExe Convert the v2c corresponding to the c2v to an exe file. The sample XML for this action is different from the sample mentioned above. See Sample Request for ConvertV2CToExe Action. The response for this action is an XML, which contains the base-64- encoded V2C text within the <Exe>...</Exe> tags. You need to decode this text and save it as an EXE file. Clearclone This action creates a V2C file, which when applied on the cloned machine clears the key. C2V (Required) The C2V string. String Sample Request for ConvertV2CToExe Action <ProtectionKey> <ProtectionKeyInput> <action>convertv2ctoexe</action> <V2C> <!--V2C goes here --> </V2C> </ProtectionKeyInput> </ProtectionKey><ProtectionKey> <ProtectionKeyInput> <action>convertv2ctoexe</action> <V2C> <!--V2C goes here --> </V2C>

79 4.8. Protection Key 71 </ProtectionKeyInput> </ProtectionKey> Sample Response Success HTTP Status Code: 200 Response Body o For SL <?xml version="1.0" encoding="utf-8"?> <ProtectionKey> <ProtectionKeyOutput> <C2V> <sentinel_ldk_info> <key> <id> </id> <type>sl-adminmode</type> <update_counter>0</update_counter> <vendor> <id>37515</id> <name>demoma - evaluation</name> <name>demoma</name> </vendor> <configuration_info> <system_fingerprint> <raw_data>mxhjsc3ra3uaizmvuazqkbk/1dvldfefblqdqinizxuncfcvm7mfgioieuuzxcii4 9UnAGFEJpf5EWIQ</raw_data> </system_fingerprint> <reference_fingerprint> <fingerprint_control_type>isv Managed</fingerprint_control_type> <raw_data>mxhjsc3ra3uaizmvuazqkbk/1dvldfefblqdqinizxuncfcvm7mfgioieuuzxcii4 9UnAGFEJpf5EWIQ</raw_data> <fingerprint_info> <criteria> <name>cpu</name> <value> </value> </criteria> <criteria> <name>cpu</name> <value> </value> </criteria> <criteria> <name>mainboard</name> <value> </value> </criteria>

80 72 Chapter 4: Web Service Interfaces <criteria> <name>mainboard_uid</name> <value> </value> </criteria> <criteria> <name>pci_storage_ide</name> <value> </value> </criteria> <criteria> <name>pci_storage_ide</name> <value> </value> </criteria> <criteria> <name>pci_network_ethernet</name> <value> </value> </criteria> <criteria> <name>pci_display_vga</name> <value> </value> </criteria> <criteria> <name>pci_display_other</name> <value> </value> </criteria> <criteria> <name>pci_multimedia_audio</name> <value> </value> </criteria> </fingerprint_info> </reference_fingerprint> <fridge_version> </fridge_version> <vlib_version> </vlib_version> </configuration_info> <clone_detected>no</clone_detected> <rehost> <type>none</type> <counter>0</counter> </rehost> <product> <id>13</id> <name>sl admin mode</name> <feature> <id>2</id> <name>6</name> <license_properties>

81 4.8. Protection Key 73 <perpetual/> <concurrency> <count>unlimited</count> <count_criteria>per Station</count_criteria> <network_access>no</network_access> <detachable>no</detachable> </concurrency> <remote_desktop_access>no</remote_desktop_access> <virtual_machine_access>yes</virtual_machine_access> </license_properties> <detach_license_count>0</detach_license_count> <locked>yes</locked> </feature> <feature> <id>3</id> <name> <script>alert(hello)</script> </name> <license_properties> <perpetual/> <concurrency> <count>unlimited</count> <count_criteria>per Station</count_criteria> <network_access>no</network_access> <detachable>no</detachable> </concurrency> <remote_desktop_access>no</remote_desktop_access> <virtual_machine_access>yes</virtual_machine_access> </license_properties> <detach_license_count>0</detach_license_count> <locked>yes</locked> </feature> </product> <need_force>false</need_force> </key> <key> <type>sl-usermode</type> <configuration_info> <system_fingerprint> <fingerprint_info> <criteria> <name>cpu</name> <value> </value> </criteria> <criteria>

82 74 Chapter 4: Web Service Interfaces <name>cpu</name> <value> </value> </criteria> <criteria> <name>mainboard</name> <value> </value> </criteria> <criteria> <name>mainboard_uid</name> <value> </value> </criteria> <criteria> <name>hdd</name> <value> </value> </criteria> <criteria> <name>optical_drive</name> <value> </value> </criteria> <criteria> <name>ethernet_uid</name> <value> </value> </criteria> <criteria> <name>pci_network_ethernet</name> <value> </value> </criteria> <criteria> <name>pci_display_vga</name> <value> </value> </criteria> <criteria> <name>pci_display_vga</name> <value> </value> </criteria> </fingerprint_info> </system_fingerprint> </configuration_info> <need_force>false</need_force> </key> </sentinel_ldk_info> </C2V> </ProtectionKeyOutput> </ProtectionKey>

83 4.8. Protection Key 75 o For HL <?xml version="1.0" encoding="utf-8"?> <ProtectionKey> <ProtectionKeyOutput> <C2V> <sentinel_ldk_info> <key> <id> </id> <type>hl-max-micro</type> <update_counter>178</update_counter> <vendor> <id>37515</id> <name/> <name>demoma</name> </vendor> <configuration_info> <firmware_revision>3.25</firmware_revision> <real_time_clock_present>no</real_time_clock_present> <manufacturing_date> </manufacturing_date> <flash_memory_size>no Flash</flash_memory_size> </configuration_info> <product> <id>2</id> <name>base</name> <feature> <id>1</id> <name>11</name> <license_properties> <perpetual/> <remote_desktop_access>no</remote_desktop_access> </license_properties> </feature> </product> <product> <id>3</id> <name>555</name> <feature> <id>1</id> <name>11</name> <license_properties> <execution_count>5</execution_count> <used_execution_count>0</used_execution_count> <remote_desktop_access>yes</remote_desktop_access> </license_properties> </feature>

84 76 Chapter 4: Web Service Interfaces </product> <need_force>false</need_force> </key> </sentinel_ldk_info> </C2V> </ProtectionKeyOutput> </ProtectionKey> Failure HTTP Status Code: 404 Response Body: Product does not exist Get Protection Key by Capable Devices Retrieves an list of Sentinel protection keys that are supported for a given Entitlement ID. Method Type GET URI v71/ws/entitlement/{entid}/target.ws URI Parameters Parameter Description Type entid Sample Response Success HTTP Status Code: 200 Response Body The entitlement ID for which the associated keys are to be extracted. String <?xml version="1.0" encoding="utf-8"?> <sentinel_ldk_info> <capable_devices> <key_type>hl-time</key_type> <key_type>hl-max</key_type> <key_type>hl-max-micro</key_type> <key_type>hl-drive</key_type> <key_type>hl-express-card</key_type> <key_type>hl-pro</key_type> <key_type>hl-nettime-250+</key_type> <key_type>hl-nettime-50</key_type> <key_type>hl-nettime-10</key_type> <key_type>hl-net-250+</key_type> <key_type>hl-net-50</key_type>

85 4.8. Protection Key 77 <key_type>hl-net-10</key_type> </capable_devices> </sentinel_ldk_info> Failure HTTP Status Code: 404 Response Body: The specified Entitlement with ID 22 was not found Get Protection Key Capable Devices by Product Key Retrieves an list of Sentinel protection keys by Product key. Method Type GET URI v71/ws/productkey/{productkeyid}/target.ws URI Parameters Parameter Description Type productkeyid The Product key. String Sample Response Success HTTP Status Code: 200 Response Body <?xml version="1.0" encoding="utf-8"?> <ProtectionKey> <ProtectionKeyOutput> <UpdateInfo> <sentinel_ldk_info> <capable_devices> <key_type configuration="hasphl">hl-time</key_type> <key_type configuration="hasphl">hl-max</key_type> <key_type configuration="hasphl">hl-max-micro</key_type> <key_type configuration="hasphl">hl-drive</key_type> <key_type configuration="hasphl">hl-express-card</key_type> <key_type configuration="hasphl">hl-pro</key_type> <key_type configuration="hasphl">hl-nettime-250+</key_type> <key_type configuration="hasphl">hl-nettime-50</key_type> <key_type configuration="hasphl">hl-nettime-10</key_type> <key_type configuration="hasphl">hl-net-250+</key_type> <key_type configuration="hasphl">hl-net-50</key_type> <key_type configuration="hasphl">hl-net-10</key_type> <key_type configuration="sentinelhl, hasphl">sentinel-hl-time</key_type> <key_type configuration="sentinelhl, hasphl">sentinel-hl-max</key_type>

86 78 Chapter 4: Web Service Interfaces <key_type configuration="sentinelhl, hasphl">sentinel-hl-max-micro</key_type> <key_type configuration="sentinelhl, hasphl">sentinel-hl-drive</key_type> <key_type configuration="sentinelhl, hasphl">sentinel-hl-express-card</key_type> <key_type configuration="sentinelhl, hasphl">sentinel-hl-pro</key_type> <key_type configuration="sentinelhl, hasphl">sentinel-hl-nettime-250+</key_type> <key_type configuration="sentinelhl, hasphl">sentinel-hl-nettime-50</key_type> <key_type configuration="sentinelhl, hasphl">sentinel-hl-nettime-10</key_type> <key_type configuration="sentinelhl, hasphl">sentinel-hl-net-250+</key_type> <key_type configuration="sentinelhl, hasphl">sentinel-hl-net-50</key_type> <key_type configuration="sentinelhl, hasphl">sentinel-hl-net-10</key_type> <key_type configuration="sentinelhl, driverless">sentinel-hl-time</key_type> <key_type configuration="sentinelhl, driverless">sentinel-hl-max</key_type> <key_type configuration="sentinelhl, driverless">sentinel-hl-max-micro</key_type> <key_type configuration="sentinelhl, driverless">sentinel-hl-drive</key_type> <key_type configuration="sentinelhl, driverless">sentinel-hl-express-card</key_type> <key_type configuration="sentinelhl, driverless">sentinel-hl-pro</key_type> </capable_devices> </sentinel_ldk_info> </UpdateInfo> </ProtectionKeyOutput> </ProtectionKey> Failure HTTP Status Code: 404 Response Body: Product key does not exist Get Entitlements by Protection Key ID Returns Entitlements associated with a key. Method Type GET URI v71/ws/target/{protectionkeyid}/entitlement.ws URI Parameters Parameter Description Type protectionkeyid Sample Response Success HTTP Status Code: 200 ID of the key for which the associated Entitlements are to be extracted. String

87 4.8. Protection Key 79 Response Body <entitlementlistresponse count="8"> <entitlementinstance entid="1" contact="" customer="" state="draft" createdate=" :52:56.853" commitdate=" :52:57.51" /> <entitlementinstance entid="2" contact="" customer="" state="draft" createdate=" :56:14.863" commitdate=" :56:15.55" /> <entitlementinstance entid="3" contact="" customer="" state="draft" createdate=" :18:28.583" commitdate=" :18:30.067" /> <entitlementinstance entid="4" contact="" customer="" state="draft" createdate=" :34:47.14" commitdate=" :34:47.187" /> <entitlementinstance entid="5" contact="" customer="" state="draft" createdate=" :37:26.623" commitdate=" :37:26.67" /> <entitlementinstance entid="6" contact="" customer="" state="draft" createdate=" :49:51.867" commitdate=" :49:52.43" /> <entitlementinstance entid="7" contact="" customer="" state="draft" createdate=" :56:41.74" commitdate=" :56:41.787" /> <entitlementinstance entid="8" contact="" customer="" state="draft" createdate=" :58:50.333" commitdate=" :58:50.397" /> </entitlementlistresponse> Failure HTTP Status Code: 404 Response Body: Unable to retrieve Protection Key for Key ID Get Protection Key Fingerprint by Key ID Retrieves the fingerprint of hardware devices from the Sentinel EMS database, according to Sentinel key ID. Method Type GET URI v71/ws/target/{protectionkeyid}.ws URI Parameters Parameter Description Type protectionkeyid ID of the key from which the fingerprint is to be extracted. String Sample Response Success HTTP Status Code: 200 Response Body: <?xml version="1.0" encoding="utf-8"?> <ProtectionKey> <ProtectionKeyOutput>

88 80 Chapter 4: Web Service Interfaces <Fingerprint> <system_fingerprint>mxhjssoageidzgcph1p846oykkigj+7oqqg+ukqchgoex4iehgao6ilczu0k/skowkmy0 SJk0+UAUhE=</system_fingerprint> <reference_fingerprint>mxhjssoageidzgcph1p846oykkigj+7oqqg+ukqchgoex4iehgao6ilczu0k/skowk MY0SJk0+UAUhE=</reference_fingerprint> </Fingerprint> </ProtectionKeyOutput> </ProtectionKey> Failure HTTP Status Code: 404 Response Body: Unable to retrieve Protection Key for Key ID Get Protection Key History by Key ID Returns key state (Products/Features/memory on the key) for specific update. If not sending activationid, returns current key history. Method Type GET URI v71/ws/target/{protectionkeyid}/activation.ws?{aid}={aid} Example URI: =c2396d ca6-9f10-682c62bdebfe URI Parameters Parameter Description Type protectionkeyid ID of the key from which the key history is to be extracted. String AID The activation ID. (Optional) String Sample Response Success HTTP Status Code: 200 Response Body <?xml version="1.0" encoding="utf-8"?> <sentinel_ldk_info> <key> <id> </id> <type>hl-net-250+</type> <update_counter>32</update_counter> <vendor> <id>37515</id> <name /> </vendor> <configuration_info> <firmware_revision>3.25</firmware_revision>

89 4.8. Protection Key 81 <real_time_clock_present>no</real_time_clock_present> <manufacturing_date> </manufacturing_date> <flash_memory_size>no Flash</flash_memory_size> </configuration_info> <product> <id>0</id> <name /> <feature> <id>0</id> <name /> <license_properties> <perpetual /> <concurrency> <count>unlimited</count> <count_criteria>per Station</count_criteria> <network_access>yes</network_access> </concurrency> <remote_desktop_access>yes</remote_desktop_access> </license_properties> </feature> </product> <product> <id>2</id> <name>p1</name> <feature> <id>1</id> <name>f1</name> <license_properties> <perpetual /> <remote_desktop_access>no</remote_desktop_access> </license_properties> </feature> </product> </key> </sentinel_ldk_info> Failure HTTP Status Code: 404 Response Body: Unable to retrieve Protection Key for Key ID Remove Pending Updates Removes updates that are generated for the key but are not installed on it (that is, updates for the key that are in pending state). If activation ID is not the most recent, which means there are older pending updates, this action will fail. Method Type DELETE URI v71/ws/activation/{aid}/target.ws

90 82 Chapter 4: Web Service Interfaces URI Parameters Parameter Description AID The activation ID. You can get the AID by checkin action in update protection key web service. Type String Sample Response Success HTTP Status Code: 204 Header-Location: Deleted Failure Status Code: 400 Response Body: There are newer activations to remove. First remove activation ID(s): {AID} Sample XML for Protection Key Web Services <ProtectionKey> <ProtectionKeyInput> <action>enable</action> <C2V> <hasp_info> <haspscope> <hasp id=" "> <vendor id="37515"/> </hasp> </haspscope> <c2v> VfXP1SV1AaimojJooZ8sCo11KZ0LZLMXN0Bdzf3pF+QvI7UWpy3UvupMhvR5B+4S 4u/uItBvTe/ua+/YOHJqdBCDygP1QWfF9o5WF50MKzKpPTIoler5tarhHtTMwNRdz BkzWTiZxKekmSF5NZY8UEjpcrHYxSKUNxx0oYUyya72Y219EF/78yNCXQq0N9arne </c2v> </hasp_info> </C2V> </ProtectionKeyInput> </ProtectionKey>

91 4.9. Customers and Contacts Customers and Contacts This section provides information about the web services available to manage Customers and Contacts. The following interfaces are available: Method URI Template Description GET v71/ws/customer/{customerid}.ws Retrieve Customer details v71/ws/customer.ws v71/ws/customer/{customerid}/contact.ws v71/ws/contact/{contactid}.ws v71/ws/contact.ws v71/ws/contact.ws Search Customers Get Contacts by Customer ID Retrieve Contact Details Get Contact details by Search Contacts PUT v71/ws/customer.ws Create a Customer v71/ws/customer/{customerid}/contact.ws Create a Contact POST v71/ws/customer/{customerid}.ws Update Customer details v71/ws/contact/{contactid}.ws Update Contact details DELETE v71/ws/customer/{customerid}.ws Delete a Customer v71/ws/contact/{contactid}.ws Delete a Contact Create Customer Create a new Customer. Method Type PUT URI v71/ws/customer.ws Sample Request A basic sample XML is provided at "Sample XML for Customer Web Services" on page 93. The XML must comply with the schema Customer.xsd. The XML element names are selfexplanatory. Some of the important elements are as follows: XML Elements Description Type type Sample Response Success (Optional) Refers to the customer type. The possible values are: ind - Individual Customer org - Organization-type Customer Default value: org String HTTP Status Code: 201 Header-Location: {customerid} (ID of the Customer created.)

92 84 Chapter 4: Web Service Interfaces Response Body: Failure HTTP Status Code: 400 Response Body: Customer already exists Update Customer Details Update the details of a Customer. Method Type POST URI v71/ws/customer/{customerid}.ws URI Parameters Parameter Description Type customerid Specify the customer ID. Integer Sample Request See "Sample XML for Customer Web Services" on page 93. The XML must comply with the schema provided for Customer (see "XSD for Customer Web Services" on page 134). Sample Response Success HTTP Status Code: 200 Response Body: <customer> <type>org</type> <enabled>true</enabled> <name>gray Matter Technologies</name> <description>737000$</description> <crmid>c10h15n</crmid> <refid>149.24</refid> <phone>(505) </phone> <fax>(505) </fax> <addresses> <shippingsameasbilling>false</shippingsameasbilling> <address> <type>billing</type> <street>negra Arroyo Lane, 308</street> <city>albuquerque</city><state>nm</state> <country>usa</country>

93 4.9. Customers and Contacts 85 <zip>87114</zip> </address> <address> <type>shipping</type> <street>4257 Isleta Blvd. SW</street> <city>albuquerque</city> <state>nm</state> <country>usa</country> <zip>87105</zip> </address> </addresses> <vendorid>2</vendorid> <defaultcontact> <firstname>walter</firstname> <middlename>hartwell</middlename> <lastname>white</lastname> <locale>en</locale> </defaultcontact> </customer> Failure HTTP Status Code: 404 Response Body: The specified Customer with ID 8 does not exist Delete Customer Delete a Customer for a given customer ID. Method Type DELETE URI v71/ws/customer/{customerid}.ws URI Parameters Parameter Description Type customerid Identifier of the Customer in the database. Integer Sample Response Success HTTP Status Code: 204 Header-Location: Deleted Failure HTTP Status Code: 404 Response Body: The specified Customer with ID 2 was not found.

94 86 Chapter 4: Web Service Interfaces Retrieve Customer Details Returns the details of a Customer by Customer ID. Method Type GET URI v71/ws/customer/{customerid}.ws URI Parameters Parameter Description Type customerid Identifier of the Customer in the database. Integer Sample Request Not applicable. Sample Response Success HTTP Status Code: 200 Response Body: <customer> <type>org</type> <enabled>true</enabled> <name>gray Matter Technologies</name> <description>737000$</description> <crmid>c10h15n</crmid> <refid>149.24</refid> <phone>(505) </phone> <fax>(505) </fax> <addresses> <shippingsameasbilling>false</shippingsameasbilling> <address> <type>billing</type> <street>negra Arroyo Lane, 308</street> <city>albuquerque</city><state>nm</state> <country>usa</country> <zip>87114</zip> </address> <address> <type>shipping</type> <street>4257 Isleta Blvd. SW</street> <city>albuquerque</city> <state>nm</state> <country>usa</country> <zip>87105</zip> </address>

95 4.9. Customers and Contacts 87 </addresses> <vendorid>2</vendorid> <defaultcontact> <firstname>walter</firstname> <middlename>hartwell</middlename> <lastname>white</lastname> <locale>en</locale> </defaultcontact> </customer> Failure HTTP Status Code: 404 Response Body: The specified Customer with ID 1 was not found Search Customers Search customers by the given query parameters. Method Type GET URI v71/ws/customer.ws?customername={customername} &crmid={crmid} &refid={refid} &pageindex={pageindex} &pagesize={pagesize} &sortcol={sortcol} &sortorder={sortorder} &vendorid={vendorid} Example URL: &crmid=crm34&refid=crmn554&pageindex=5&pagesize=10&sortcol=customername&sortorder=a sc&vendorid=2 URI Parameters Parameter Description Type customername (Optional) The Customer name. String crmid (Optional) CRM ID. String refid (Optional) Reference ID. String pageindex (Optional) The starting page number. Integer (>0) pagesize (Optional) The number of customers retrieved by one request. Integer (>0) sortcol (Optional) Sort against the column. String (crmid, cstmrid,

96 88 Chapter 4: Web Service Interfaces Parameter Description Type customername, refid, type) sortorder (Optional) The order to sort. String (asc, desc) vendorid Sample Response Success HTTP Status Code: 200 Response Body (Optional) The Customers which are associated with the given vendor are returned. Integer (>0) <listresponse type="customer" count="7"> <instance customerid="6" name="priya Shetye" refid1="106" type="ind" enabled="true" phone=" " fax="" billingzip="11234" billingaddress="24 Hegde Drive" billingcity="bangalore" b illingcountry="india" billingstate="" vendorid="1" default ="p.shetye025@testsite.com" defa ultcontactname="priya Shetye"/> <instance customerid="5" name="parag Mahajan" refid1="105" type="ind" enabled="true" phone=" " fax="" billingzip="23432" billingaddress="112 Main St" billingcity="pune" billingc ountry="india" billingstate="" vendorid="1" default ="pmahajan@miain.com" defaultcontactnam e="parag Mahajan"/> <instance customerid="4" name="robert Jones" refid1="104" type="ind" enabled="true" phone=" " fax="" billingzip="10952" billingaddress="148 Highview La" billingcity="new Square" billingcountry="" billingstate="ny" vendorid="1" default ="rjr12@zahav15.net" defaultcontac tname="robert Jones"/> <instance customerid="3" name="peter Adams" refid1="103" type="ind" enabled="true" phone=" " fax="" billingzip="62204" billingaddress="1104 Fifth Ave" billingcity="athens" billi ngcountry="" billingstate="ga" vendorid="1" default ="adamsp@eliashim.com" defaultcontactna me="peter Adams"/> <instance customerid="2" name="sara Brown" refid1="102" type="ind" enabled="true" phone=" " fax="" billingzip="62204" billingaddress="654 Four Mile Dr" billingcity="arlington" bi llingcountry="" billingstate="va" vendorid="1" default ="sara@fast-ag.com" defaultcontactna me="sara Brown"/> <instance customerid="1" name="john Smith" refid1="101" type="ind" enabled="true" phone=" " fax="" billingzip="34897" billingaddress="1104 Fifth Ave" billingcity="athens" billin gcountry="" billingstate="ga" vendorid="1" default ="smithj@eliashim.com" defaultcontactnam e="john Smith"/> </listresponse> Failure HTTP Status Code: 400 Response Body: Invalid crmid Get Contact by Customer ID Returns a list of Contact for the given Customer ID.

97 4.9. Customers and Contacts 89 Method Type GET URI v71/ws/customer/{customerid}/contact.ws URI Parameters Parameter Description Type customerid Specify the customer ID. Integer Sample Request Not applicable. Sample Response Success HTTP Status Code: 200 Response Body: <listresponse type="contact" count="1"> <instance contactid="16" customerid="23" name="walter Hartwell White" enabled="true" default="true" firstname="walter" middlename="hartwell" lastname="white" locale="en"/> </listresponse> Failure HTTP Status Code: 404 Response Body: The specified Customer with ID 21 was not found Create Contact Create a new Contact for the given Customer ID. You can create a Contact only for organizationtype Customers. Method Type PUT URI v71/ws/customer/{customerid}/contact.ws URI Parameters Parameter Description Type customerid Identifier of the Customer in the database. Integer Sample Request See "Sample XML for Contact Web Services" on page 94. The XML must comply with the schema provided for Contact (see "XSD for Contact Web Services" on page 133).

98 90 Chapter 4: Web Service Interfaces Sample Response Success HTTP Status Code: 201 Header-Location: {contactid} Failure HTTP Status Code: 404 Response Body: The specified Customer with ID 3 was not found Update Contact Details Update the details of a Contact. Method Type POST URI v71/ws/contact/{contactid}.ws URI Parameters Parameter Description Type contactid Specify the Contact ID. Integer Sample Request See "Sample XML for Contact Web Services" on page 94. The XML must comply with the schema provided for Contact (see "XSD for Contact Web Services" on page 133). Sample Response Success HTTP Status Code: 200 Response Body: <contact> <enabled>true</enabled> <default>true</default> < id>breakingbadeee44@gmail.com</ id> <firstname>bryan</firstname> <middlename>heisenberg</middlename> <lastname>cranston</lastname> <locale>de</locale> </contact> Failure HTTP Status Code: 404 Response Body: Contact does not exist.

99 4.9. Customers and Contacts Delete Contact Delete a Contact for a given Contact ID. Method Type DELETE URI v71/ws/contact/{contactid}.ws URI Parameters Parameter Description Type contactid Identifier of the Contact in the database. Integer Sample Response Success HTTP Status Code: 204 Header-Location: Deleted Failure HTTP Status Code: 404 Response Body: The specified Contact with ID 2 was not found Retrieve Contact Details Returns the details of a Contact by Contact ID. Method Type GET URI v71/ws/contact/{contactid}.ws URI Parameters Parameter Description Type contactid Identifier of the Contact in the database. Integer Sample Request Not applicable. Sample Response Success HTTP Status Code: 200 Response Body: <contact> <enabled>true</enabled> <default>true</default>

100 92 Chapter 4: Web Service Interfaces <firstname>walter</firstname> <middlename>hartwell</middlename> <lastname>white</lastname> <locale>en</locale> </contact> Failure HTTP Status Code: 404 Response Body: The specified Contact with ID 1 was not found Get Contact Details by Returns the details of a Contact by ID. Method Type GET URI v71/ws/contact.ws?contact id={contact id} GET Parameters Parameter Description Type contact id of the Contact. String Sample Request Not applicable. Sample Response Success HTTP Status Code: 200 Response Body <listresponse type="contact" count="1"> <instance contactid="14" id="heisenberg@gmail.com" customerid="8"/> </listresponse> Failure HTTP Status Code: 400 Response Body: Invalid identifier Search Contacts Search Contacts by the given query parameters.

101 4.9. Customers and Contacts 93 Method Type GET URI v71/ws/contact.ws?firstname={firstname} &lastname={lastname} &pagesize={pagesize} &pageindex={pageindex} &sortcol={sortcol} &sortorder={sortorder} Example URL: &lastname=patel&pageindex=5&pagesize=10&sortcol=contactid&sortorder=asc URI Parameters Parameter Description Type firstname First name. String lastname Last name. String pagesize The number of contacts retrieved by one request. Integer (>0) pageindex The starting page number. Integer (>0) sortcol Sort against the column. String sortorder Ascending or descending. String (asc, desc) Sample Response Success HTTP Status Code: 200 Response Body: <listresponse type="contact" count="1"> <instance contactid="16" customerid="23" name="walter Hartwell White" enabled="true" default="true" firstname="walter" middlename="hartwell" lastname="white" locale="en"/> </listresponse> Failure HTTP Status Code: 400 Response Body: Invalid First Name Sample XML for Customer Web Services <customer> <type>org</type> <enabled>true</enabled> <name>gray Matter Technologies</name> <description>737000$</description>

102 94 Chapter 4: Web Service Interfaces <crmid>c10h15n</crmid> <refid>149.24</refid> <phone>(505) </phone> <fax>(505) </fax> <addresses> <shippingsameasbilling>false</shippingsameasbilling> <address> <type>billing</type> <street>negra Arroyo Lane, 308</street> <city>albuquerque</city><state>nm</state> <country>usa</country> <zip>87114</zip> </address> <address> <type>shipping</type> <street>4257 Isleta Blvd. SW</street> <city>albuquerque</city> <state>nm</state> <country>usa</country> <zip>87105</zip> </address> </addresses> <vendorid>2</vendorid> <defaultcontact> <firstname>walter</firstname> <middlename>hartwell</middlename> <lastname>white</lastname> <locale>en</locale> </defaultcontact> </customer> Sample XML for Contact Web Services <?xml version="1.0" encoding="utf-8"?> <contact> <firstname>bryan</firstname> <middlename>heisenberg</middlename> <lastname>cranston</lastname> <locale>de</locale> <enabled>true</enabled> <default>true</default> </contact>

103 5 Chapter 5: Backward Compatibility Some XSDs for Sentinel EMS web services have been updated to support additional attributes and the data type of some attributes have been modified. Optimum care has been taken to keep these XSDs backward compatible. However, it is advisable to update your client application to use the new XSDs for validating responses Modified XSDs in Sentinel EMS 7.0 The following XSDs have been modified in this release. Feature.xsd Product.xsd Entitlement.xsd Activation.xsd XSDs of the earlier version are available at %ems_home%\backup\xsd Modified and New XSDs in Sentinel EMS 6.4 The following XSDs have been modified in v6.4. Entitlement.xsd Product.xsd ProductKey.xsd ProtectionKey.xsd The following new XSD has been added in this release: ProductKeyIdentity.xsd

104 96 Chapter 5: Backward Compatibility 5.3. Web Services that Were Deprecated in Sentinel EMS 6.3 This section provides information about the web services that were available in EMS and have been deprecated in EMS 7.1: Method URI Template PUT GET PUT GET v71/ws/vendor/{vendorid}/namespace/ {namespaceid}/feature.ws v71/ws/vendor/{vendorid}/namespace/ {namespaceid}/feature.ws v71/ws/vendor/{vendorid}/namespace/ {namespaceid}/product.ws v71/ws/vendor/{vendorid}/namespace/ {namespaceid}/product.ws Description Create a Feature Retrieve Features by Vendor and Namespace Create a Product Search Products by Vendor and Namespace GET v71/ws/namespace/{namespaceid}.ws Get Namespace details by ID v71/ws/vendor/{vendorid}/namespace.ws Get Namespaces by Vendor 5.4. Changes in 2.2 XSDs over 2.1 In some XSDs, few optional attributes have been added. None of the added attributes is mandatory. The pre-existing attributes have not been modified. XSD AuthenticationDetail.xsd Customer.xsd ListResponse.xsd Added/Updated Elements <xs:element name="version" type="xs:string" minoccurs="0" maxoccurs= "1"/> <xs:element ref="defaultcontact" minoccurs="0" maxoccurs="1"/> <xs:attribute name="descr" type="xs:string"/> <xs:attribute name="locktype" type="xs:string"/> <xs:attribute name="enabled" type="xs:boolean"/> <xs:attribute name="deployed" type="xs:boolean"/> <xs:attribute name="keysnumber" type="xs:integer"/> <xs:attribute name="actperkey" type="xs:integer"/> <xs:attribute name="activationdate" type="xs:integer"/> <xs:attribute name="customerid" type="xs:string"/> <xs:attribute name="needconfirm" type="xs:boolean"/> <xs:attribute name="phone" type="xs:string"/> <xs:attribute name="fax" type="xs:string"/> <xs:attribute name="billingaddress" type="xs:string"/>

105 5.4. Changes in 2.2 XSDs over XSD Added/Updated Elements <xs:attribute name="billingzip" type="xs:string"/> <xs:attribute name="billingcity" type="xs:string"/> <xs:attribute name="billingcountry" type="xs:string"/> <xs:attribute name="billingstate" type="xs:string"/> <xs:attribute name="vendorid" type="xs:integer"/> <xs:attribute name="default " type="xs:string"/> <xs:attribute name="defaultcontactname" type="xs:string"/> <xs:attribute name="contactid" type="xs:integer"/> <xs:attribute name=" id" type="xs:string"/> Product.xsd <xs:element minoccurs="0" name="enabled" maxoccurs="1"> <xs:restriction base="xs:boolean"/> <xs:element minoccurs="0" name="deployed" maxoccurs="1"> <xs:restriction base="xs:boolean"/> ProductKey.xsd ProtectionKey.xsd <xs:complextype> <xs:simplecontent> <xs:extension base="xs:string"> <xs:attribute name="protectionkeyid" type="xs:string"/> </xs:extension> </xs:simplecontent> </xs:complextype>> The XSD contains many changes. Compare the new XSD with your old one to get the list of changes.

106

107 6 Chapter 6: emswsdemo: A Client Application to Test the Web Services emswsdemo is a demo application available with Sentinel EMS, using which you can test the EMS web services. Using emswsdemo, you can also generate sample codes for the web services. To use the tool, first you need to deploy it in your Sentinel EMS Server Deploying emswsdemo 1. Copy the file emswsdemo.war from %EMS_HOME%\samples\EmsWSDemo\bin to %EMS_ HOME%\EMSServer\webapps. 2. Wait for some time (approximately 2 minutes) before Tomcat extracts this war file. 3. Edit %EMS_HOME%\EMSServer\webapps\emsWSDemo\WEB_INF\emsWSDemo.properties and update values for the following properties: usessl if you have configured Sentinel EMS to use SSL, set the value to true (default value: false) server specify the machine name and port for (default value: localhost:80) truststore Provide the path of the certificate keystore file truststorepass provide the trust store password (default value: changeit) 4. Re-start Sentinel EMS service Accessing the emswsdemo URL Make sure that the Sentinel EMS service is started. Use the URL from any client machine in the network to access the tool. Where, host - IP address or name of the machine where emswsdemo tool is deployed. port - Sentinel EMS Server port. Example:

108

109 Chapter 7: A Sample Application using Java The Java code samples provided along with Sentinel EMS 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. If you are using CASTOR for marshalling operation, you need to modify the castor.properties file and set the value org.exolab.castor.naming=mixed for proper marshalling Getting Ready 1. Create a new Java project, say, JavaWSSample, from the source located at %EMS_ HOME%\Sample/JavaWSSample 2. Update the configure.properties file and provide actual values for following properties: truststore=c:/program Files/apache-tomcat /ems.keystore truststorepassword=changeit serverurl= The Concept The general process for executing EMS web service URLs can be divided into the following steps Read Properties Read different values like server URL, trust store location, password from property file and set these values to system (refer to the init() method in JavaWSSample/EMSActivationSample.java). Properties props=new Properties(); FileInputStream in = new FileInputStream("configure.properties"); props.load(in); truststore = props.getproperty("truststore");

110 102 Chapter 7: A Sample Application using Java truststorepass =props.getproperty("truststorepassword"); serverurl=props.getproperty("serverurl"); Set System Properties 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); Log In To access a web service, you need to first log on using login.ws. To implement this, create an object of HttpContext and call the EMS log-in URL using POST method as shown below: HttpContext context = new BasicHttpContext(); HttpPost post = new HttpPost(serverUrl+"ems/v71/ws/login.ws"); String authenticationdetail = WSUtil.readFileAsString ("AuthenticationDetailSample.xml"); post.setentity(new StringEntity(authenticationDetail, HTTP.UTF_8)); HttpResponse emsresponse = httpclient.execute(post, context); principal = (Principal) context.getattribute(clientcontext.user_token); if (emsresponse.getstatusline().getstatuscode()==200) return true; else return false; Refer to the verifylogin() method in JavaWSSample/EMSActivationSample.java for details. Once login is successful, store the ClientContext.USER_TOKEN in a variable to use in further calls. This will help you to authenticate once for one session of your application Call the Web Services After login is successful, you can call any web service method to get/create/update different EMS entities (refer to the sample at JavaWSSample/WSUtil.java for doput(), doget(), dopost() methods). GET Sample The code sample uses HTTPGet class to call GET web service and set search parameters (if any) to URL. HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); // Use HttpGet class to call HTTP Get method HttpGet get = new HttpGet(url);

111 7.2. The Concept 103 StringBuffer query = new StringBuffer(); // If url have some search parameters if (urlparams!=null) { for (String paramname : urlparams.keyset()) { String paramvalue = urlparams.get(paramname); setparameter(query, paramname, paramvalue); } get.seturi(new URI(URLDecoder.decode(get.getURI() + query.tostring(), "UTF-8"))); } HttpResponse response = httpclient.execute(get, context); PUT Sample The code sample uses HTTPPut class to call PUT web service and set input XML to request body. You can call POST and DELETE web services in a similar way. If you need to use characters like "<" and "&" in your XML elements, enclose the element within a CDATA section. A CDATA section begins with "<![CDATA[" and ends with "]]>". All text in an XML document is parsed by the parser. But text inside CDATA section are ignored by the parser. HttpContext context = new BasicHttpContext(); context.setattribute(clientcontext.user_token, principal); // Use HttpPut class to call HTTP Put method HttpPut put = new HttpPut(url); // Set Input Xml to request body put.setentity(new StringEntity(inputXml, HTTP.UTF_8)); HttpResponse response = httpclient.execute(put, context); Handling Response PUT Response If the PUT call is successful, HTTP status code 201, Created, is returned. // Check for status code, if not 201 get error reason from response body. if(emsresponse.getstatusline().getstatuscode()!=sc_created){ throw new Exception("Create Entitlement Failed - " + WSUtil.getDataFromResponse (emsresponse)); }else{ //If successfully done Id of object created can be retrieved from header Location return emsresponse.getfirstheader("location").getvalue(); } POST response If the POST call is successful, HTTP status code 200, OK, is returned. // Check for status code, if not 200 get error reason from response body. if (emsresponse.getstatusline().getstatuscode()!=sc_ok)

112 104 Chapter 7: A Sample Application using Java throw new Exception(WSUtil.getDataFromResponse(emsResponse)); else{ //If successfully done response xml can be retrieved from response body. return WSUtil.getDataFromResponse(emsResponse); } DELETE Response If the DELETE call is successful, HTTP status code 204, No Content, is returned. // Check for status code if not, 204 get error reason from response body. if (emsresponse.getstatusline().getstatuscode()!=sc_no_content) throw new Exception(WSUtil.getDataFromResponse(emsResponse)); else{ //If successfully done response xml can be retrieved from response body. return true; } GET Response If the GET call is successful, HTTP status code 200, OK, is returned. // Check for status code, if not 200 get error reason from response body. if (emsresponse.getstatusline().getstatuscode()!=sc_ok) throw new Exception(WSUtil.getDataFromResponse(emsResponse)); else{ //If successfully done response xml can be retrieved from response body. return WSUtil.getDataFromResponse(emsResponse); }

113 8 Chapter 8: Data Model 8.1. Activation Objects

114 106 Chapter 8: Data Model 8.2. Entitlement Objects

115 8.3. Catalog Objects 8.3. Catalog Objects 107