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:
|
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:
|
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.