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.

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

Exception Handling

If unsuccessful, throws LicensingException.