Configure Usage Records for Invoices

When Usage Records are enabled for an invoice, instellix automatically collects the usages associated with the invoice according to the selected configuration type and creates a CSV file according to the configured Usage Record schema. The generated file is attached to the invoice document and can be accessed together with the invoice.

A Usage Record configuration defines:

• the configuration type (Metered, Rated, or Combined),
• the file name of the generated CSV file,
• which Usage fields are included,
• the CSV column headers,
• and which custom Usage Properties are included.

The configuration is created centrally and can then be assigned to one or multiple Document Provisioning configurations.

1. Create a Usage Record configuration

Navigate to: Configuration → Provisioning → Usage Records

The overview lists the existing Usage Record configurations, including their identifiers, configuration types, file names, and configured columns.

Select Add to create a new configuration.

Enter an Ident for the configuration. The Ident uniquely identifies the configuration and is used when assigning it to Document Provisioning.

Select the configuration type

Select the configuration type. This setting defines which usage kinds are included in the generated Usage Record:

Choose the type that matches the usage model of the invoices for which this configuration will be used. For example, use Rated if invoices only contain Rated Usages, or Combined if a single CSV should contain both Metered and Rated Usages.

Configure the file name

Enter the file name schema that should be used for generated Usage Record files. The file name can contain both static text and dynamic variables. Dynamic variables are replaced with the corresponding value when the individual file is generated.

For example:usage_record_{DocumentIdent}

This allows each generated Usage Record to be associated with its corresponding invoice while still following a consistent naming convention.

The configured file name is used for newly generated Usage Records. Changing it later does not rename Usage Records that have already been generated.

2. Select the CSV columns

In the Columns section, select the usage information that should be included in the CSV. Each selected field becomes a column in the generated Usage Record.

Available information can include fields such as:

• Start Date
• End Date
• Contract Ident
• Document Ident
• Performance Location Country
• Quantity
• Quantity Type
• Product Ident
• Article Number
• Product Name
• Option Name

The exact data available in the generated record depends on the underlying usage and invoice data. You can select individual columns or use Add all to include all available standard columns.

At least one column must be configured. A Usage Record configuration without any columns cannot be saved.

Customize column headers

For every selected field, you can define the CSV column header. By default, the field name can be used as the header. Change the value if the exported CSV should use a different column name.

For example, the quantity field could be exported with a header such as: Consumed Units

This allows the structure and terminology of the CSV to be adapted to downstream processes or customer requirements. The generated CSV contains the configured columns and uses the configured column headers.

3. Add Usage Properties

In addition to the standard fields, you can include custom Properties stored on the usages.

In the Property columns section, select Add and specify:

• Property ident -- the Ident of the Property stored on the
  Metered Usage.
• CSV column header -- the name of the corresponding column in the
  generated CSV.

Each configured Property is exported as a separate column.

If a configured Property exists on a usage, its value is written to the corresponding CSV field. If the Property is not present on an individual usage, the cell remains empty and generation of the Usage Record continues.

Special characters contained in Property values are handled as part of CSV generation so that values containing delimiters, quotation marks, line breaks, or special characters do not invalidate the CSV.

Select Save when the configuration is complete.

4. Assign the Usage Record configuration to invoices

Creating a Usage Record configuration does not automatically enable Usage Records for invoices.

The configuration must be assigned through Document Provisioning.

Navigate to: Configuration → Provisioning → Document Provisioning

Open the Document Provisioning configuration that applies to the invoices for which Usage Records should be generated and select Edit.

Under Document Provision, locate the Usage Records field.

You can either select:

• Do not create a usage record
• CSV to generate Usage Records

When CSV is selected, assign one of the available Usage Record configurations. Depending on your Document Provisioning setup, you can:

• assign one Usage Record configuration (of type Metered, Rated, or Combined) for a single CSV attachment

Select the configuration created in the previous steps and save the Document Provisioning configuration.

From this point onward, invoices matching this Document Provisioning configuration use the selected Usage Record configuration. The same central Usage Record configuration can also be reused by multiple Document Provisioning configurations.

If Do not create a usage record is selected, the invoice is created normally without an additional Usage Record attachment.

5. Generated Usage Record

When an invoice matching the Document Provisioning configuration is created, instellix automatically generates the configured Usage Record. The CSV contains one row for each usage associated with the Invoice that matches the configuration type:

• Metered — one row per Metered Usage
• Rated — one row per Rated Usage
• Combined — one row per Metered Usage and one row per Rated Usage

Depending on the configuration, the file can contain information such as the invoice and contract identifiers, usage period, quantity and quantity type, product information, location information, and custom usage Properties.

The generated CSV is stored as an attachment of the corresponding invoice document. It is displayed with the document in the Webportal and can be downloaded from there.

Invoices without matching usages

A configured Usage Record does not require an invoice to contain usages of the selected type.

If Usage Record generation is enabled but no matching usages are associated with the invoice, a valid CSV containing only the configured header is generated. This is not treated as an error.

Example

A Usage Record configuration of type Combined could use the following file name:

usage_record_{DocumentIdent}

and include these columns:

Source field CSV column header

---

startDate Usage Start
endDate Usage End
contractIdent Contract
documentIdent Invoice
productIdent Product
quantity Quantity
quantityType Unit

Additional customer-specific information can be added using Property columns.

For an invoice containing multiple Metered and Rated Usages, the resulting CSV contains the configured header and one data row for each usage belonging to that invoice.

Changing an existing configuration

Usage Record configurations can be reused and edited.

Changes affect Usage Records generated after the configuration has been updated. Existing CSV files remain unchanged. This also applies when the configured file name is changed.

This makes it possible to evolve the exported Usage Record format without modifying files that were already generated for previous invoices.