Methods: EntitlementOrderService

The createEntitlementLineItem operation adds one or more entitlement line items to a simple entitlement.

You can specify an activation ID using createEntitlementLineItem.

EXAMPLE

<urn:lineItems>
   <urn:activationId>
      <!--Optional:-->
      <!--type: string-->
      <urn:id>quae divum incedo</urn:id>
      <!--Optional:-->
      <!--type: boolean-->
      <urn:autoGenerate>true</urn:autoGenerate>
   </urn:activationId>

In this example, autoGenerate is true or false. If you specify false, it means you need to pass the ID value of the activation ID (which is the custom activation ID).

An activation ID must meet the following requirements:

• Maximum 255 characters

• Must not be empty

• Must be unique

• Invalid characters are:

      ,  "  &  %  ^  (  )  #  @  !  ~  /  <  >  `  }  {  =  |  .

The createSimpleEntitlement operation creates one or more simple entitlements. To use the Entitlement Order service to create an entitlement:

• There must be deployed products and license models in the FlexNet Operations database.

• There must be accounts in the FlexNet Operations database.

• You must provide any entitlement-time data that are required by the specified license model.

Note: Using the createSimpleEntitlement operation, it is possible to create a simple entitlement with no line items. Such an entitlement cannot be created through the Administrative Console. One created with web services will not appear in the Administrative Console, though it is saved in the FlexNet Operations database. Therefore, avoid using the createSimpleEntitlement operation to create an entitlement with no line items or with only maintenance items.

You can specify an activation ID using createSimpleEntitlement.

EXAMPLE

<urn:lineItems>
   <urn:activationId>
      <!--Optional:-->
      <!--type: string-->
      <urn:id>quae divum incedo</urn:id>
      <!--Optional:-->
      <!--type: boolean-->
      <urn:autoGenerate>true</urn:autoGenerate>
   </urn:activationId>

In this example, autoGenerate is true or false. If you specify false, it means you need to pass the ID value of the activation ID (which is the custom activation ID).

An activation ID must meet the following requirements:

• Maximum 255 characters

• Must not be empty

• Must be unique

• Invalid characters are:

      ,  "  &  %  ^  (  )  #  @  !  ~  /  <  >  `  }  {  =  |  .

The createWebRegKey operation adds one or more web register keys to one or more bulk entitlements, either asynchronously or synchronously. By default, web register key creation is asynchronous. To use the Entitlement Order service to load web register keys:

There must be bulk entitlements in the FlexNet Operations database.

If web register keys are going to be imported asynchronously, the Importing Bulk Entitlement Web Register Keys alert must be configured. See the FlexNet Operations Online Help for instructions. Before checking whether the web register keys were really added, wait until after the import has triggered. With synchronous processing, the Web services client will be blocked until the request is completely processed. Therefore, use synchronous processing to load only for small numbers of web register keys at a time. The Importing Bulk Entitlement Web Register Keys alert does not have to be configured to load web register keys synchronously.

The emailActivatableItem operation sends an entitlement certificate for a single activatable item via email. To send an entitlement certificate for an activatable item as an email attachment using the Entitlement Order service:

• Configure the from-address for the entitlement email. See theFlexNet Operations Installation Guide.

• Customize the entitlement email template and entitlement certificate template, if necessary. See the FlexNet Operations Producer Portal Help Guide.

• An activation ID for an activatable item must exist in the database.

• At least one email address must be provided.

When an email template is specified when creating or updating an entitlement, that template will be given preference in sending the email. If no email template is specified, the template configured for the license technology will be selected. If no email template is configured for the license technology, then the default email template will be selected. However, if the selected template is not active or if the send indicator is not switched on, no email will be sent.

The emailEntitlement operation sends an entitlement certificate via email. To send an entitlement certificate as an email attachment using the Entitlement Order service:

• Configure the from-address for the entitlement email. See the FlexNet Operations Installation Guide.

• Customize the entitlement email template and entitlement certificate template, if necessary. See the FlexNet Operations Producer Portal Help Guide.

• An ID for an entitlement must exist in the database.

• At least one email address must be provided.

When an email template is specified when creating or updating an entitlement, that template will be given preference in sending the email. If no email template is specified, the template configured for the license technology will be selected. If no email template is configured for the license technology, then the default email template will be selected. However, if the selected template is not active or if the send indicator is not switched on, no email will be sent.

The getActivatableItemsQuery operation returns the activatable line items that match specified criteria.

Note: This operation does not return maintenance line items.

The getEntitlementLineItemPropertiesQuery operation returns all entitlement line items and web register keys based on the provided search criteria, including draft entries.

This operation works similarly to the operation getActivatableItemsQuery. However, the response from getEntitlementLineItemPropertiesQuery is highly configurable. You can use it to select only the data you need in a given response.

Note: With this query, maintenance line items will not be returned if the product type Maintenance is used in the search criteria. Associated maintenance line items can be obtained by using the new response configuration element maintenance.

Use caution when crafting queries that may return excessive numbers of responses. The following error, ORA-01795: maximum number of expressions in a list is 1000, has be seen when performing searches via FlexNet Operations landing pages or web service queries when:

1. FlexNet Operations is connected to an Oracle database
2. Certain types of searches in the UI or web services return > 1000 items, for example, the entitlements or line item landing pages and getEntitlementsQuery or getEntitlementLineItemPropertiesQuery.

If the error is seen in the FlexNet Operations UI, consider setting the Entitlement Records per Page and Line Items Page Size per Entitlement settings to 1000 or less. If the error is seen in a web service query, set the batch size to 1000 or less and page through the results.

The getEntitlementsQuery operation returns the entitlements that match specified criteria. The response data is sorted by the most recent line item.

Tip: For more optimal memory usage, consider using getActivatableItemsQuery instead of getEntitlementsQuery to retrieve policy information for a particular line item. getActivatableItemsQuery loads only the information for the specified activation while getEntitlementsQuery loads information for the all the activations for a given EntitlementID. See getActivatableItemsQuery.

The getExactAvailableCount operation provides the exact, current available count for a specified line item. This operation allows users to obtain a potentially more precise count than those available in the administrative console UI or via other web service operations.

The FlexNet Operations UI and other web service operations do not evaluate the count of available copies when an upgrade is created. Therefore it is possible to create an upgrade count that exceeds the number of available copies; however, the count is evaluated at fulfillment time. On fulfillment, upgrades that exceed the available count are rejected. To avoid errors at fulfillment time, users may use getExactAvailableCount, which returns exact number of copies available for an upgrade fulfillment, for example, without having to return any previous fulfillments.

The getMatchingBulkEnts operation returns bulk entitlements suitable to receive the web register keys from a splitBulkEntitlement operation. The getMatchingBulkEnts operation searches for bulk entitlements with the target account in the target tier that match the bulk entitlement you want to split. Any bulk entitlement returned by this operation can receive the web register keys as the result of the split operation.

To be considered a match, the bulk entitlement that is the target of the split must share the following attributes with the bulk entitlement that is the source of the split:

• Orderable

• License model

• License term (permanent, expiration date, duration)

• Version date details (options, date, duration)

• Line item state

• License model policies

• License model attributes

The getMatchingLineItems operation returns line items suitable to receive the count from a splitLineItem operation. The getMatchingLineItems operation searches for entitlement line items in entitlements with the target account in the target tier that match the line item you want to split. Any line item returned by this operation can receive the counts as the result of the split operation.

To be considered a matching line item, the line item that is the target of the split must share the following attributes with the line item that is the source of the split:

• Orderable

• License model

• License term (permanent, expiration date, duration)

• Version date details (options, date, duration)

• Line item state

• License model policies

• License model attributes

Note: If the source line item has a parent line item, then the entire ancestor tree is scanned to ensure that the parent line items of the target line item also match.

The mergeEntitlements operation merges assets of one account with those of another account. The following types of assets can be merged:

• Entitlements and fulfillments—The state of the transferred entitlements and fulfillments are preserved during the merge.

• Users

The splitBulkEntitlement operation assigns a specified number of unredeemed web register keys to a related account in a different distribution tier. The web register keys that are split can be transfered to:

• A compatible existing bulk entitlement (transfers the web register keys to that bulk entitlement).

• An existing line item that has been redeemed from a compatible web register key (adds the counts from the transferred web register keys to the count of the line item).

• A new bulk entitlement.

Only publisher users, or channel partner users with sufficient privileges in the account that is the current owner, can perform a splitBulkEntitlement operation.

Note: You cannot control the specific web register keys that splitBulkEntitlement transfers.

The splitLineItem operation assigns some portion of an entitlement line item’s count from the current owner to a related account in a different distribution tier. This operation can either increase the count of an existing entitlement line item at the target account or create a new entitlement, if no matching entitlements exist at the target account. Only publisher users, or channel partner users with sufficient privileges in the account that is the current owner, can perform a splitLineItem operation.

Note: When a line item associated with a maintenance is split, the maintenance is also split. Likewise, when a new entitlement is created as the result of a split, a new maintenance is created and associated with the new entitlement.