You are here: Entitlement Management > Entitlement > updateEntitlement

Update Entitlement Details

Description

Update entitlement details for a given entitlement ID. Using this Web service, you can update entitlements that are in Draft stage and Reconfigured stage.

Default Protocol Method Type URI
HTTPS POST updateEntitlement.xml

Post Parameters

Parameter Description Valid Values Optional
entId Entitlement ID Integer (>0) No
startDate Entitlement start date. Date (yyyy-mm-dd) Yes
endDate Entitlement end date. Date (yyyy-mm-dd) Yes
customerId The unique record ID of the customer in EMS database. Integer (>0) Yes
contactEmailId E-mail address of a customer's contact. String Yes
alternateEmailId

E-mail address of a person representing the software vendor, such as a sales representative.

The same e-mail address can be specified for different customers. The sales representative e-mail address can be changed any time for the given entitlement, it can be changed to new email id or blank.

To reset alternateEmailId to blank, you need to explicitly specify its value as NULL.

String Yes
isRetail

Whether entitlement type is of retail or not

Valid values are True or False.

Boolean Yes
userId Identifier of the user in case of retail entitlement. String Yes
refId1 Information that uniquely identifies the entitlement in a different ERP system. String Yes
refId2 A second unique reference ID, similar to Ref ID 1. String Yes
stationCount

Maximum number of on-premise machines on which an entitlement can be used. You need to specify this value for on-premise entitlements created with entitlement level mode (deploymentType=4).

Range: 1 - 50

The default maximum value of station count is configurable and you can get it increased up to 999999 by contacting SafeNet Support (if required).

Default Value: 1

Integer

Yes
detachInterval

Maximum duration, in hour(s), for which the license can be detached by an on-premise machine. You need to specify this value for on-premise entitlements created with deploymentType 3 or 4.

Range: 1 hour - 43800 hours (approximately 5 years)

Default Value: 2160 hours

  • To detach a license for an indefinite duration, pass -1.
  • It is only applicable for entitlements created with deploymentType 4.

  • The default and maximum value of this parameter are configurable and you can change them from EMS Admin Console.
Integer Yes
collectUsage

Specifies whether or not to collect usage informatio. You can specify this value for on-premise entitlements created with deploymentType 4.

Allowed values: On and Off

Default Value: On

String

Yes
cacheInterval

Maximum duration, in minutes, for which the license is cached locally (in the connected license store) by an on-premise machine. You can specify this value for on-premise entitlements created with deploymentType 3.

Range: 1 minute - 43200 minutes (30 days)

Default Value: 60 minutes

The default and maximum value of this parameter are configurable and and you can change them from EMS Admin Console.

  Yes
vmEnabled

Specify to allow or disallow a protected application to run on a virtual machine.

You can configure this property only for on-premise entitlement level entitlements, that is deploymentType 4. This value is ignored for other deployment types. For on-premise feature level, the setting is considered enabled always.

Allowed Values: True or False

The default value of this parameter is configurable and you can change it from EMS Admin Console.

Boolean Yes
cloneProtection

Specify to enable or disable protection against virtual machine cloning. A clone is a copy of an existing virtual machine. Running applications on a cloned virtual machine can lead to misuse of software licenses. When Clone Protection is enabled, the protected application is not allowed to run on a machine that has been detected as a clone.

The value of cloneProtection is dependent on vmEnabled. Its value is taken into account only if vmEnabled is True.

Allowed Values: True or False

The default value of this parameter is configurable and you can change it from EMS Admin Console.

Boolean Yes

Sample Code

import java.io.IOException;
//..............................
//..............................
//..............................
import org.apache.http.params.HttpParams;
public class EMSSample {
	private static DefaultHttpClient httpclient = new DefaultHttpClient();
	private static Principal principal = null;
//..............................
//..............................
//..............................
public static String updateEntitlement.xml()throws Exception {
    if(!verifyLogin()){
        	return "login failed";
    }
    	HttpContext context = new BasicHttpContext();
    	context.setAttribute(ClientContext.USER_TOKEN, principal);
    	HttpPost post =  new HttpPost("https://localhost:8443/ems/updateEntitlement.xml");
    List<NameValuePair> nvps = new ArrayList<NameValuePair>();
    	nvps.add(new BasicNameValuePair("startDate", ""));
    	nvps.add(new BasicNameValuePair("entId", ""));
    	nvps.add(new BasicNameValuePair("endDate", ""));
    	nvps.add(new BasicNameValuePair("stationCount", ""));
    	nvps.add(new BasicNameValuePair("contactEmailId", ""));
    	nvps.add(new BasicNameValuePair("refId2", ""));
    	nvps.add(new BasicNameValuePair("detachInterval", ""));
    	nvps.add(new BasicNameValuePair("customerId", ""));
    	nvps.add(new BasicNameValuePair("refId1", ""));
    	nvps.add(new BasicNameValuePair("isRetail", ""));
    	nvps.add(new BasicNameValuePair("userId", ""));
    	nvps.add(new BasicNameValuePair("alternateEmailId", ""));
    	nvps.add(new BasicNameValuePair("cacheInterval", ""));
    	nvps.add(new BasicNameValuePair("vmEnabled", ""));
    	nvps.add(new BasicNameValuePair("collectUsage", ""));
    	nvps.add(new BasicNameValuePair("cloneProtection", ""));
    	post.setEntity(new UrlEncodedFormEntity(nvps, HTTP.UTF_8));
    HttpResponse response = httpclient.execute(post, context);
    HttpEntity entity = response.getEntity();
    byte[] b = null;
    if (entity != null) {
        long l = entity.getContentLength();
         b = new byte[(int) l];
         entity.getContent().read(b);
         entity.consumeContent();
     	}
    	return new String(b);
    	}
    	}



    

Sample Response

<emsResponse>
   <stat>ok</stat>
</emsResponse>
See Also:

Output Format for Failure

Error Codes

Error Code Description
100 Invalid request parameter.
101 You are not authorized to use this service.
113 Specify a valid Boolean value for {field}. Valid values are true or false. [Note: This error code is applicable for the fields - fetchCompleteEID, loginAllowed, isEnabled, vmEnabled, clonePotection, and optional.].
118 {field} should be of data type integer. [Note: This error code is applicable for the fields - featureId, License modelId, entId, ftrId, customerId, lmId, templateType, lineItemId, CustomerId, stationCount, status, and granularity.]
120 {field} value is less than the minimum permitted value {value}. [Note: This error code is applicable for the fields - productd, featureId,entId, billType, lmId, lastModified, timeZoneId, customerId, and granularity.]
122 {field} is a required field and should have a not null value. [Note: This error code is applicable for the fields - Eid, namespaceName, featureName, startDate, endDate, userIds, featureId, productName, productVersion, detailsLM, lmId, templateType, customAttribute, lineItemId, customerRefId, granularity, loginId, oldPassword, and newPassword.]
123 endDate should be of dataType Date in the format yyyy-mm-dd startDate should be of dataType Date in the format yyyy-mm-dd.
128 You should log on first.
132 The URL address does not exist.
511 Unable to find customer for customer name
513 The contact does not exist.
515 Invalid contact for this customer.
519 Customer not found for the given customerId.
615 End date and Start date cannot be null.
617 Start date cannot be greater than end date.
621 Entitlement does not exist. Retry with a correct ID.
647 Cannot update entitlement with lifeCycleState=complete.
1012 UserId can not be blank.
1067 An On-Premise entitlement can not be retail.
1078 Deployment type change not allowed.Please delete the entitlement and create a new one with the desired deployment type.
1081 Invalid Web service version provided
1084 No Web service version provided
1088 The EMS system is running on HTTPS. Please provide the correct Web service URL.
1126 Invalid value for stationCount. Valid values are between 1 - {configurable value}.
1158 Invalid value for parameter collectUsage. Valid values are 'On' or 'Off'.
1185 E-mail address is not valid