PATCH licenseSession

Updates the license authorization session of a feature (obtained using the POST request).

NOTE This request should be placed after the POST licenseSession request.

Additional Details

The PATCH licenseSession request performs the following functions:

>Avoids premature termination of sessions: It refreshes the sessions periodically to keep the sessions alive for a longer period. Refreshing a session ensures that the background process does not terminate the session after a specified time.

>Notifies an application about terminated sessions:It helps identify if a session has been terminated or is still valid. For example, If a session is terminated by a background process or a vendor's administrator, an error is returned and the application does not allow the user to consume the feature further avoiding the license overuse.

>Cleans abandoned sessions: The background process checks for the presence of abandoned sessions and closes them. An abandoned session is the one where the request to stop or update a license session does not reach the Sentinel Cloud Connect within a given time; for example, in the case of client or browser crash. This way the background process cleans abandoned sessions and makes the concurrency available for consumption.

>Helps in usage tracking: The abandoned sessions are forced complete to ensure integrity of usage data.

>Determines the duration of a session: Let us say, an application ran for 1 month and then crashed suddenly. The last refresh time of the application will help to take into account the entire duration for which the application ran, and charge the customer for the same.

For more details about abandoned sessions, see .

When to use the PATCH licenseSession request?

The licensed application should use this request periodically for refreshing sessions.

For example, if the application allows online movie watching, then the application brings buffer only for certain duration, then it fetches next buffer for next duration, and so on. The application places this request and fetches the next buffer only if the session is still valid.

If a user exits the application without proper exiting the license session or due to any reason, the refresh request will return failure, and the background process will auto-complete the session to free the concurrency.

Type

PATCH

URI

<SCC_URL>/licenseSessions/{licenseSessionId}

The <SCC_URL> represents the Cloud Connect URL sent by Directory Service (also called, YPS) in response to the POST registration request.

Example URI

 https://fra01-he02.trial.sentinelcloud.com/scc/licenseSessions/ rT9LfprcD%2FI6fwBwn7L9nK3mNAall25C%0D%0AvZAizsyn%2BVdJIT8GoRsCvAZrty

URI Parameter

licenseSessionId (mandatory)

NOTE The licenseSessionId parameter passed to a web service must be URL encoded.

Request Body

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<licenseSession>
	<usageCountMultiplier>11</usageCountMultiplier>
</licenseSession>

If the request body is not provided, the request updates the license session time stamp in the refresh time.

Elements in the Request XML

Parameter	Description
usageCountMultiplier	(Optional) This attribute is used to specify the number of usage count consumed in a license session. It is also used to return the unconsumed count at the time of license session update. By default, a license session consumes one usage count and this count is acknowledged at the start of the session. At times, a vendor may want to specify a count more than one, either at the start of the session and/or at the time of session update. To consume more than one usage count for a given session, set the usage count multiplier at the start of a license session. It is recommended not to specify usage count multiplier at the license session update - for licenses where the usage limit is defined. This is because the final result could be a negative value, which indicates overuse. Its value can be any integer ranging from -2147483647 to 2,147,483,647 (including grace value). The default value is: > 1 at the start of a license session API >0 at the update of a license session NOTE From version 4.4.350 onwards, this parameters accepts negative values to return the unconsumed count at the time of license session update. The support for negative usageCountMultiplier value is available only for the Sentinel Cloud Connect Web Services for the Connected mode. The total usage count consumed in a particular session is calculated by adding the usage count multiplier values specified at the start and update of a license session. usage count consumed = usageCountMultiplier at the start(+ve) + usageCountMultiplier at the update(+ve/-ve) >If usageCountMultiplier is not provided at start and update, one (1+0) usage count is consumed. >If usageCountMultiplier is provided at the start but not at update, the usage count equals the value specified at the start. >If usageCountMultiplier is not provided at the start but at the update, the usage count equals one plus the value specified at the update. >If usageCountMultiplier is provided at both the start and update, the usage count is the sum of both the values. The usage count consumed by a license session is visible in all EMS usage reports. Let us understand this with the help of an example. Example: The value of the usageCountMultiplier provided at the start of the license session (POST licenseSession) is 20. To return 5 as the unconsumed count, you can provide -5 as the usageCountMultiplier value during the session update (PATCH licenseSession). This will return 5 as the value of the unconsumed count. NOTE This parameter’s start and end tags should contain a valid value. If you provide blank tags or an invalid value, an error is returned. If you do not provide tags, the default value is used.

Parameter

Description

usageCountMultiplier

(Optional)

This attribute is used to specify the number of usage count consumed in a license session. It is also used to return the unconsumed count at the time of license session update.

By default, a license session consumes one usage count and this count is acknowledged at the start of the session. At times, a vendor may want to specify a count more than one, either at the start of the session and/or at the time of session update. To consume more than one usage count for a given session, set the usage count multiplier at the start of a license session.

It is recommended not to specify usage count multiplier at the license session update - for licenses where the usage limit is defined. This is because the final result could be a negative value, which indicates overuse.

Its value can be any integer ranging from -2147483647 to 2,147,483,647 (including grace value). The default value is:

> 1 at the start of a license session API

>0 at the update of a license session

NOTE
From version 4.4.350 onwards, this parameters accepts negative values to return the unconsumed count at the time of license session update.
The support for negative usageCountMultiplier value is available only for the Sentinel Cloud Connect Web Services for the Connected mode.

The total usage count consumed in a particular session is calculated by adding the usage count multiplier values specified at the start and update of a license session.

usage count consumed = usageCountMultiplier at the start(+ve) + usageCountMultiplier at the update(+ve/-ve)

>If usageCountMultiplier is not provided at start and update, one (1+0) usage count is consumed.

>If usageCountMultiplier is provided at the start but not at update, the usage count equals the value specified at the start.

>If usageCountMultiplier is not provided at the start but at the update, the usage count equals one plus the value specified at the update.

>If usageCountMultiplier is provided at both the start and update, the usage count is the sum of both the values.

The usage count consumed by a license session is visible in all EMS usage reports.

Let us understand this with the help of an example.

Example: The value of the usageCountMultiplier provided at the start of the license session (POST licenseSession) is 20. To return 5 as the unconsumed count, you can provide -5 as the usageCountMultiplier value during the session update (PATCH licenseSession). This will return 5 as the value of the unconsumed count.

NOTE This parameter’s start and end tags should contain a valid value. If you provide blank tags or an invalid value, an error is returned. If you do not provide tags, the default value is used.

Request Schema

<?xml version="1.0"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
	<xs:element name="licenseSession">
		<xs:complexType>
			<xs:sequence>
				<xs:element type="xs:int" name="usageCountMultiplier" minOccurs='0'/>
			</xs:sequence>
		</xs:complexType>
	</xs:element>
</xs:schema>

Response Body

In case of success:


<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<licenseSession>
	<status>Ok</status>
</licenseSession >

In case of error:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<error>
	<status>Fail</status>
	<errorCode>error_code</errorCode>
	<errorDescription>error_message</errorDescription>
</error>

Response Schema

<?xml version="1.0"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
	<xs:element name="licenseSession">
		<xs:complexType>
			<xs:sequence>
				<xs:element type="xs:string" name="status"/>
			</xs:sequence>
		</xs:complexType>
	</xs:element>
</xs:schema>

Error Codes

Error Code	Description	Status Code
2013	license sessionId is invalid	400 Bad request
2016	Error occurred in usage update	400 Bad request
2025	Session terminated	403 Forbidden
2042	Maximum value of Usage Count allowed reached	403 Forbidden