Configuration via cpl24.json

Besides the technical inventory there is addtional information necessary to achieve a complete reporting. E. g. which customers do i have, which machine belongs to which customer, customer bring in licenses, manual exlcusions, etc.

The following documentation provides the information how to deal with the cpl24.json file.

Format and structure of cpl24.json

The file is written in JSON format. Please see json.org for further information.

For editing the file we recommend a editor with JSON syntax highlighting, e. g. Visual Studio Code or Notepad++ with JSON Plugin.

The document is splitted in two main sections

• Global Configuration
• Local Configuration

Global Configuration

The global configuration affects the local machine and all other machines. Within the global section you define your customer data. If you want so, it is a simple list which contains all your customers. The customer data is needed to map machines and users to customers.

We recommend that you define the global configuration only on one device. It is a good practice to programmatically generate your customer data out of your master data (e. g. ERP System).

For example you can you can use a PowerShell script which converts you customer data to JSON with the ConvertTo-JSON function.

Further you can define so called BaseOUs for each customer.

A BaseOU is the distinguished name of an Active Directory organizational unit. With this configuration you achieve that all users placed in this OU and below are mapped to this customer.

Additionally you are able to define so called GroupMatches.

A GroupMatch is nothing other than a mapping from an Active Directory group to a SPLA SKU. If a user is placed within such a group the license with this SKU is booked onto the user. If the user is removed from the group, then the license gets unbooked.

See the FAQ section on why a GroupMatch is a good practice and also why in most cases of user based licences this is the only way to get a correct reporting.

Local Configuration

Within the local configuration you can define all the things for the local/current device where inventory is running on.

This table shows on a high level the sub sections and what effect it has, for details see the example JSON:

Example JSON

This is a complete example cpl24.json. Please be aware that JSON doesn’t allow comments but we used // to add comments for better understanding. Also have a look at the square brackets, this allows multiple objects to be defined, e. g. CustomerData.

{
    // The global configuration affects this and all other inventoried machines
    "Global" : {
        "CustomerData": [               // List of your customers and their base OUs resp. group matches
            {
                "Id": "12345",          // Customer id (a new customer is created, if not found)
                "Name": "Example Ltd.", // optional, set override the customer's name identified by id

                "BaseOUs": [            // List of base ous to detect it's users and maps them to the given customer id
                    "DC=example,DC=com"
                ],

                "GroupMatch": [         // List of AD groups to map a group membership to an article
                    {
                        "ObjectGUID": "151ec906-3a4a-4494-89a3-94075a3e293f",   // The AD's group GUID
                        "ItemId": "F08-00025"                                   // Article id to book, when a user is member of that group
                    }
                ]
            }
        ]
    },

    // The local configuration affects only this local device
    "Local" : {
        "InventoryData": {
            "TargetUrl": "example.com:5001/p/api/VeryLongCrypticRandomId", // replaces the --TargetUrl start parameter //TODO Noch ohne Funktion
            "InfrastructureLicensed": false,        // automatically book a license when applicable e.g. DataCenter
            "ReadActiveDirectory": false            // If the machine is an domaincontroller, AD data is only inventoried when the AD has the PDC role. Set this value to true to enforce the AD inventory even the machine has not the PDC role.
        },

        "UserConfiguration": {
            "ExcludedGroups": [
                {
                    "AdGroupName": "DomainAdmins",                              // The AD's group name
                    "Description": "Administrative accounts should be ignored"  // Legitimation of the exclude
                },
                {
                    "AdGroupName": "ExampleLtd-ServiceAccounts",                // The AD's group name
                    "Description": "Service accounts should be excluded"
                }
            ],

            "excludedAccounts": [
                {
                    "RegularExpression": "^[Ss][Vv][Cc][_].+$",                     //Exclude all user beginning with SVC_
                    "Description": "All service users begin with SVC_ and are therefore excluded"
                },
                {
                    "ObjectGUID": "c5050441-a7b2-49d6-987c-0187ff81206d",       // Exclude a specific object GUID (AD user guid)
                    "Description": "Exclude explicit admin account"
                },
                {
                    "UserName": "Administrator",                                // Exclude users by name
                    "Description": "Exclude all administrator accounts"
                }
            ]
        },

        "MachineData": {

            "ExcludeThisMachine": true,         // Exclude this machine from all licensing
            "ExcludeThisMachineReason": "This machine is only for testing, not for production use",         // Legitimation when excludeThisMachine is true
            "CustomerId": "12345",              // Map this machine to this customer (assure that the customer is registered in your global section)

            "ExcludedItemIds": [
                {
                    "ItemId": "9EM-00562",
                    "Description": "License included by software XY. License agreement is available in the path X:\\contract\\...\\xy.pdf as evidence."     // Legitimizing text that proves the exclusion in audit cases
                }
            ],

            "IncludedItemIds": [
                {
                    "ItemId": "9EM-00562",
                    "Description": "Manually booked datacenter core license, as automatic detection is not possible.",
                    "Quantity": 32,
                    "CalclulateQuantity": false
                }
            ]
        },

        "ManualLicenses": [
            {
                "ItemId": "F08-00025",      // article id to be booked
                "CustomerId": "12345",      // The customers id. Assure that the customer is declared in your global section
                "Quantity": 3,              // Factor of how many times the article is booked. Note the denomination and minimum purchase quantity.
                "ValidFrom": "2021-01-01",  // start date
                "ValidUntil": "2021-12-31", // optional end date
                "Description": "Manually reported licenses from external system"    // Reason for booking this article
            },
            {
                "ItemId": "6WC-00002",
                "CustomerId": "18729",
                "Quantity": -10,            // If you already booked license, you could lower the detected amount by negative factors
                "ValidFrom": "2021-01-01",
                "Description": "Already purchased provided license"                 // Provide a legimitation text/link/... when an auditor checks theese entries 
            }
        ]
    }
}