Imports and processing
This section explains the import and processing of usage data. It also discusses the different methods for pricing of usage data.
Usage data imports
The first step is to create a new import for the corresponding supplier and import the usage data file. To do this, navigate to the Usage Data Suppliers page and then open the related Usage Data Imports using the action of the same name. A new import is created via the New Import action.
In addition to the data generated by the system, an (individual) description per import can be entered in the Description field. Furthermore, the current processing status can be read using the fields Processing Step, Processing Status and - in case of error - Reason (Preview).
The progress of processing can be viewed via this page. Invoicing takes place after the usage data has been processed.
Structure of the page Usage Data Imports
The page has the following action areas:
- New
- The New Import action is used to prepare a new import.
- Process
- Import file
Opens a file dialog to add the import file to the selected import. - Process Data
Processes the imported usage data, but without creating the invoices. The individual steps Create Imported Lines, Process Imported Lines, Create Usage Data Billing and Process Usage Data Billing are automatically run one after the other. - Create Customer Invoices
Creates a Sales Invoice for all contract elements belonging to the selected import. This creates a separate invoice document for each Customer Contract. The generated contract invoices are posted directly if the Post documents indicator is set to YES in the dialog. - Create Vendor Invoices
Creates a Purchase Invoice for all contract components belonging to the selected import. This creates a separate invoice document for each Vendor Contract. Since a Vendor Invoice No. is required for posting Purchase Invoices, the option to post the generated documents directly is not available here.
- Import file
- Manual Processing (via Related)
As an alternative to automatic processing of usage data via Process Data, the individual steps can also be called up separately.- Create Imported Lines
Generates the usage data as raw data based on the import file. The Data Exchange Definition is used, which is stored at the Usage Data Supplier (in the Settings page). The generated Imported Lines can be opened via the lookup in the No. of Imported Lines field. - Process Imported Lines
When processing the Imported Lines, the system attempts to create a link between the usage data and the Service Commitments or Service Objects. If errors occur during processing, the erroneous data can be opened using the lookup in the No. of Imported Line Errors field. After correcting the causes of the errors, the processing step can be executed again. - Create Usage Data Billing
Generates the data needed for actual billing based on the Imported Lines. Since usage data is often vendor or supplier data, this step - depending on the configuration - generates the data needed for customer billing. - Process Usage Data Billing
In this step, the pricing for the usage data takes place. The respective method for pricing and the period to be billed are taken into account. If errors occur during processing, the incorrect data can be opened via the lookup in the No. of Usage Data Billing Errors field. After correcting the causes of the errors, the processing step can be executed again. - Remove Usage Data Lines & Billing
This action can be used to delete the usage data generated on the basis of the import file and then generate it again. This is useful, for example, if errors occur during processing that can be solved by changing the Data Exchange Definition used.
- Create Imported Lines
- Usage Data Billing (via Related)
- Customer Contracts
This action opens an overview of the Customer Contracts belonging to the import. - Customer Contract Invoices
This action opens an overview of the Customer Contract Invoices created for the import, but not yet posted. - Posted Customer Contract Invoices
This action opens an overview of the Customer Contract Invoices created and posted for the import. - Vendor Contracts
This action opens an overview of the Vendor Contracts associated with the import. - Vendor Contract Invoices
This action opens an overview of the Vendor Contract Invoices created for the import, but not yet posted. - Posted Vendor Contract Invoices
This action opens an overview of the Vendor Contract Invoices created and posted for the import.
- Customer Contracts
Imported Lines
The Usage Data Generic Import page displays the raw data generated from the import file(s). This usually includes supplier information about the customers, the subscriptions and the respective billing period. The fields Unit Cost and Cost Amount offer the possibility to import unit prices as well as total prices. If the total price is available in the Cost Amount field, the Unit Cost is calculated based on the quantity. If the total price is not available, it will be calculated based on the quantity and the Unit Cost.
The page can be opened using the lookup in the field No. of Imported Lines. The processing steps are explained in more detail in Process: Import usage data.
Usage Data Billing
This page contains the data that serves as the basis for subsequent billing. Depending on how the Services Commitments are set up, related customer usage data is generated for each Vendor usage data. In addition, customer pricing and the updating of prices in the Service Commitments takes place here in the last processing step. Customer pricing depends on the setting in the field Unit Price from Import at the supplier.
The page can be opened using the lookup in the field No. of Usage Data Billing. The processing steps are explained in more detail in Process: Process usage data.
Import usage data via API
In addition to importing usage data via file, import via API (using an API page) is also available. When the page is called up, a new import number is automatically assigned. This number is then used for each transferred data record and is used to assign the data records to an import.
Authentication (Service-to-Service, S2S) must be performed when calling the API page. For setup, please refer to this part of the Microsoft documentation.
In summary, you need to create an Azure AD application, enter it into Business Central, and assign appropriate access rights (just as you would for users). The page contains further down a nice explanation of the procedure to test the newly set up authentication and web service.
The link for calling the page externally is as follows:
https://api.businesscentral.dynamics.com/v2.0/<tenant_id>/<environment_name>/api/singhammerITConsulting/dyce/v1.0/companies(<company_id>)/usageDataImports?$expand=usageDataGenericImports
- tenant_id = from the customer system
- environment_name = from the customer system
- company_id = from the customer's system
For more details on API pages and their activation, please refer to the Microsoft documentation.
If usage data is imported via API, the Process without Usage Data Blobs field should be set to Yes in the supplier settings.
Methods for pricing
On the purchasing side, i.e. for Usage Data Billing with Partner=Vendor, the prices provided via the supplier are further used, as the supplier usually also provides an invoice for this that matches the usage data. Since with the vendor-side invoicing in the further process a Vendor Contract Invoice is created, this must likewise fit to the usage data and thus also to supplier invoice.
The Customer price calculation, on the other hand, depends mainly on two things:
- the value in the Usage Based Pricing field of the Service Commitments belonging to the usage data and
- the setting of the Unit Price from Import field at the Usage Data Supplier.
If the indicator in the Unit Price from Import field is set at the supplier, the import file must contain this data. In addition, the Data Exchange Definition must take this information into account. In this case, price calculation does not take place because the supplier of the usage data includes the sales prices and this flag overrides price calculation.
If the indicator is not set at the supplier, one of the following methods for customer pricing is used.
Usage Quantity
The price is calculated based on the quantity contained in the usage data. First, the Service Commitments are used to find the Service Object and thus the related item. If necessary, the appropriate price scale is determined via the quantity. The decisive factor here is the contract partner (which is stored in the Sell-to Customer No. field of the Customer Contract), not the invoice recipient. Based on the period to be billed (fields Charge Start Date and Charge End Date), the partial period is calculated to the day (with a corresponding daily price) in the case of a pro-rata billing period.
Fixed Quantity
When processing usage data, the original quantity remains fixed. This means that the customer is always charged the original fixed quantity. There is no adjustment of quantities based on usage data. This pricing thus serves the flat-rate billing of Service Commitments, which, however, only takes place if usage data is actually available.
Unit Cost Surcharge
Here, the imported usage quantity is also disregarded. However, the cost price plus the surcharge specified in the Service Commitments is charged to the customer. This option is often used for consumption-based billing. In this case, all individual prices of the usage data belonging to a subscription are aggregated and then the surcharge is calculated on the total.
Consumed Quantity
This pricing option also leaves the quantity in the Service Object unaffected. This means that - in contrast to the Used Quantity option - non-integer consumption quantities (with decimal places) can also be processed. However, there is no aggregation of all usage data to one single Service Commitment (as with the Unit Cost Surcharge option). It is therefore a combination of the two pricing methods mentioned before. Similarly, the sales price (per unit) is also determined here on a quantity-dependent basis using the related item (via the Service Commitment and the Service Object) and the contract partner (Sell-to Customer No. field) in the Customer Contract.
Pricing for partial periods
In addition to the above methods, any partial periods are also taken into account when determining prices. First of all, the following notes apply:
- Partial periods exist if the time span between Charge Start Date + Dateformula from Billing Base Period of the Service is different from the time span between Charge Start Date and (inclusive) Charge End Date. This can be the case, for example, if there are one or more quantity changes within a billing period or if it is just not a complete billing period.
- Since the months have different numbers of days, the month in which the Charge Start Date (in Usage Data Billing) lies determines which daily price is used as the basis for calculating the partial period (see below).
- Provided that it is a full billing period, it is irrelevant whether the billing period is congruent with a calendar month or overlapping.
Usage data describing a change in quantity within a billing period usually contains several data records, with the periods matching the corresponding quantity in each case.
When calculating prices for partial periods, the system calculates with the respective valid day price. For this purpose, first the number of days of the Calculation Base Period (from the Service Commitments) is determined, in which the Charge Start Date lies. The (billing period) price is then multiplied - taking into account the quantity scale, if applicable - based on the ratio of the two time periods.
For the common billing period of 1 month (Billing Base Period=1M), the daily prices within a calendar month are always identical. Consequently, for two partial periods whose Charge Start Date is in two calendar months with different number of days, the daily price is also different.
If the monthly price is the same, the daily price in a month with 31 days (e.g. January) is lower than in a month with only 28 days (e.g. February). However, this only applies if it is a partial period. The price of full billing periods, however, is always identical.
For a partial period that extends over several months with different numbers of days, the daily price of the respective month always applies. This ensures that for several partial periods within a month, the sum of the daily prices always corresponds to the monthly amount.
Partial periods within a calendar month
| Charge Start Date | Charge End Date | Number of days | Unit price month | Quantity | Price partial period |
|---|---|---|---|---|---|
| 01.05.2022 | 10.05.2022 | 10 | 35 | 2 | 22,58 |
| 11.05.2022 | 31.05.2022 | 21 | 35 | 5 | 118,55 |
Total price for billing period: 141,13
Overlapping partial periods
| Charge Start Date | Charge End Date | Number of days | Unit price month | Quantity | Price partial period |
|---|---|---|---|---|---|
| 11.01.2022 | 02.02.2022 | 23 | 35 | 5 | 138,55 |
| 03.02.2022 | 10.02.2022 | 8 | 35 | 8 | 80 |
Total price for billing period: 218,55
Note: The amount for the first subperiod is made up of the daily rates for 21 days in January (21/31 * 35 * 5 = 118,55) and 2 days in February (2/28 * 35 * 8 = 20,00).
Billing period from usage data
It is quite common but not mandatory that the prices for usage-based Service Commitments are monthly prices. At the same time, there may be differences between the Billing Base Period (from Service Commitments) and the actual billed period (from usage data). To take both into account, both periods are compared when calculating the prices (see Process usage data). If they are not identical, the ratio is used as a factor in price calculation.
Process: Import usage data
- Via the Usage Data Suppliers page, the related Usage Data Imports are opened via the action of the same name.
- A new import is created via the New Import action. The supplier is set automatically.
- The Import file action opens a file dialog with which the import file can be added to the selected import.
- The file will be stored as a BLOB. The details can be viewed via the lookup in the No. of Usage Data Blobs field. Then the usage data is processed.
Process: Process usage data
The processing of usage data can be done in just one step via Process Data. This comprises several individual steps, which are explained in detail here for better understanding.
After importing the reconciliation file, the raw data is generated as individual lines based on the import file via Create Imported Lines. The details can be viewed via the lookup in the Imported Lines field.
2. When processing the Imported Lines (Process Imported Lines), the imported usage data is merged with the Service Commitments and thus Service Objects. Subscriptions are used as a link for this purpose, and DYCE Usage Based Billing uses them to establish the connection. If required, these records can be created automatically (s. Settings on the supplier). Specifically, the usage data contains the ID of the subscription to which it belongs. Each Subscription, in turn, has a reference associated with the Service Commitments (via the Supplier Reference Entry No. field). When the usage data is merged with the Service Commitments, the validity of the Service Commitments is checked, among other things. If it is not yet or no longer valid, a processing error will be shown. In the event of an error, the affected records can be viewed and corrected via the lookup in the No. of Imported Line Errors field.
If there is no connection between a Subscription and a Service Commitment, it can be established via the functionality Connect Subscription with Service Object, provided that the Service Commitment and the Service Object already exist. If this is not the case, they can be created using the Extend Contract functionality and automatically linked in the process.
3. Since usage data is often supplier-side data for which the data required for customer-side billing is (still) missing, customer-side partner data is created for each vendor usage data record when generating the Usage Data Billing (via Create Usage Data Billing) - depending on the configuration (see below) - which is later used for customer-side billing. The details can be viewed via the lookup in the No. of Usage Data Billing field.
The records in Usage Data Billing are vendor neutral, meaning all usage data read in is normalized to this table regardless of the original source.
4. When processing Usage Data Billing (via Process Usage Data Billing), the data in the respective Vendor or Customer Contract lines, in the Service Objects and in the Service Commitments are updated based on the new usage data (quantities and prices). In addition, the sales price is calculated for each data record with Partner=Customer (see methods for pricing). In case of error, the affected records can be viewed via the lookup in the No. of Usage Data Billing Errors field.
This step completes the actual processing of the usage data.
The next step is the invoicing. Ideally, first with the incoming invoice accompanying the usage data of the supplier and then with the further billing in the form of Customer Contract Invoices to the respective customers (although the order is arbitrary).
Vendor and/or customer usage data
In addition to the import of Vendor usage data already described in this section, it is also possible that only Customer usage data is available. This is usually the case when the Service Commitments to be billed are internal services. In such a constellation, both the Service Commitments at the item master data and the Service Commitments at the Service Objects are configured in such a way that there are only Service Commitments with Partner=Customer.
The connection between Subscriptions and Service Commitments is always made via the field Supplier Reference Entry No., whereby a Vendor Service Commitment is always prioritized. However, if there is only one Customer Service Commitment, the connection can also be made via this.
When processing usage data, the assignment is therefore made either via the Vendor Service Commitments or, if this is not available, via the Customer Service Commitments.
If only a Customer Service Commitment exists, only those with Partner=Customer are created when processing the related usage data.