This article assumes a knowledge of services, their rates and related concepts as documented in Services in Exivity
The service statement is used to create or modify a single service definition during the execution of a Transcript task. The service definition is associated with the data in an existing DSET, and the global database is updated if and when the Transcript task successfully completes.
It is recommended not to use the service statement for creating services, rather to use services.
service{ param1 = value [... paramN = value] }
Example:
Parameters may be specified in any order. The '=' between parameters and their values is optional and may be omitted, but if present it must be surrounded by white-space
The service statement is used to create a new service definition. Once created, a service definition automatically becomes available to the reporting engine.
The service statement creates a new service using the following parameters:
The key parameter must be distinct from that in any other service unless it is used to identify an existing service definition to be overwritten with new values. By default, an attempt to create a service with a key that is a duplicate to an existing service in the global database will result in a warning in the logfile and no further action will be taken.
If the key matches that of a service that has been defined previously in the task file then one of two things can happen depending on the value of the current execution mode:
If the mode is set to strict then an error is logged and the task will fail
If the mode is set to permissive then a warning is logged and the newest service definition is ignored
To override the default protection against overwriting existing service definitions in the global database, the statement option services = overwrite should be invoked prior to the service statement.
The value of the key parameter may be up to 127 characters in length. Longer names will be truncated (and as a result may no longer be unique).
The description parameter is freely definable and does not have to be unique. When a report is generated, the description of a service will be used on that report so care should be taken to make the description meaningful.
By default, if description is not specified in a service definition then a copy of the key will be used as the description.
The value of the description parameter may be up to 255 characters in length. Longer descriptions will be truncated.
Either category or group may be used. The two terms are interchangeable in this context.
The category parameter is used to logically associate a service with other services. All services sharing the same category will be grouped together on reports. Any number of different categories may exist and if the category specified does not exist then it will be automatically created.
If no category is specified then the service will be placed into a category called Default.
The value of the category parameter may be up to 63 characters in length. Longer values will be truncated.
In order to calculate a price for a service, the number of units of that service that were consumed needs to be known. The value of the usage_col parameter specifies the column in the usage data which contains this figure.
The usage_col argument is also used to derive the DSET associated with the service as follows:
If the value of usage_col is a fully qualified column name then the service will be associated with the DSET identified by that name
If the value of usage_col is not fully qualified then the service will be associated with the default DSET
If the column specified by the usage_col argument is determined not to exist using the above checks, then one of two things can happen depending on the value of the current execution mode:
If the mode is set to strict then an error is logged and the task will fail
If the mode is set to permissive then a warning is logged and the service definition is ignored
The value of the usage_col parameter may be up to 255 characters in length. Longer values will be truncated.
Services may be charged in different ways. For example some services will invoke a charge whenever they are used whereas others are charged by a time interval, such as per month.
The value of the interval parameter determines how the service should be charged as per the following table:
Specifies whether or not to apply proration when calculating the charge for a monthly service.
Currently, only monthly services can be prorated, based on the number of days in the month the service was used.
The unit_label is the label used for units of consumption on reports. For example storage-related services may be measured in Gb or Tb, Virtual Machines may be measured in Instances and software usage may be measured in licenses.
The specified unit_label value may be up to 63 characters in length. Longer values will be truncated.
If the unit_label parameter is not specified then a default value of Units will be used.
The account_id parameter is intended for internal use only and should not be used
The optional account_id references an entry in the account table in the global database. If specified, the service will be created with a rate revision specific to the account id.
The default rate for the service (which applies to all combinations of report column values not explicitly associated with their own rate) can be defined in any of the following ways:
By omitting the account_id parameter altogether
By specifying an account_id of 0
By specifying an account_id of *
The rate parameter determines the cost per unit of consumption to use when calculating the charge. A rate of 0.0 may be used if there is no charge associated with the service.
This may be used in conjunction with a fixed_price and one of cogs or fixed_cogs.
Either or both of rate or fixed_price may be specified, but at least one of them is required.
The fixed_price is a charge applied to the service per charge interval regardless of the units of consumption.
This may be used in conjunction with a rate and one of cogs or fixed_cogs
Either or both of rate or fixed_price may be specified, but at least one of them is required.
The optional COGS charge is the price to the provider of the service. Usually, COGS-related charges are not included on reports special permissions are required to see the COGS charges.
For services with a defined cogs value it is possible to generate Profit and Loss reports, the profit/loss being the total charge calculated from the rate and/or fixed_rate values minus the price calculated from the cogs or fixed_cogs values.
The optional fixed_cogs value is a fixed price to be factored into COGS-related calculations regardless of the number of units consumed in the charging interval.
The optional min_commit parameter specifies a minimum number of units of consumption to include when calculating the charge associated with a service. In cases where the actual consumption is greater than the min_commit value this will have no effect, but where the actual consumption is less than the minimum commit the price will be calculated as if the min_commit units had been consumed.
If specified as peak then the charge for monthly service created will be calculated based on the day with the highest charge in the month.
If specified as average then the charge for monthly service created will be calculated as the average unit price (for days that have usage only) multiplied by the average quantity (days with no usage will be treated as if they had a quantity of 0).
If specified as last_day then the charge for monthly service created will be calculated based on the last day of the month.
If specified as day_xxx (where xxx is a number in 1-28 range) then the charge for monthly service created will be calculated based on the specified day of the month.
Once all parameters have been evaluated by the service statement the resulting service definition is added to a cache in memory. This cache is committed to the global database at the successful conclusion of the Transcript task (or discarded in the case of error).
Once a service definition has been added to the cache, no subsequent service definitions with the same key may be added to the cache. In the event of conflict the first definition written to the cache is perserved and the attempt to add a duplicate will result in a warning or an error depending on the value of the current execution mode as described in the key section above.
As described in Services in Exivity a service may have multiple rate revisions associated with it. The service statement can only create a single rate revision per service per execution of a Transcript task.
A rate revision consists of the rate, fixed_rate, cogs, fixed_cogs and effective_date parameters. Each revision must have a different effective_date which indicates the date from which that service revision is to be used. A rate definition remains in force for all dates on or after the effective_date, or until such time as a rate revision with a later effective_date is defined (at which point that revision comes into effect).
To create multiple revisions, Transcript must be run multiple times using a service statement that has the same key and uses the same rate, fixed_rate, cogs and fixed_cogs values but has a different effective_date each time. For each of the effective_date parameters a new rate revision will be created for the service.
At the successful conclusion of a Transcript task the global database is updated from the memory cache.
Parameter
Required
Notes
key
Yes
A unique identifier for the service
description
No
The name of the service as it will appear on a report
category or group
No
Services are grouped by category on a report
usage_col
Yes
The name of the column containing the number of units consumed
interval
No
The charging interval for the service
model
No
Whether the service charges should be prorated or not
unit_label
No
The label for the units of consumption; eg: GB for storage
account_id
No
Which account to associate with the rate revision
rate
No
The price per unit of consumption
fixed_price
No
The fixed price which will be charged regardless of non-zero usage in the charge interval
cogs
No
The COGS price per unit of consumption
fixed_cogs
No
The fixed COGS price which will be charged regardless of non-zero usage in the charge interval
min_commit
No
The minimum number of units of consumption that will be charged per interval
effective_date
No
The date from which the rate revision should be applied
charge_model
No
A specific charge model (may be peak , average, last_day or day_xxx, where xxx is number in range 1-28)
Interval value
Meaning
individually
Every unit of consumption is charged individually. For example if a network-related service charges by the GB, then for every GB seen in the usage the charge is applied regardless of how many GB are used or over how long a period of time the consumption took place.
hourly
The charge is applied once per hour regardless of the number of times within the hour the service was consumed
daily
As for hourly but applied per-day
monthly
As for daily but applied per calendar month
Model value
Meaning
unprorated
No proration is to be applied
prorated
Proration will be applied