getInfo

String getInfo(Attribute attribute, string scope, string query)

This API performs the following:

>Provides provisioning information related to entitlements, products, and features.

>Provides license consumption information. For example:

Number of running sessions in the case of licenses with the limited concurrency limit

Number of usage count consumed in the case of licenses with the limited usage limit

>Checks the license availability for a user.

This API provides information across all entitlements for the given feature name, feature version, and Identity (which contains the customer-user pair).

The information is provided in the XML format.

Parameters

Parameter Description
attribute[in]

Reserved for future use. Use NULL as the value for this argument.

scope [in]

It defines the search parameters on which the API has to get information. The output is an XML. The results are filtered based on the specified parameters.

query [in]

XML specifying the format of the output.

NOTE   Currently the query executes for all entitlements, and returns the information in a hierarchical format.

Input Scope and Query XMLs

This section shows how the input XMLs are formed.

Scope

scope="<?xml version=\"1.0\" encoding=\"UTF-8\"?>" + 

	    "<sentinelScope>" + 
              "<identity>" + identitySerializedData + "</identity>" + 
              "<feature index=\"0\">" + 
	            "<name>" +featureName + "</name>" +
                   "<version>" + featureVersion + "</version>" + 
              "</feature>" + 
	       “<product>” + 
                   “<name>” + productName + “</name>” +   
	            “<version>” + productVersion + “</version>” +  
	       “</product>” + 
	       “<entitlement>” + 
	             “<entitlementId>” + EID + “</entitlementId>” + 
	             “<userSpecificEntitlement>” + true/false + “</userSpecificEntitlement>”
	    "</sentinelScope>";

Here, you need to replace the values in the bold font with those values for which want you to retrieve information.

To be Replaced Replacement Value
identitySerializedData The serialized identity string containing the user name and customer ID. The identity string is obtained from the serialize API of the Identity Class.
featureName (Optional) The feature name.
featureVersion

(Optional) The feature version.

NOTE   If a feature is created with version from EMS, it become mandatory to provide the feature version along with the feature name in the request

productName (Optional) The product name.
productVersion

(Optional) The product version.

NOTE   If productVersion is provided, the filtering is performed for the exact product name and product version pair. Otherwise, details of all products are returned.

EID (Optional) The entitlement ID.
userSpecificEntitlement

(Optional) A Boolean parameter to filter results based on the user name specified in Identity. It has one of the following values:

>True : Enable the user-specific filtering. The request, in this case, returns only those named entitlements to which the given user is associated and all unnamed entitlements.

>False : Disable the user-specific filtering. In this case, all named and unnamed entitlements are returned.

The default value is False.

Input Combinations

Following are the combinations for the request parameters:

Customer

Entitlement

Product

Feature

Result

Not null

Null

Null

Null

Information of all entitlements, products, and features related to the given customer and user.

Not null

Not null

Null

Null

Information of all features and products for the given EID.

Not null

Not null

Not null

Null

Information of all features for the given product and EID.

Not null

Not null

Not null

Not null

Information for the given feature, product, and EID.

Further filtering can be done based on userSpecificEntitlement parameter and user name given in Identity.

Query

<sentinelQuery query=\"entitlementInfo\"/>

Returns

Requested information in XML format.

Elements in the getInfo Output XML

The following table describes the elements present in the output XML of the getInfo API:

Element Description
Entitlement Information
entitlementId The entitlement ID (known as EID in EMS).
Product Information
productName The name of the product.
productVersion The version of the product.
Feature Information  
featureId The integer ID of the feature.
featureName The name of the feature.
featureVersion The version of the feature.
usable

Specifies if the license is usable or not.

Its value can be one of the following:

>true: Indicates that the license is usable.

>false: Indicates that the license is not usable.

usabilityStatus

The usability status of the feature.

Its value can be one of the following:

>Available: Indicates that the license is ready for use.

>An error string: Indicates that the license is not available. For example, the error string can be:

License Information  
concurrencyLimit

The maximum number of concurrent instances allowed for a feature.

Its value should be in the range 1-32752. The "unlimited" value indicates that the concurrency limit is not set, or the concurrency is unlimited.

NOTE   When using the EMS GUI, to specify unlimited concurrency, the Unlimited check box is selected. The 0 value is not allowed from the EMS GUI. When using an EMS web service, the 0 value is provided to specify unlimited concurrency. For license attribute details, refer to the EMS Guides.

The default value is "unlimited".

If the concurrencyLimit contains a finite value, the getInfo output also contains the following elements: concurrencyCriteria and runningSessions.

NOTE   Both usage limit and concurrency limit are "unlimited' by default. But only one of these limits can be set to a finite value at a time.

concurrencyCriteria

The criteria of counting concurrent instances.

Its value can be one of the following:

>per login: Count each login request as an instance. If the same user logins to a feature multiple times, each login will consume one concurrency limit.

>per user: Count each user as an instance. All the login requests by the same user are counted as one instance, and consume only one concurrency limit.

This element is present in the XML only if concurrencyLimit contains a finite value.

runningSessions

The number of active concurrent instances.

Its value cannot exceed the concurrency limit.

This element is present in the XML only if concurrencyLimit contains a finite value.

startDate

The license start date and time. If a start date is given for a license, the feature can not be used before that date and time.

Date is in the yyyy-mm-dd format, and time is in the hours:minutes:seconds format.

The UTC time zone is used.

Example:

<startDate>2016-08-03T00:00:00Z</startDate>
endDate

The license expiration date and time. The license expires when the end date is reached.

Date is in the yyyy-mm-dd format, and time is in the hours:minutes format. If the end date is set to 'Never Expires' in EMS, then the getInfo API returns 2500-12-31 12 AM.

The UTC time zone is used.

Example:

<endDate>2500-12-31T00:00:00Z</endDate>
vendorInfo

The vendor-defined information for a feature specified from EMS (in the Vendor Info license attribute), for example, employee role or data download speed.

A software vendor can query vendorInfo values in an application by using the getInfo API. Based on the API results, the vendor can define application logic or can implement dynamic decision making capabilities.

This field can contain up to 255 alphanumeric characters.

Note:

>This attribute/element is not used by the Sentinel Cloud Connect in license enforcement.

endDateGraceDuration

The additional number of days for which the license can be used after the end date has been reached. The range is 0 to 365 days.

This element is mapped to the Grace Days attribute of the Connected license model of EMS.

usageLimit

The maximum number of times a feature can be used.

Its value is an integer in the range of 1 to 2147483647. The "unlimited" value indicates that the usage limit is not set, or unlimited usage counts are allowed.

NOTE   When using the EMS GUI, to specify unlimited usage counts, the Unlimited check box is selected. 0 is not allowed from the EMS GUI. When using an EMS web service, the 0 value is used to allow unlimited usage count. For license attribute details, refer to the EMS Guides.

If usageLimit contains a finite value, the getInfo output also contains the following elements: usageCountGrace and usageCountConsumed.

NOTE   Both usage limit and concurrency limit are "unlimited' by default. But only one of these limits can be set to a finite value at a time.

usageCountGrace

The number of additional usage counts allowed for a feature after the usage limit has been reached.

This element is present in the getInfo output only if the usageLimit contains a finite value.

Its value is an integer in the range of 1 to 2147483647.

usageCountConsumed

The number of usage counts that have been consumed so far.

This element is present in the getInfo output only if the usageLimit contains a finite value.

This element is mapped to the Grace Limit attribute of the Connected license model of EMS

Examples of the getInfo Output XML

The sentinelInfo structure contains the output of getInfo.

NOTE   Both usage limit and concurrency limit are "unlimited' by default. But only one of these limits can be set to a finite value at a time.

Case 1: When an entitlement contains a feature with unlimited concurrency and unlimited usage count

NOTE   The response shown below is for a given entitlementId, productName, and productVersion.

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<sentinelInfo>
	<entitlement>
		<entitlementId>3c6d37dd-7c23-453d-8f07-96f776d301c7</entitlementId>
		<product>
			<productName>calculator</productName>
			<productVersion>1</productVersion>
			<feature>
				<featureId>17</featureId>
				<featureName>add</featureName>
				<featureVersion>1</featureVersion>
				<usable>true</usable>
				<usabilityStatus>available</usabilityStatus>
				<concurrencyLimit>unlimited</concurrencyLimit>
				<startDate>2016-07-18T00:00:00Z</startDate>
				<endDate>2017-07-18T00:00:00Z</endDate>
				<vendorInfo>vendorinfo</vendorInfo>
				<endDateGraceDuration>2</endDateGraceDuration>
				<usageLimit>unlimited</usageLimit>
			</feature>
		</product>
	</entitlement>
</sentinelInfo>

Case 2: When an entitlement contains a feature with limited concurrency

NOTE   The response shown below is for a given entitlementId, productName, and productVersion.

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<sentinelInfo>
	<entitlement>
		<entitlementId>3c6d37dd-7c23-453d-8f07-96f776d301c7</entitlementId>
		<product>
			<productName>calculator</productName>
			<productVersion>2</productVersion>
			<feature>
				<featureId>19</featureId>
				<featureName>add</featureName>
				<featureVersion>1</featureVersion>
				<usable>true</usable>
				<usabilityStatus>available</usabilityStatus>
				<concurrencyLimit>5</concurrencyLimit>
				<concurrencyCriteria>per user</concurrencyCriteria>
				<runningSessions>0</runningSessions>
				<startDate>2016-07-18T00:00:00Z</startDate>
				<endDate>2017-07-18T00:00:00Z</endDate>
				<vendorInfo>vendorinfo</vendorInfo>
				<endDateGraceDuration>3</endDateGraceDuration>
				<usageLimit>unlimited</usageLimit>
			</feature>
		</product>
	</entitlement>
</sentinelInfo>

For a feature with limited concurrency, the following attributes are visible in the getInfo output:

  • concurrencyLimit (It contains a finite integer value for concurrent licenses. In other cases, its value remains "unlimited").
  • concurrencyCriteria
  • runningSessions

Case 3: When an entitlement contains a feature with limited usage count

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<sentinelInfo>
	<entitlement>
		<entitlementId>3c6d37dd-7c23-453d-8f07-96f776d301c7</entitlementId>
		<product>
			<productName>calculator</productName>
			<productVersion>3</productVersion>
			<feature>
				<featureId>16</featureId>
				<featureName>add</featureName>
				<featureVersion>1</featureVersion>
				<usable>true</usable>
				<usabilityStatus>available</usabilityStatus>
				<concurrencyLimit>unlimited</concurrencyLimit>
				<startDate>2016-07-18T00:00:00Z</startDate>
				<endDate>2017-07-18T00:00:00Z</endDate>
				<vendorInfo>vendorinfo</vendorInfo>
				<usageLimit>5</usageLimit>
				<usageCountConsumed>0</usageCountConsumed>
				<usageCountGrace>10</usageCountGrace>
				<endDateGraceDuration>2</endDateGraceDuration>
			</feature>
		</product>
	</entitlement>
</sentinelInfo>

For a feature with limited usage count, the following attributes are visible in the getInfo output:

  • usageLimit (It contains a finite integer value indicating the maximum number of usage counts allowed. In other cases, its value remains "unlimited").
  • usageCountGrace
  • usageCountConsumed

See Also

Finding the expiration date, usability status, and available usage count of a license

Exception Handling

If unsuccessful, throws LicensingException.