Contents

Entitlement import files

Summary

Definitions of each type of record that may be imported into an AppClarity entitlement repository.

The following tables show each category, sub-category, and the record types that can be imported. The 11 sub-categories are visible as tabs in the home page of an entitlement repository.

The Manual upload feature available in AppClarity 6.1 no longer exists in AppClarity 7.x . When importing entitlements you must use the Entitlement.tsv connector.

Entitlement information is managed using various fields, in 11 sub-categories (one of which is not used), which map directly to columns in a import file. TSV and CSV files are both supported, but the documentation here refers to TSV.

Import files must have the following:

  • All columns must have column headings
  • Column headings must not have spaces
  • The Version column must be named Version and not Version/Number as it did in some older export files

Please note the following:

  • When using a simple editor like notepad ensure you leave the tab/comma delimiters between headings
  • Any column heading with an incorrect name is ignored; this allows additional columns to be used as notes or extra information
  • Columns can be in any order; it may help you to standardize on the column order listed below
  • In the tables below, mandatory means the column and value are expected. If a mandatory column or value is omitted you will see caveats reported
  • Ensure date formats are correct. When editing a file using Excel, the date columns should have their number format set as Text instead of Date , otherwise you will see integers instead of dates when saved as a TSV/CSV file. Text ensures that whatever you type will remain unchanged.

Use the ISO 8601 date format for date fields: yyyy/mm/dd or yyyy-mm-dd

When exporting dates from other SQL servers, the format may be different due to the region settings of the source server, for example mm-dd-yyyy for English (US). To ensure dates are imported correctly, changing the data format to ISO 8601 is recommended, or you should ensure the SQL Server instance hosting the AppClarity database uses the same or equivalent region settings. In most cases SQL Server will intelligently convert dates, but you should review your imports to be sure.

You should test your system with a few test entitlements before you do any bulk imports.

On this page:

Base Entitlement (1)

ColumnMandatoryDefault if not specifiedDatatypeNotes
EntitlementIdNoAuto-generated GUIDString

Identity id of this entitlement. This is auto-generated as a GUID if this entitlement was created in the user-interface.

ParentEntitlementIdNo
String

Identity id of the parent entitlement linked to this entitlement. This is auto-generated as a GUID if this entitlement was created in the user-interface, and it is linked to a parent Entitlement.

If ParentEntitlementId is specified, then you must have a matching EntitlementId earlier in the import file, or you already know the EntitlementId has been imported previously.

In AppClarity 7.1 an entitlement can only have one parent or none. When exporting from AppClarity 5.2, if any entitlement has multiple parents then only one will be used, and the ParentEntitlementId of the others will exported into the comments column, and appear in the comments field when imported into AppClarity 7.1.

Finding the EntitlementId from the database or UI is not supported currently.

EntitlementTypeYes
String

Valid values are:

  • License
  • Maintenance
  • Agreement

Once imported it can not be changed.

IdentifierNo
String

Appears in pages as Custom identifier. Enter any alphanumeric text that will help identify the entitlement.

LicenseTypeNo

Perpetual for License and Maintenance.

NA for Agreement.

String

Valid values are:

  • Perpetual
  • Subscription

Agreement is always 'NA'

StartDateNo

Calulated as EndDate - DurationInMonths for Agreements and Subscription.

If neither is set then today’s date.

If DurationInMonths is not set, then 12 is the default.

Today's date for Perpetual.

Date

When the entitlement starts applying.

EndDateYes/no depending on other fields.

Calculated as StartDate +  DurationInMonths for Agreements and Subscription.

If DurationInMonths is not set then 12 is the default.

It is set only for Agreements and Subscription.

Date

This is last date of entitlement.

DurationInMonthsNo

Calculated as EndDate - StartDate. If either of these are missing then 12 is the default.

It is set only for Agreements and Subscription.

Decimal

For how long the entitlement is applicable after start date.

For example, if start date if Jan 14, 2016 and Durationmonths is 24 months then end date would be Jan 14, 2018 

ProductSKUNo
String

Product SKU

IsEntitlementProductNoFALSEBoolean

Is the entitlement entered an SKU based from Catalog

Vendor

Yes if ProductSKU is not present for License and Maintenance.

Yes for Agreement.


String

Vendor. The name of product Vendor.

Title

Yes if ProductSKU is not present for License and Maintenance.

No for Agreement.


String

For license and maintenance pages, this is Product title; the name of the product.

For agreement page, this is Name.

VersionNo
String

For license and maintenance pages, this is Version; the version of product. Version can be given in any format depending on chosen Version Type.

For agreement page, this is Number.

VersionTypeNoAllVersionsString
  • AllVersions
  • DotFormat
  • Colloquial
  • NA - Agreements are always 'NA'
Edition

Yes if ProductSKU is not present for License and Maintenance.

No for Agreement.


String

Edition. The name of product edition. 

IsEditionBasedNoFALSEBoolean

If edition is available then True otherwise False.

IsRenewalNoFALSEBoolean

Entitlement types that needs to be renewed (has an end date).

IsUpgradeNoFALSEBoolean

This specifies rights, if upgrade rights are allowed.

IsQuantityUnlimitedNoFALSEBoolean

If the number of licenses purchased is unlimited then True otherwise False. If True then Quantity is ignored.

Quantity

Yes if IsQuantityUnlimited is FALSE for License and Maintenance.

No for Agreement.


Integer

Number of licenses purchased.

MetricTypeNoDeviceString

Valid values are:

  • Device
  • Processor
  • Core
  • PVU
  • Other

Agreement is always 'NA'

OtherMetricNo
String

Used only if Metric Type is 'Other'

IsVersionUpgradeRightNoTRUEBoolean

Whether the entitlement is applicable on the later versions of chosen product version. Only applicable, and automatically enabled, if Vendor is Microsoft Corporation, and SA is selected.

IsVersionUpgradeRightPersistentNoTRUEBoolean

Version upgrade persists after maintenance is expired. If this right is False, then the license rights resets back to original version at the time of purchase of perpetual license when maintenance expires. Only applicable, and automatically enabled, Vendor is Microsoft Corporation, and SA is selected.

IsVersionDowngradeRightNoFALSEBoolean

Whether the entitlement is applicable on the previous versions of chosen product version. By default these rights are active

IsVersionDowngradeRightPersistentNoFALSEBoolean

Version downgrade persists after maintenance is expired. If this right is False, then the license rights resets back to original version at the time of purchase of perpetual license when maintenance expires.

IsEditionDowngradeRightNoFALSEBoolean

Whether the entitlement is applicable on the previous editions of chosen product edition.

IsEditionDowngradeRightPersistentNoFALSEBoolean

Edition downgrade persists after maintenance is expired. If this right is False, then the license rights resets back to original edition at the time of purchase of perpetual license when maintenance expires.

IsMultiInstanceRightNoFALSEBoolean

Whether the same license is applicable on multiple installations.

IsSoftwareAssuranceNoFALSEBoolean

SA is applicable only for Microsoft Corporation products. On selecting SA Version upgrade rights are automatically set to True.

SecondaryUseCountRightNoFALSEBoolean/Int

This refers to the use right to allow users to use same product on their second device free of cost (example one office desktop and one home laptop) with their single device-based license

CurrencyNoUSD3 chars

ISO 4217 currency code. The code must match one of the codes already existing in the database. Please contact 1E if you need to add additional codes to the database.

CodeSymbol
USD$
EUR€
GBP£
JPY¥
CADC$
AUDA$
CNY¥
CHFFr.
SGDS$
HKDHK$
ZARR$
UnitCostNo0Decimal

Cost of licence per unit

TotalCostYes for Agreement.

For License and Maintenance, the value is automatically calculated if Unit Cost Type is OnceOff, and values are povided in Quantity and Unit Cost.

Decimal

For Agreement, this value must be supplied. It appears as License Cost in the Agreement page.

For License and Maintenance, do not provide a value. It will be automatically calculated if Unit Cost Type is OnceOff, and values are povided in Quantity and Unit Cost.

UnitCostTypeNoOnceOffString

Valid values are:

  • OnceOff
  • Monthly
  • Quarterly
  • Yearly
CommentsNo
String

Used for any comments you want to import.

If an AppClarity 5.2 entitlement includes any of the following product details, these will be exported in the comments field:

  • Colloquial SubVersion
  • Registration Key
  • Persistent Id
  • Entitlement Key
  • Channel Type
  • Product Family
  • UNSPSC Code

ParentEntitlementId - In AppClarity 7.0 an entitlement can only have one parent or none. When exporting from AppClarity 5.2, if any entitlement has multiple parents then only one will be used in the ParentEntitlementId column, and the ParentEntitlementId of the others will appear here in the Comments column.

MasterAllocationPercentageNo
Integer

Not supported. This is to handle complex agreement scenarios; currently not supported. There are Agreements where total amount is fixed and can be distributed among various entitlements in that agreement. This defines the percentage of that amount allocated to this entitlement.

FOSSDetail (3)

ColumnMandatoryDefaultDatatypeNotes
FossDetail.FossDetailIdNo
String

Do not use for imports.

FossDetail.IsFossNo
Boolean

This value is true only if the granted rights fulfil the requirements of the definition of free software maintained by the Free Software Foundation (FSF)

FossDetail.CopyLeftNo
String

This value provides information on whether derivative works (which are always allowed for open source software) are themselves required to be open source software. There are three allowed values:

  • strong - that all kinds of derivative works are required to be open source software themselves
  • no - means that for all kinds of derivative works, it is allowed to distribute the derivative work as proprietary software
  • weak - the intermediate value means that there are some restrictions and the details are to be checked in the license
FossDetail.TrademarkRestrictionsNo
String

FOSS trademark restrictions

Internal Order (4)

ColumnMandatoryDefaultDatatypeNotes
InternalOrder.InternalOrderIdNo
String

Do not use for imports.

InternalOrder.NumberNo
String

Free text but recommendation is integer

InternalOrder.LineItemNumberNo
String

Free text but recommendation is integer

InternalOrder.DateNo
Date

Date

Licensor Detail (5)

ColumnMandatoryDefaultDatatypeNotes
LicensorDetail.LicensorDetailIdNoNULLString

Do not use for imports.

LicensorDetail.NameNoNULLString

The name of the licensor, could be the vendor or a VAR

LicensorDetail.NumberNoNULLString

This is intended as a reference to a licensor source other than an invoice, e.g. to an on-line portal of license purchases. Free text but recommendation is integer

LicensorDetail.DateNoNULLDate

Date

Miscellaneous Details (6)

ColumnMandatoryDefaultDatatypeNotes
MiscellaneousDetail.MiscellaneousDetailIdNoNULLString

Do not use for imports.

MiscellaneousDetail.ManagementGroupNoNULLString

The entitlement can be associated with the specified Management Group.

The management group must already exist.

In the current version of AppClarity, associations with management groups do not affect compliance calculations. Calculations apply to all devices in the repository, irrespective of Management Groups. 

MiscellaneousDetail.BusinessUnitNoNULLString

May be covered by Management Group, but may not - in the VA, this is the Pillar the software is associated with. (Kapil Makhija)

MiscellaneousDetail.SponsorNoNULLString

Name of the person who manages the budget associated with an agreement (likely used only on agreements, but could be extended to individual entitlements)

Audit Detail (7)

ColumnMandatoryDefaultDatatypeNotes
AuditDetail.AuditDetailIdNoNULLString

Do not use for imports.

AuditDetail.AuditorNoNULLString

Names of organisations entitled to perform the audit including, if appropriate, the licensor organisation and third party organisations according to what was agreed in the contract.

AuditDetail.FrequencyNoNULLString

Definition of the highest agreed frequency of the audit expressed in months

AuditDetail.ToolNoNULLString

Name of the tool(s) which are approved for use in the audit.

AuditDetail.NoticePeriodNoNULLInteger

Notice period expressed in months

AuditDetail.ScopeNoNULLString

Defines what part of the software customer organisation is allowed to be audited.

AuditDetail.ClauseNoNULLString

Provides additional information on what could trigger the audit.

Contract (8)

ColumnMandatoryDefaultDatatypeNotes
Contract.ContractIdNoNULLString

Identity id of the contract. This is auto-generated as a GUID if the entitlement was created in the user-interface.

Do not use for imports.

Contract.DataNoNULLString

Do not use for imports.

Contract.NameNoNULLString

Name of the contract.

Contract.NumberNoNULLInteger

Contract number

Contract.StartDateYesNULLDate

When the contracts starts applying

Contract.LinkNoNULLString

A link to a referenced contract (not uploaded)

Contract.ResourceNoNULLString

Name of the person who manages the agreement  (likely used only on agreements, but could be extended to individual entitlements)

Contract.TechnicalResourceNoNULLString

Name of the person who knows the technical details behind licensing, or product information for an agreement (likely only used on agreements, but could be extended to individual entitlements)

Contract.FileName
NULL
If there is any attachment - then what? (currently not supported through tsv file) 

Direct Supplier (9)

ColumnMandatoryDefaultDatatypeNotes
DirectSupplier.DirectSupplierIdNoNULLString

Do not use for imports.

DirectSupplier.NumberNoNULLString

Free text but recommendation is integer

DirectSupplier.LineItemNumberNoNULLInteger

LineItemNumber

DirectSupplier.DateNoNULLDate

Date

Invoice Detail (10)

ColumnMandatoryDefaultDatatypeNotes
InvoiceDetail.InvoiceDetailIdNoNULLString

Do not use for imports.

InvoiceDetail.NumberNoNULLString

Free text but recommendation is integer

InvoiceDetail.LineItemNumberNoNULLInteger

Line item number

InvoiceDetail.DateNoNULLDate

Date

Purchase Order Detail (11)

ColumnMandatoryDefaultDatatypeNotes
PurchaseOrderDetail.PurchaseOrderDetailIdNoNULLString

Do not use for imports.

PurchaseOrderDetail.NumberNoNULLString

Free text but recommendation is integer

PurchaseOrderDetail.LineItemNumberNoNULLInteger

LineItemNumber

PurchaseOrderDetail.DateNoNULLDate

Date