Advanced License Management Topics : CloudBlue Technical Support

This article serves as an extension of the Business Automation (formerly PBA) Provider's Guide in respect to license management. Refer to the Provider's Guide for basic information. This article covers the following topics in detail:

Extending License Offering

1.1 New License Class

1.2 New Feature Group

1.3 New Feature

1.4 New Upgrade Option
Troubleshooting

2.1 Order Failure

2.2 Problems with License Synchronization

2.3 License Class/Feature Is Missing within KA Plugin Tabs
Known Issues and Limitations

Appendix A. API Methods for Additional License Classes Management

Appendix B. API Methods for Feature Groups Management

Appendix C. API Methods for License Upgrade Options Management

1. Extending License Offering

Business Automation is shipped with a preconfigured set of license classes/features for reselling. However, in some cases, this set needs to be extended (for example, when a new APS application is released for selling or a new feature for an existing license class is introduced).

1.1 New License Class

Follow the steps below to add a new license class for reselling in Business Automation:

Add a new license class in the Business Automation Provider Control Panel (CP) at External Systems Director > License Manager > License Classes. Click the Add New License Class button. The Adding new license class form is displayed.
Specify the Keytype Identifier and the License Class Name parameters. For the correct values, refer to the KA Partner API Reference and Developer's Guide.
Specify the Description, Billing Type, and Is Additional parameters. Refer to Online Help for definitions of these parameters.
If the new license class refers to an APS application, then specify the APS License Type parameter. For the correct value, refer to the APP- META.xml file in the APS application: the /license/type tag in the <requirements> section contains the license type. For example, for the excerpt <requirements> <l:license id="main" type="urn:pla:pinnacle-cart:1"> <l:need-query/> </l:license> </requirements>, the APS License Type must be set to urn:pla:pinnacle-cart:1.
If the license class is additional, add it as an add-on to the other license class. This action requires the XMLRPC call to the Business Automation method. Refer to Appendix A for details.
Add features to the created license class. Open the license class details, switch to the Features tab, and click Add New Feature. The Adding new feature form is displayed. Fill in the form.
Specify the Feature ID parameter. For the correct value, refer to the KA Partner API Reference and Developer's Guide.
Specify the feature group for the new feature (refer to the New Feature Group subsection if there is no appropriate feature group in Business Automation).
Synchronize the license management plug-in. For details, refer to the Provider's Guide > Managing Licenses > Synchronize List of License Classes section.
Add resources for the added license class and its features. Resources should be based on the KAGATE (License Management) service gate. The Command parameter value is the license class or feature keytype identifier. For details, refer to the Provider's Guide > Managing Resources section. Use the Plesk 9.0 for Virtuozzo resource as an example.
Add a resource category for the added resources. See the category Additional Products as an example of the category for the license class and Domain Limit as an example of the category for additional features.
Configure resource dependencies at Product Director > Resource Manager > Resources. For each resource, there is a Depends On tab, where the necessary relationships should be configured. The following relationships should be set up:
- A resource that corresponds to features should require the license class (use "Dependence Kind" = Requires).
- A resource that corresponds to an additional license class should require the parent license class (use "Dependence Kind" = Requires).
- Resources that correspond to features within one feature group must conflict with each other (use "Dependence Kind" = Conflicts). This means that only one resource can be chosen from one feature group.
After this, the license and its features can be added to a desired service plan for selling. Use the Configure Licenses/Features button on the Resource Rates tab of the service plan settings.

Note: Make sure the new license class is available for your KA account (address your AM/sales representative with this question in the subject). Otherwise, this license class will be missing within the KA plugin "License Classes" tab and it will be unavailable for reselling.

1.2 New Feature Group

A feature group designates a mutually exclusive grouping of similar features. This means only one feature from a group can be installed.

Feature grouping also imposes additional restrictions on the features upgrade. Namely, one feature may be upgraded to another feature of the same group (target feature) only if the sort number of this feature is equal to or less than the sort number of the target feature. This is needed to represent the relationship between features like the following ones:

10 Plesk domains may be upgraded to 30/100/300/unlimited domains
1 Language Pack may be upgraded to 2/3/4 Language Packs

Notes:

Sort Number of a feature may be seen in the Business Automation Control Panel at External Systems Director > License Manager > License Classes > select a License Class > switch to the Features tab > select a Feature.
Corresponding resources for features from one group should conflict with each other (see step 12 of the "New License Class" subsection).
It is unlikely a new feature group will be required. A set of predefined feature groups covers most use cases.

Addition of a new feature group requires an XMLRPC call of the Business Automation API method; refer to Appendix B for details.

1.3 New Feature

Refer to steps 6 - 12 of the "New License Class" subsection for instructions on how to add a new feature.

Note: Make sure the new feature is available for your KA account (address your AM/sales representative with this question in the subject). Otherwise, this feature will be missing within the KA plugin "Features" tab and it will be unavailable for reselling.

1.4 New Upgrade Option

To configure a new upgrade option for two license classes/features, consider the following steps:

Check KA documentation for the so-called "upgrade plan" (a conversion rule that allows a key's product version upgrade). Make sure the desired upgrade plan exists. Note and save the text code of the upgrade plan; you will need to specify it in the XMLRPC call to Business Automation API to add the upgrade option to Business Automation and make it accessible from Business Automation UI.
Configure the possible upgrade between two resources that correspond to the desired license classes/features. Go to Product Director > Resource Manager > Resources. For each resource, there are Upgrade From and Upgrade To tabs where the necessary relationships should be entered. Consider the Plesk 9.0 for Virtuozzo resource as an example. Remember the resource IDs involved.
Manually add the upgrade option to Business Automation by means of an XMLRPC call of the Business Automation API method; refer to Appendix C for details.

2. Troubleshooting

2.1 Order Failure

The starting point for order failure investigation is an order provisioning items review: Go to Operation Director > Sales Manager > Customers Orders, select the failed order, and go to the Provisioning Items tab. Select the failed provisioning item related to the license/feature and review the Comment field. Typically, the comment contains enough information about the reason for the failure and points to the required troubleshooting steps.

The comment messages requiring an additional explanation are as follows:

Could not create License into Subscription. This message indicates a negative or incorrect response was received from KA. Check the exact message after the colon to find the root cause. Note: Before Business Automation 5.1.20, an incorrect response (e.g., when a request is timed out) was not properly diagnosed and there was no message after the colon. Some of the most confusing root causes include the following ones:
- conflicting feature set means there was an attempt to provision a license with an unsupported feature(s). For example, an attempt to provision Plesk 10 Plus for Unix/Linux along with the feature Plesk Reloaded(TM) Power Pack Light will fail with such an error.
- Invalid Key configuration means there was an attempt to provision a license without the necessary feature(s). For example, an attempt to provision Plesk 10 for Unix/Linux for Virtuozzo containers without any feature from the Domain Limit group will fail with such an error.
- Could not find appropriate Upgrade Plan or Can not find available key type upgrade for Provisioning Item means the KA_Upgrade table in the Business Automation database does not contain a row describing an upgrade option in the active state (refer to the New Upgrade Option subsection). For example, an attempt to upgrade Plesk 10 for Unix/Linux for Virtuozzo containers to Plesk 10 Plus for Unix/Linux for Virtuozzo containers will fail with such an error.
- Unknown base keytype in some cases indicates an incorrect billing type of a license class; check with KA documentation that you have correctly specified a Lease or Purchase billing type.
HTTP request error.... This message indicates communication problems between Business Automation and KA or incorrect account credentials. Verify the following things:
- Business Automation Management Node can connect to Key Administrator using the host and port provided in the KA plugin settings.
- The login name and password in the KA plugin settings are correct.

Note: If an order provisioning fails right after the new license offering is configured, it is quite possible the problem is in incorrect/missing configuration of resources and their dependencies. Refer to steps 10 - 12 of the "New License Class" subsection for more information.

2.2 Problems with License Synchronization

When a non-synchronized license is spotted, select this license at External Systems Director > License Management > Licenses and click the Sync License button. You will get an error message describing the reason for the discrepancy. In most cases, the only way to resolve the discrepancy is to perform manual investigations in the Business Automation database and logs, and to create a support request with the error message in the subject.

Immediate Support Team attention is not required if the message contains the statement Different Additional License in Business Automation and in KA. This can point to the fact that KA has issued some additional licenses that are not compatible with Business Automation. Check that the version of Business Automation is 5.1.13 or newer, since this incompatibility issue is fixed starting from the mentioned version. If Business Automation 5.1.13 or a newer version already is installed, then address the issue to Support.

2.3 License Class/Feature Is Missing within KA Plugin Tabs

Problem: A new license class/feature was configured in accordance with steps listed under 1.1 or 1.2, respectively; however, one cannot find them within KA plugin tabs ("License Classes"/"Features" tabs) and thus cannot resell them.

Cause: The respective license class/feature is not available for your KA account.

Resolution: Address your AM/sales representative to enable the desired license class/feature for your KA account and sync the KA plugin after that.

Additional information: A list of available license classes/features is returned in response to call of the partner10.getAvailableKeyTypesAndFeatures method. This information can be found in the KAGATE.log on the Business Automation Management Node.

3. Known Issues and Limitations

As follows is the list of known problems:

KA can issue unsolicited additional licenses for some of the license classes. If Business Automation is 5.1.13 or a newer version, these unsolicited add-ons are being downloaded from KA but remain uninstalled. Only the vendor or end-customer can download them from the Business Automation Control Panel.
Before attempting to assign a license to a subscription, make sure that for every feature/additional license and license itself, there is a properly configured resource within the subscription. If some of the resources are missing, check that they are added to the service plan the subscription is based on, and synchronize the subscription with the service plan.
When un-assigning a license of a "Lease" type from a subscription, make sure the Software Upgrade Service (SUS) resource is present among the resources of the subscription. If the corresponding SUS resource is missing, it must be included in the service plan the subscription is based on, and the subscription must be synchronized with the service plan.
In rare cases of high load, some of the requests to KA may fail. In this case, the Comment field of the corresponding provisioning item will contain the error message Could not create License into Subscription with either an empty reason or with the reason Failed to read XML-RPC request: Read timed out (after a colon). If such a problem occurs, try to resubmit the failed order for provisioning.
Do not configure a service plan with several license classes until the corresponding resources of these license classes are set to a mutually conflicting state.
Do not configure resource rates for license classes/features via the Add New Resource Rate button. Use only the Configure Licenses/Features button.
Downgrading of licenses is not supported at the moment. The only workaround is cancelling the license and issuing its downgraded analog.
Avoid any manual changes of licenses directly on the KA side, since this most likely will lead to inconsistencies between Business Automation and KA.

Appendix A. API Methods for Additional License Classes Management

Two API methods are used for additional classes management:

KA_AddonAdd - Method used to insert new additional license class into database
KA_AddonMoveToArc - Method used to remove existing additional license class from database

Note: The methods are invoked via the XMLRPC interface. Refer to Business Automation Public API Reference for details on how to call Business Automation API methods.

Example of XML request used to invoke the KA_AddonAdd method:

<?xml version="1.0" encoding="UTF-8" ?>
<methodCall>
  <methodName>Execute</methodName>
  <params>
    <param>
      <value>
        <struct>
          <member>
            <name>Server</name>
            <value>KAGATE</value>
          </member>
          <member>
            <name>Method</name>
            <value>KA_AddonAdd</value>
          </member>
          <member>
            <name>Params</name>
            <value>
              <array>
                <data>
                  <value><string>ACME_LICENSE_CLASS</string></value>
                  <value><string>ACME_LICENSE_CLASS_ADDON</string></value>
                </data>
              </array>
            </value>
          </member>
        </struct>
      </value>
    </param>
  </params>
</methodCall>

This call will add a license class designated by the KA API keytype ACME_LICENSE_CLASS_ADDON to the license class designated by the KA API keytype ACME_LICENSE_CLASS.

Example of an XML request used to invoke the KA_AddonMoveToArc method:

<?xml version="1.0" encoding="UTF-8" ?>
<methodCall>
  <methodName>Execute</methodName>
  <params>
    <param>
      <value>
        <struct>
          <member>
            <name>Server</name>
            <value>KAGATE</value>
          </member>
          <member>
            <name>Method</name>
            <value>KA_AddonMoveToArc</value>
          </member>
          <member>
            <name>Params</name>
            <value>
              <array>
                <data>
                  <value><string>ACME_LICENSE_CLASS</string></value>
                  <value><string>ACME_LICENSE_CLASS_ADDON</string></value>
                </data>
              </array>
            </value>
          </member>
        </struct>
      </value>
    </param>
  </params>
</methodCall>

This call will remove an additional license class designated by the KA API keytype ACME_LICENSE_CLASS_ADDON from the license class designated by the KA API keytype ACME_LICENSE_CLASS.

Appendix B. API Methods for Feature Groups Management

Two API methods are used for feature groups management:

KA_FeatureGroupAdd - Method used to insert new feature group into database
KA_FeatureGroupMoveToArc - Method used to remove existing feature group from database

Note: Methods are invoked via the XMLRPC interface. Refer to the Business Automation Public API Reference for details on how to call Business Automation API methods.

Example of XML request used to invoke the KA_FeatureGroupAdd method:

<?xml version="1.0" encoding="UTF-8" ?>
<methodCall>
  <methodName>Execute</methodName>
  <params>
    <param>
      <value>
        <struct>
          <member>
            <name>Server</name>
            <value>KAGATE</value>
          </member>
          <member>
            <name>Method</name>
            <value>KA_FeatureGroupAdd</value>
          </member>
          <member>
            <name>Params</name>
            <value>
              <array>
                <data>
                  <value><string>ACME_FEATURE_GROUP</string></value>
                  <value><string>Custom feature group</string></value>
                  <value><i4>1000</i4></value>
                  <value><i4>1</i4></value>
                </data>
              </array>
            </value>
          </member>
        </struct>
      </value>
    </param>
  </params>
</methodCall>

This call will add a new feature group with the identifier ACME_FEATURE_GROUP, where

Custom feature group - Human-readable feature group's description
1000 - Feature group's sort number
1 - Indicator that this feature group is mandatory; for an optional feature group, 0 must be supplied

Example of XML request used to invoke the KA_FeatureGroupMoveToArc method:

<?xml version="1.0" encoding="UTF-8" ?>
<methodCall>
  <methodName>Execute</methodName>
  <params>
    <param>
      <value>
        <struct>
          <member>
            <name>Server</name>
            <value>KAGATE</value>
          </member>
          <member>
            <name>Method</name>
            <value>KA_FeatureGroupMoveToArc</value>
          </member>
          <member>
            <name>Params</name>
            <value>
              <array>
                <data>
                  <value><string>ACME_FEATURE_GROUP</string></value>
                </data>
              </array>
            </value>
          </member>
        </struct>
      </value>
    </param>
  </params>
</methodCall>

This call will remove a feature group with the identifier ACME_FEATURE_GROUP from the database.

Note: There must be no features included in the feature group before its removal. Otherwise, the call to KA_FeatureGroupMoveToArc method will fail.

Appendix C. API Methods for Upgrade Options Management

Two API methods are used for additional class management:

KA_UpgradeAdd - Method used to insert new license class/feature upgrade option into database
KA_UpgradeMoveToArc - Method used to remove existing license class/feature upgrade option from database

Note: Methods are invoked via the XMLRPC interface. Refer to the Business Automation Public API Reference for details on how to call Business Automation API methods.

Example of XML request used to invoke the KA_UpgradeAdd method:

<?xml version="1.0" encoding="UTF-8" ?>
<methodCall>
  <methodName>Execute</methodName>
  <params>
    <param>
      <value>
        <struct>
          <member>
            <name>Server</name>
            <value>KAGATE</value>
          </member>
          <member>
            <name>Method</name>
            <value>KA_UpgradeAdd</value>
          </member>
          <member>
            <name>Params</name>
            <value>
              <array>
                <data>
                  <value><string>ACME_FROM</string></value>
                  <value><string>ACME_TO</string></value>
                  <value><string>ACME_FROM_TO_ACME_TO</string></value>
                  <value><string>Custom upgrade</string></value>
                  <value><i4>1</i4></value>
                  <value><i4>1</i4></value>
                </data>
              </array>
            </value>
          </member>
        </struct>
      </value>
    </param>
  </params>
</methodCall>

This call will add a new upgrade option into the Business Automation database with the following attributes (in the order of appearance in the Params section):

ACME_FROM - KA API keytype of the license class/feature you will upgrade from
ACME_TO - KA API keytype of the license class/feature you will upgrade to
ACME_FROM_TO_ACME_TO - Upgrade plan identified; refer to the KA Partner API Reference and Developer's Guide for the correct one
Custom upgrade - Human-readable upgrade plan description
1 - operation type - "1" means upgrade operation, "2" means downgrade operation
1 - Indicates whether upgrade is enabled (1) or not (0)

Example of XML used to invoke the KA_UpgradeMoveToArc method:

<?xml version="1.0" encoding="UTF-8" ?>
<methodCall>
  <methodName>Execute</methodName>
  <params>
    <param>
      <value>
        <struct>
          <member>
            <name>Server</name>
            <value>KAGATE</value>
          </member>
          <member>
            <name>Method</name>
            <value>KA_UpgradeMoveToArc</value>
          </member>
          <member>
            <name>Params</name>
            <value>
              <array>
                <data>
                  <value><string>ACME_FROM</string></value>
                  <value><string>ACME_TO</string></value>
                </data>
              </array>
            </value>
          </member>
        </struct>
      </value>
    </param>
  </params>
</methodCall>

This call will remove the upgrade option from ACME_FROM to the ACME_TO license class/feature KA API keytype.