10Duke Enterprise release 3 documentation is no longer being updated

Provision licenses

In essence, software licenses represent the terms and conditions of use for your applications. With 10Duke Enterprise, you can provision (grant) licenses at the user level or at the organization level.

You may have use cases where you want to provision licenses (of any type) manually. Using 10Duke SysAdmin, you can easily do this for both organizations and users.

However, you will more commonly rely on the 10Duke Entitlement Management REST API and CRUD operations to automate the provisioning of licenses.

When provisioning licenses to an organization through the Entitlement Management REST API, the licenses are always created in the organization’s default entitlement. A default entitlement is automatically created for the organization if it doesn’t have one yet. Similarly, provisioning licenses to a user also creates an entitlement for them if they don’t have one yet.

The articles in this section cover examples on how to provision the most common license types through the Entitlement Management REST API.

API operations

10Duke Entitlement Management REST API operations for provisioning licenses:

Item URL (relative, prepend the environment base URL)
Provision a license to an organization POST /organizations/{orgId}/license-transactions
Provision a personal license to a user POST /users/{userId}/license-transactions
Update the organization licenses in a license transaction PUT /organizations/{orgId}/license-transactions
Update the personal licenses in a license transaction PUT /users/{userId}/license-transactions

Provision licenses in transactions

The Entitlement Management REST API uses the concept of a transaction that allows you to group multiple license grants together if needed.

This JSON example request body shows a simple transaction that contains the essential information for provisioning licenses using a single product package:

{
   "transaction": {
      "type": "Order",
      "externalId": "0000004556786",
      "items": [
         {
            "externalId": "0005404526916",
            "productId": "57042763-559c-4503-8db2-432d4fe82431",
            "quantity": 10,
            "licenseValidFrom": "2023-05-31T14:12:22.012Z",
            "licenseValidUntil": "2024-05-31T14:12:22.012Z"
         }
      ]
   }
}

In the externalId parameters, specify the IDs used in your external system, such as IDs related to the customer’s order.

In productId, specify the ID of the product package, and in licenseValidFrom and (optional) licenseValidUntil the validity time for the licenses.

In quantity, specify the number of product packages that licenses are provisioned with. Whether this quantity will be reflected as seats, use count, or use time in the licenses depends on the licensed items’ advanced settings in the product package, which define the type and amount of credit included in the product package for each licensed item.

For example, if the product package includes 50 seats for each licensed item, the example request above with quantity 10 would create 500 seats for each license.

See more details on the fields in the API reference.

Now, let’s say your customer purchased two products at a time. Now you’re provisioning licenses using two product packages in one transaction:

{
   "transaction": {
      "type": "Order",
      "externalId": "0000004556786",
      "items": [
         {
            "externalId": "0005404526916",
            "productId": "57042763-559c-4503-8db2-432d4fe82431",
            "quantity": 10,
            "licenseValidFrom": "2023-05-31T14:12:22.012Z",
            "licenseValidUntil": "2024-05-31T14:12:22.012Z"
         },
         {
            "externalId": "0005404526917",
            "productId": "7a195f0b-459b-4c60-ba5e-7a3d53133e28",
            "quantity": 15,
            "licenseValidFrom": "2023-05-31T14:12:22.012Z",
            "licenseValidUntil": "2024-05-31T14:12:22.012Z"
         }
      ]
   }
}

When you later want to update the licenses related to a specific transaction, you use the same transaction structure. Identify the transactions and transaction items using the IDs from your external system that you specified in the externalId fields.

When retrieving information on or deleting the licenses related to a transaction, you need to identify the transaction in the transactionId path parameter in the request. Use the ID from your external system that you specified in externalId at the transaction level when you provisioned the licenses.