Migrating your Qlik Cloud tenant to a new subscription or entitlement

[DaveChannon]

Qlik Cloud tenants are the highest level of logical isolation provided to our customers. The subscriptions and associated entitlements (also known as licenses) that customers purchase from Qlik are not fixed to these tenants. When needed, a customer can update the entitlement used by their tenant. This article covers how to do this, as well as all considerations before moving.

You should not attempt to update your tenant entitlement unless directed to do so by Qlik, or you are an OEM customer who is managing multiple entitlements for their estate.

Content:

• Why you might need to update your entitlement
• Considerations
• How to update the entitlement for your tenant
• 1. Retrieve the signed license key (SLK) for your entitlement
• 2. Export the current user assignments
• 3. Update the tenant entitlement
• 4. Reassign user assignments

Why you might need to update your entitlement

There are three scenarios where you might need to update your entitlement:

1. You have been directed to do so by Qlik support or another Qlik team
2. You are an OEM customer who purchased multiple subscriptions, and who wishes to merge these into your new multitenant entitlement
3. You are an OEM customer who is managing multiple multitenant entitlements

If you are an OEM or Enterprise customer leveraging multiple tenants in Qlik Cloud, please also consider reviewing the Platform Operations series on qlik.dev to learn more about managing these estates prior to changing your entitlements.

Considerations

Before you begin migrating your subscription or entitlement, consider:

• When changing entitlements, all assignments will be lost. This means any user who has previously been assigned a named entitlement (such as a professional-, analyzer-, full- or basic user entitlement) will need to have their entitlement reassigned. 
• Any entitlement changes are immediate. If your new entitlement is missing features or capabilities compared to the original entitlement, or it has less capacity than the original entitlement, then components in the tenant may not function as expected, or users may be impacted. As a good practice, verify the new entitlement on another tenant before applying the changes, or apply the change outside of working hours for the majority of your users.
• Original assignments are not restored if you re-apply the original entitlement. Although you are able to re-apply the original entitlement, it will not restore the original assignments, and some capabilities that may have been disabled through the move might need manually re-enabling.
• The Service Account Owner of the entitlement is the individual who has access to the tenant recovery capabilities. Make sure you know who the Service Account Owner is for the new entitlement before you move the tenant.

How to update the entitlement for your tenant

Updating the entitlement requires four steps:

1. Retrieve your signed license key 
2. Export the current user assignments
3. Update the tenant entitlement
4. Reassign  User assignments

1. Retrieve the signed license key (SLK) for your entitlement

Your SLK is available through:

• The welcome email sent when the entitlement was generated
• Qlik support, if you only have the numeric subscription or entitlement number available
• Any tenant already deployed to that entitlement
  
  To find the entitlement via an existing tenant, log into a tenant linked to the entitlement, and navigate to https://<hostname>.<region>.qlikcloud.com/api/v1/licenses/overview
  
  This will return a license definition, from which you can pull out the SLK. In the example below, you can see "licenseKey". We need the long value, e.g.: "eyJhbGciOiJSUzUxMiIsImtpZCI6ImE...".
  
  
  {"licenseNumber":"1234 5678 1234 5678","licenseKey":"eyJhbGciOiJSUzUxMiIsImtpZCI6ImEzMzdhZDE3LTk1ODctNG....","valid":"./2023-10-08","status":"Ok",...}

2. Export the current user assignments

When you migrate between entitlements, any user assignments will be reset. You will need to export any current assignments if you wish to reassign them. 

There are three ways of doing this:

1. Call the licenses/assignments API endpoint via script:
   
   
   curl -L -X GET 'https://<hostname>.<region>.qlikcloud.com/api/v1/licenses/assignments' \

   -H 'Authorization: Bearer ey....' \

   -H 'Content-type: application/json' \

   -H 'Accept: application/json'
   
   
   
2. Log into the tenant you wish to bring onto the entitlement as a user with the Tenant Admin role. Then open the following address: https://<hostname>.<region>.qlikcloud.com/api/v1/licenses/assignments

   
   If you have many users, both option a and b will require you to paginate to get all results.
   
   Results will look like:

   {

       "data": [

           {

               "subject": "QLIKBOT\\f0e92f326ac77427df155940fec39e6a",

               "type": "professional",

               "excess": false,

               "created": "2022-10-20T13:46:29.474Z"

           },

           {

               "subject": "auth0|a08d000001f0wjria3",

               "type": "professional",

               "excess": false,

               "created": "2022-10-06T09:21:13.265Z"

           },

           {

               "subject": "QLIKBOT\\52b7313d6705e2873eaadb9be23d8c06",

               "type": "professional",

               "excess": false,

               "created": "2022-10-05T12:46:01.716Z"

           }

       ],

       "links": {

           "next": {

               "href": ""

           },

           "prev": {

               "href": ""

           }

       }

   }
   
   
   
3. Log into the tenant you wish to bring onto the new entitlement as a user with the Tenant Admin role, and use an automation to export these assignments. The example below returns the list as a table to the automation output. To import this automation, simply create a new automation, right click, then import the workspace JSON file attached to this post (automation-template-export-license-assignments.json).
   
   Output of attached automation template
   
   Note that for tenants with a large number of users, you will need to output the records to a file as the output window will eventually be capped.

3. Update the tenant entitlement

1. Log into the tenant you wish to bring onto the new entitlement as a user with the Tenant Admin role
2. Click your Profile
3. Click About
   
   
   
   
4. Click the key icon next to Subscription ID
   
   
   
   
5. Enter the SLK for the multitenant entitled subscription
   
   
   
   
6. Click Submit

 

4. Reassign user assignments

If required, reassign entitlements which were exported in step 2. You can do this in two ways:

1. Manually, by navigating to the management console.  See Assigning user entitlements | Help.qlik.com.
2. Programmatically by using automations or raw API calls.
   
   An example API call to assign an entitlement is shown below.
   
   Example cURL code to assign an entitlement (can also be done in automations):
   

   curl -L -X POST 'https://<hostname>.<region>.qlikcloud.com/api/v1/licenses/assignments/actions/add' \
   -H 'Authorization: Bearer ey...' \
   -H 'Content-type: application/json' \
   -H 'Accept: application/json' \
   --data-raw '{
       "add": [
           {
               "subject": "1ef2caed0dbe0a66a24ccadf61546099",
               "type": "professional"
           }
       ]
   }'

The information in this article is provided as-is and to be used at own discretion. Depending on tool(s) used, customization(s), and/or other factors ongoing support on the solution below may not be provided by Qlik Support.