Create an Entitlement

Create an Entitlement using the parameters provided.

Method Type URI
PUT v90/ws/entitlement.ws

Prerequisites

Before calling this web service, make sure that:

>The Products for which the entitlement will be created are available (Base, Unlocked, Modification, or Cancellation).

>You know which Entitlement type (also called lineItemType - see below) you want to use.

>The Products contain any required Features or Memory Data.

>The Features contain License Models that are configured as needed.

>The state of all Products included in the entitlement is set to "Complete".

Sample Request

A basic sample XML is provided at Sample XML for Entitlement Web Services.

The XML must comply with the schema provided for Entitlement (see XSD for Entitlement Web Services). 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.

Valid values: DRAFT, QUEUED, PRODUCT_KEY_GENERATED, PRODUCED, COMPLETED, ACKNOWLEDGED

Default: DRAFT

 String
action

(Optional) The action to be taken on the Entitlement.

Valid values:

>SAVE: Saves the Entitlement in DRAFT state. The Entitlement can still be updated.

>QUEUE: Saves and update the entState to QUEUED. The Entitlement cannot be updated anymore.

>PRODUCE: Generates Product keys for entitlements). This action will change entState to PRODUCED.

NOTE   This value is not applicable for Entitlements with lineItemType=Hardware_Key or ProtectionKey_Update.

>ENABLE: Enables the entitlement.

>DISABLE: Disables the entitlement.

>REOPEN: To change entState from QUEUED or PRODUCED (only for Product_Key based) to DRAFT and make it available for update.

 String
action name

Controls the action that will be performed for a particular attribute depending on the attribute value that is selected.

Valid values:

NONE(Leave): Retain the existing value that is set for the attribute.

SET(Overwrite): Replaces the existing attribute value with a new value(s).

CANCEL: Deletes the entire product.

ADD(Modify): Adds a new value to the existing attribute value.

SUB(Modify): Removes a value from the existing attribute value.

 String
licenseModelId

Identifies Sentinel LDK-EMS licensing models in the database.

Valid values:

1: Execution Count

2: Expiration Date

3: Time Period

4: Perpetual

5: Unlocked (Time Period)

6: Unlocked (Perpetual)

11: Unlocked (Expiry Date) for on-premises Sentinel LDK-EMS

13: Unlocked (Expiry Date) for Sentinel LDK-EMS subscriptions

NOTE   Thales recommends retrieving the License Model ID before using it. For details, see Viewing License Model Details.

 String
attributeId

Attribute ID is used to identify XML elements in the Sentinel LDK-EMS database.

Valid values:

1: LICENSE_TYPE

2: EXECUTION_COUNT

3: EXPIRATION_DATE

4: TIME_PERIOD

5: ENABLE_CONCURRENCY

6: CONCURRENT_INSTANCES
    (for unlimited concurrency, set attributeValue to 10000000)

7: COUNT_CRITERIA

8: REMOTE_DESKTOP_ACCESS

9: NETWORK_ENABLED

10: DETACHABLE

11: VIRTUAL_MACHINE_ACCESS

12: C2V

13: ACKNOWLEDGEMENT_REQUEST

14: (Deprecated) PROVISIONAL_FLAG

15: ENFORCEMENT_TYPE

16: MEMORY_DATA

17: REHOST_ALLOWED

18: CLEAR_BEFORE_APPLYING_UPDATE

19: UPGRADE_DL_KEY_ALLOWED

20: START_DATE

21: END_DATE

22: (Deprecated) USAGE_TYPE

23: (Deprecated) CONCURRENT_LIMIT

24: (Deprecated) COUNTING_TYPE

25: (Deprecated) LICENSE_TYPE

26: (Deprecated) MAXIMUM_USAGE_LIMIT

27: (Deprecated) GRACE_LIMIT

28: (Deprecated) MEASUREMENT_UNIT_DURATION

29: (Deprecated) MEASUREMENT_UNIT_USAGE

30: (Deprecated) DISCONNECTED_TIME

31: (Deprecated) DEPLOYMENT_TYPE

32: (Deprecated) KEEP_ALIVE_TIME

33: (Deprecated) REFRESH_PERIOD

34: (Deprecated) VENDOR_ATTRIBUTE

String
customerId

(Optional) Identifier of the Customer in the database. The Entitlement will be associated with this customer ID.

TIP   You can fetch customerId by using the Search Customer web service.

customerId is required for pushing a license to your cloud license server using the Produce and Push a License for a Sentinel SL Key web service.

 Integer
customerEmail

(Optional)

>If customerId is provided—provide an email ID related to the customerId.

>If customerId is not provided—provide an email ID and the corresponding customerId will be automatically chosen.

 String
partnerId

(Optional) The identifier of the Channel Partner in the database is stored as the customerId. The Entitlement will be associated with this ID.

NOTE   partnerId can be fetched by using Search Channel Partner web service.

 Integer
partnerEmail

(Optional)

>If partnerId is provided—provide an email ID related to the partnerId.

>If partnerId has not been provided—provide an email ID and the corresponding partnerId will be automatically chosen.

 String
registrationRequired

(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

 String
entitlementItem (Required) Contains further elements, such as: numProductKeys, numActivationPerProductKey, itemType, Priority (must be set to D, reserved for future use), itemProducts, LicensingAttribute (for example, ACKNOWLEDGMENT_REQUEST). Complex Type
itemProduct

(Required) Can have two combination of values.

>only productId—if the user wants to add product without changing any values.

>productId with productDetails (for example, <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.

Complex Type
lineItemType

(Required) The type of entitlement.

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.

 String
protectionKeyId ID of the key to update. It is applicable only for Entitlements with lineItemType=ProtectionKey_Update. Multiple key IDs can be provided. String
numProductKeys

The number of Product keys to generate. Depends on lineItemType:

>For lineItemType=Product_Key the value can be in the range 1–10000.

>For lineItemType= Hardware_Key or ProtectionKey_Update the value can be 1.

 Integer
numActivationPerProductKey

>For lineItemType=Product_Key: Number of activations allowed per Product key.

>For lineItemType=Hardware_Key: Number of keys to burn.

>For lineItemType=ProtectionKey_Update: Number of updates to generate.

Integer
enforcementId

(Optional) The enforcement technology, Sentinel LDK.

Valid values: 1

Integer
identity Deprecated. String
identityCount Deprecated. Integer
productStatus (Optional) Status of the Product. String

Steps to Create an Entitlement

Edit the XML as follows:

1.Specify the action to be performed (SAVE, QUEUE, PRODUCE, ENABLE, DISABLE, REOPEN).

<action>QUEUE</action>

2.Add one or more Products. Apply values to any settings that are marked as SAOT.

To enable support for concurrency, you must:

•Set ENABLE_CONCURRENCY to TRUE.

•Set <attributeValue>integer</attributeValue> for CONCURRENT_INSTANCES.

<itemProduct>
  <productId>2</productId>
       <product>//This element is optional.
       ...
       ...
       //Here you can add Product details that are set to be specified at order time (SAOT)
       ...
       ...
       </product>
</itemProduct>
<itemProduct>
  <productId>5</productId>
</itemProduct>

3.Update/add memory data in the relevant Product details part in the Entitlement XML. Refer to Product XSD for details.

4.To exclude a feature from a Product, do not include the productFeatureRef tag (including all sub tags) for that Feature in the Product XML definition.

NOTE    If some product tags are missing, the entitlement will include all features by default.

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. Valid values are: Product_Key, Hardware_Key, ProtectionKey_Update.

<lineItemType>Product_Key</lineItemType>

For Entitlements of type ProtectionKey_Update, provide the Protection key ID as follows:

<protectionKeyId>43243243243</protectionKeyId>

NOTE    

>You can only add existing Customers and Contacts to an Entitlement. This web service does not support creating new Customers and Contacts.

> To include memory data, specify the information in the Product(s).

>You can either QUEUE the entitlement or Produce it 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.