Provisioning Plans

>Dynamic Substitutions in Provisioning Plans

Prerequisites for Adding a Plan

A role that includes Catalog (Namespace) permissions for the relevant namespace. At minimum, the vendor user needs the Add permission. For details, see Roles.

Adding a Plan

A plan is a set of static and/or dynamic expressions in a given format that defines the criteria for provisioning an activated product, such as number of users, pods, and transactions. You can add a new plan that can be associated with a provisioning-enabled product.

To add a new plan:

1.From the navigation pane, select Provisioning > Plans.

2.Click Add Plan. The Add Plan page opens.

3.Define the Plan Attributes.

4.Click Save.

Plan Attributes

Attribute	Description	Required/Optional	Valid Values
Name	Name of the plan.	Required	>1 to 50 characters >Special characters allowed: ^ * ( ) + [ \ ? $ ~ ` ! @ # - _ = { } ] \| : ; ' , . / >Cannot contain: ' % & " < >
Description	Additional details about the plan.	Optional	>1 to 500 characters >Special Characters allowed: % & " < > ^ * ( ) + [ \ ? $ ~ ` ! @ # - _ = { } ] \| : ; ' , . /
Format	The text format in which the plan is written.	Read-only	JSON
Definition	A set of static and/or dynamic expressions specified in a given format that includes whatever is required for provisioning. Enter the content in JSON format. You can use dynamic expressions to replace attribute values. See the Definition Example below.	Optional	JSON

Definition Example

The following is an example of an endpoint definition for provisioning. Notice that both static values and dynamic substitutions (described below) are included.

{
"Provisioning ID": "$.provisioningRequest.id",
"Activation ID": "$.provisioningRequest.activationRef.activation.aid",
"Activation Date": "$.provisioningRequest.activationRef.activation.activationDate",
"Activated Product ID": "$.provisioningRequest.activationRef.activation.activationProductKey.activationItem.activationProduct.product.id",
"Customer Name": "$.provisioningRequest.entitlement.customer.name",
"Entitlement ID": "$.provisioningRequest.entitlement.eId",
"Activated Quantity": "$.provisioningRequest.activationRef.activation.activationQuantity",
"Product Name": "$.provisioningRequest.activationRef.activation.activationProductKey.activationItem.activationProduct.product.nameVersion.name",
"Product Type": "$.provisioningRequest.entitlement.productKeys.productKey[0].item.itemProduct.product.productType",
"No. of Pods": "5",
"Customer Information": "$.provisioningRequest.activationRef.activation.customer.identifier" 
}

>Example of a static value where the value is a constant:

"No. of Pods": "5",

>Example of a dynamic substitution where the value is derived from Sentinel EMS:

"Entitlement ID": "$.provisioningRequest.entitlement.eId",

$.provisioningRequest is a prefix that you use to define an attribute for which substitution is needed. Here, the entitlement ID (eId) is derived from the entitlement.

>Example of a dynamic substitution where the value is derived from a custom attribute that is defined for the entity

Available for:

•entitlement objects

•activation objects

•product key objects

•customer objects

The following example is for an entitlement object. Notice that you add the custom attribute directly after the entity object node. Additional examples are displayed in Object Nodes.

"Entitlement Custom Attribute": "$.provisioningRequest.entitlement.customAttributes.customAttribute[?(@.name == \"CustomAttributeEntityName\")].value",

Dynamic Substitutions in Provisioning Plans

You can use dynamic expressions to dynamically modify string-type provisioning attributes in a provisioning definition. A dynamic expression is an expression whose variable values are dynamically evaluated during activation. When preparing the provisioning request, the variables in the expression are replaced in the provisioning payload with the actual values defined in Sentinel EMS. This is known as dynamic substitution.

Dynamic expressions help software vendors add business critical provisioning payloads with just a few clicks without having to involve Thales Professional Services. Using dynamic expressions also eliminates the need for custom payload implementations. Vendor users with appropriate permissions can add dynamic information to the provisioning attributes of a provisioning definition.

>Syntax. You can use the JSON response of the provisioning endpoint in the Sentinel EMS REST APIs to build a dynamic expression. The JSON response is stored in the provisioningRequest object. The expression is enclosed in quotation marks and preceded by the $ symbol. In the following example, the evaluated value of id is assigned to the provisioning attribute.

"$.provisioningRequest.id"

In the following example, the dynamic expression is evaluated to display the value of the entitlement ID (eid) in an entitlement. :

"$.provisioningRequest.activationRef.activation.entitlement.eId"

>Case-sensitivity. To ensure correct evaluation, dynamic expressions must use the same case as specified in the REST API JSON response.

Incorrect: "$.provisioningRequest.activationRef.activation.Entitlement.EID"

Correct: "$.provisioningRequest.activationRef.activation.entitlement.eId

Object Nodes

Object nodes are entity-specific provisioning objects in Sentinel EMS REST APIs that you can use to retrieve information to build your dynamic expression. You can use the following objects for provisioning:

>provisioningRequest Object Node

>activation Object Node

>entitlement Object Node

>customer Object Node

>Custom Attributes in Dynamic Expressions

provisioningRequest Object Node

provisioningRequest: The object node that contains information about the provisioning request. The following example evaluates the value for a provisioning object attribute (id).

"Provisioning ID": "$.provisioningRequest.id"

For details on the paths and attributes that you can use, see Sentinel EMS REST API Reference.

activation Object Node

>activation: The object node that contains activation details. The following example evaluates the value for an activation object attribute (activationDate) that is nested in several levels of activation objects.

"Activation Date": "$.provisioningRequest.activationRef.activation.activationDate"

>activationProductKey: The object node that contains details about the activated product key. The following example evaluates the pkId attribute.

"Product Key ID Activation": "$.provisioningRequest.activationRef.activation.activationProductKey.pkId"

>activationProduct: The object node that contains details about all activated products in the activation. The following example evaluates the name attribute of the product object.

"$.provisioningRequest.activationRef.activation.activationProductKey.activationItem.activationProduct.product.nameVersion.name"

>activationfeatures: The object node that contains details about all the features in the activated product. The following example evaluates the values for all the features in the activated product. You could also expand the expression to drill down to evaluate specific attributes if needed.

"Feature Details": "$.provisioningRequest.activationRef.activation.activationProductKey.activationItem.activationProduct.activationFeatures"

For details on the paths and attributes that you can use, see Sentinel EMS REST API Reference.

entitlement Object Node

>entitlement: The object node that contains information about entitlements. The following example evaluates the value for an entitlement object attribute (eId).

"Entitlement ID": "$.provisioningRequest.entitlement.eId"

>productKey: The object node for the line item being activated in the entitlement. The following example evaluates the value for a product key object attribute (pkId).

"Product Key ID": "$.provisioningRequest.entitlement.productKeys.productKey[0].pkId"

>product: The object node The object node that contains details about the products in an entitlement. You can also include the product attribute in expressions for the product key object. The following example evaluates the value of a product attribute by product key.

"Product Type": "$.provisioningRequest.entitlement.productKeys.productKey[0].item.itemProduct.product.productType"

>feature: The object node that evaluates the values of all features in the entitlement. You can also include the feature attribute for the product key object. The following example evaluates the nameVersion value for a feature object attribute.

"Feature Name": "$.provisioningRequest.entitlement.productKeys.productKey[0].item.itemProduct.itemProductFeatures.itemProductFeature[0].feature.nameVersion"

For details on the paths and attributes that you can use, see Sentinel EMS REST API Reference.

customer Object Node

customer: The object node that evaluates the values of the customer object. The following example evaluates the value for a customer object attribute (name).

"Customer Name": "$.provisioningRequest.customer.name"

For details on the paths and attributes that you can use, see Sentinel EMS REST API Reference.

Custom Attributes in Dynamic Expressions

You can include custom attributes in the dynamic expressions for activation and entitlement objects at both the main object node level and at child object levels, as long as you specify the correct path. For example, you may want to include a custom attribute for the product key object in an entitlement.

You add custom attributes directly after the relevant object node using the syntax below. The closing quote relates to the opening quote in "$.provisioningRequest.

customAttributes.customAttribute[?(@.name == \"CustomAttributeName\")].value"

The following example evaluates the value of a custom attribute for the activation object. Notice that you add the custom attribute directly after the activation object node.

"Activation Custom Attribute": "$.provisioningRequest.activationRef.activation.customAttributes.customAttribute[?(@.name == \"ActivationCustomAttribute\")].value"

The following example evaluates the value of a custom attribute for the entitlement object at the entitlement object node level.

"Entitlement Custom Attribute": "$.provisioningRequest.entitlement.customAttributes.customAttribute[?(@.name == \"EntitlementCustomAttribute\")].value"

The following example evaluates the value of a custom attribute at a child level for the productKey object node. You add the custom attribute directly after the productKey object node.

"Product Key Custom Attribute": "$.provisioningRequest.entitlement.productKeys.productKey[0].customAttributes.customAttribute[?(@.name == \"ProductKeyCustomAttribute\")].value",

Troubleshooting Dynamic Expressions

Unsupported characters. If the evaluated value for a dynamic expression (the actual value that is generated during activation) includes non-supported characters, an error may be generated. This might occur, for example, if an evaluated value is not formatted properly. Suppose an evaluated value includes opening quotation marks without closing quotation marks. In this case, the JSON is not valid, and an error is generated.

Non-existent object. If a dynamic expression includes any object that does not exist in Sentinel EMS, then the dynamic expression is ignored and is excluded from the provisioning payload JSON file.

In the following example, ids—which is not a valid object—is included in the dynamic expression (instead of id):

"Provisioning ID": "$.provisioningRequest.ids",
"Activation ID": "$.provisioningRequest.activationRef.activation.aid"

In this case, the provisioning payload would exclude "Provisioning ID" and include only the evaluated value for "Activation ID", for example:

"Activation ID": "12345678-9876-5432-1234-567890987654"

Missing value. If a dynamic expression includes a valid object whose value cannot be evaluated, then a blank value is included in the provisioning payload.

Actions for Provisioning Plans

The following table lists the actions available for plans.

Action		Description
	Edit	Enables you to edit the attributes of an existing plan. For more details, see Editing an Entity. When you update a plan, all requests processed after the update use the new plan attributes.
	Copy	Duplicates an existing plan, enabling you to edit the copy and create a new plan.
	View Plan Definition	Displays the definition endpoint for the selected plan.
	Delete	Deletes the selected plan. Note: You cannot delete a plan that is associated with a product.