Configure Metered Usage Records for Invoices

When Metered Usage Records are enabled for an invoice, instellix automatically collects the Metered Usages associated with the invoice 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 file name of the generated CSV file,
• which Metered 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, 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.

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 Metered 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 Metered 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 Metered 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 Metered Usage, its value is written to the corresponding CSV field. If the Property is not present on an individual Metered 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
• one of the available Usage Record configurations.

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 Metered Usage associated with the Invoice.

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 Metered Usages

A configured Usage Record does not require an invoice to contain Metered Usages.

If Usage Record generation is enabled but no Metered 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 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 Usages, the resulting CSV contains the configured header and one data row for each Metered 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.