Earlier versions of AppClarity do not contain the same entitlement functionality as AppClarity 5.0. In previous versions, users could create and manage licenses which provided similar functionality and allowed AppClarity to calculate compliance. The older licenses are not automatically imported into AppClarity 5.0 during an upgrade. The existing licenses are not changed and remain in the system and can be migrated at any point after the upgrade. License migration is a manual process that needs to be performed post-upgrade to using a stored procedure which ships with AppClarity 5.0. 

The APSP_MigrateLicenses stored procedure is found in the Entitlement schema after the database have been upgraded to via the AppClarity installer. It takes a single parameter:

The migration script does not remove any license data, the old license tables will still exist (but may be removed in a later release) and they are no longer used in AppClarity 5.0. The license table will be updated to include a new ulic_migration_state column which is used by the stored procedure to flag licenses have been migrated. If the migration script is run multiple times the ulic_migration_state column is used to skip any previously migrated licenses. If any license fails to migrate, it will contain an error code.

When you upgrade, the Entitlement.Entitlement and Entitlement.Entity tables are empty. Before the script can be run you must create an entity. The simplest way to create an entity is to manually create an entitlement in the AppClarity Console – it ensures the entity is valid and it refers to an existing AppClarity user. You can delete this entitlement after you have created it.

To create an entity in the AppClarity Console:

1. Click the Configuration icon .
2. On the Configuration screen, click Users.
3. Ensure the the current user has a valid name, login and email address. An email address is mandatory in AppClarity 5.0 (it was optional in previous versions).
4. Click the Entitlements icon .
5. In the Entitlements Library screen, click Create Entitlement .
6. When you create the first entitlement, ensure that the Entitlement Type is set to License.
7. in the Product panel, select an Vendor and Product from the respective drop-down lists and check the Valid for all version box. For Vendor, ensure that it is an existing vendor to prevent AppClarity create a site defined entry.
8. In the Quantity and Metrics panel, complete the fields for Quantity, Metric Type and Metric Name.
9. Click Publish to Library.

The newly created entitlement is now visible in your Entitlements library. You can now delete this entitlement. When you created the entitlement, the Entitlement.Entity table was updated with a row with details for the user who created the entitlement. This entity can be used by the APSP_MigrateLicenses stored procedure.

You will need the entity id for the user before you run the migration script. To do this, run this query:

SELECT * FROM [Entitlement].[Entity] WHERE entity_logon = '[logon name]'

 where [logon name] is the users logon name. The script can be run as follows:

DECLARE @return_value int
EXEC @return_value = [Entitlement].[APSP_MigrateLicenses] @entityId = 1

SELECT 'Return Value' = @return_value

In our example, the entityId is 1; your entity id may be different. The output for our example is illustrated below:

When the script is run, ulic_migration_state column in the licenses table is updated to reflect the migration state of the license. It is set to one of the following:

• NULL – after the database upgrade to AppClarity 5.0, the ulic_migration_state column is created and set to NULL. This value indicates no migration has been attempted on the license.
• 1 – the license has successfully been migrated. Licenses in this state are skipped in future migration runs.
• 2 – the license could not be migrated due to invalid dates. Licenses are migrated as either Perpetual License or Subscription Licenseentitlements. A perpetual license has an optional start date but no end date. A subscription license has both a start and end date. If you get this error the possible causes are:
  • The license has an end date but no start date. This cannot be mapped to either a perpetual or subscription license.
  • The licenses end date occurs before the start date. This shouldn't occur as this would have been prevented by the console.

  Correct the dates and re-run the migration.

Some useful queries

The following queries can be used to get the total number of licenses and entitlements in the database.

• To retrieve the total number of licenses, run:
  select count(*) as TotalLicenses from dbo.License
• To retrieve the total number of active licenses excluding deleted licenses, run:
  select count(*) as TotalActiveLicenses from dbo.License where ulic_state = 0
• To retrieve the total licenses migrated, run:
  select count(*) as TotalLicensesMigrated from dbo.License where ulic_migration_state = 1
• To retrieve the total number of entitlements, run:
  select count(*) as TotalEntitlements from Entitlement.Entitlement
• To retrieve the total number of active entitlements excluding deleted entitlements, run:
  select count(*) as TotalActiveEntitlements from Entitlement.Entitlement where entitlement_is_inactive = 0

Using the same database that contain the 865 entitlements above, running the above queries both before and after the migration returned the following results:

• A total of 865 licenses were migrated
• Of these, 653 of these are active and can be seen in the AppClarity 5.0 Console
• The other licenses were migrated to entitlements, but there were marked as inactive (deleted). The inactive entitlements are not listed in the AppClarity Console and do not count towards compliance.