Transformation Templates

As explained in the Transformations Overview, CloudBilling’s output is a set of pricing rule results. A transformation can be used to generate text or PDF output based on this set of rule results. This is achieved through the use of a transformation template. On this page we describe how the templates work and the features available to you.

View Engine

The Razor view engine is used to generate the output. This means the templates have to be in the Razor format. They can output any plain text format, but if the PDF output type is specified on the transformation the corresponding template should output HTML. Since PDF output is achieved by applying an HTML to PDF conversion.

Header - Model

Here we describe the model that defines an invoice object, it’s properties and methods that can be used in the Razor template. The base of the model is an ExportInvoice object and it has the following properties:

Line Items - Model

The actual rule results are represented in the InvoiceItems list of ExportInvoiceItems. Each of these is a thin wrapper around an InvoiceRuleResult, which contains the actual pricing rule result and has the following properties:

Using the Models

In the actual template, we have to begin by importing the namespace for the model described above. This is achieved by starting the template with the following statement:

@using Kolonel.Domain.Model

From this point on the template can use the model described above to generate output. When applying a transformation to an invoice, that invoice is represented by a single ExportInvoice object, containing a list of invoiceItems. The template is then applied to that specific instance of the model, thus generating output. Specifically, in the template we can now say something like:

Model.CustomerName

to print out the customer name.

Grouped Templates

When adding a template, you can indicate whether or not it is a grouped template. If this is the case, the model is slightly different. Instead of a single ExportInvoice object (representing a single invoice), the model contains a list of ExportInvoice objects, each representing an invoice that the template is applied to. We import the same namespace at the start of the template, only now to use it, we generally iterate over the ExportInvoice objects and generate output for each one sequentially, like this:

foreach(var inv in Model.ExportInvoices){
    inv.CustomerName
}

to print out the customer name for each invoice.

Metadata

One of the more complex aspects of transformation templates and rule application is metadata, so we cover it separately. Customer metadata is fairly straightforward. Any metadata specified on a customer will be available as metadata in the template on the ExportInvoice object. Purchase metadata is slightly more complex, since purchases are not part of the set of information available to the template. The template does have access to all of the pricing rule results though. In general (and by default), CloudBilling tries to maintain as much metadata on results as possible. Sometimes this will be all metadata of a purchase, e.g., a price rule will just copy over all metadata from the purchase onto the result. In other cases this might be more challenging, consider 3 different purchases for a bicycle. Each has a string metadata attribute ‘color’, but each has a different value for this attribute, say ‘red’, ‘white’, and ‘blue’ respectively. Then a price rule will generate 3 separate results, each with the metadata intact and corresponding to the respective purchase that’s underlying to the result. However, if we want to get a subtotal of the amount for bicycles, we get a single SUM results with these 3 price results as underlying, there is no clear way to fill the ‘color’ metadata on the result of the SUM, since there are 3 different input values. In this case, we can’t retain the metadata.

The general rule of thumb is, unless it’s a 1-to-1 relationship, we will lose metadata. We do try to keep as much as possible (if all source items have the same value for a piece of metadata, it will persist). Furthermore, we have a concept called grouping on, for instance, sums. Where we can group on a piece of metadata. Let’s go back to the bicycle example and pretend instead of 3 different colors, we have 2 ‘red’ bikes and a ‘blue’ bike. Now if we group on the ‘color’ metadata key in the SUM rule, it will generate 2 results instead of 1. One of the results will contain the total for the red bikes, whereas the other will contain the total for the blue bike. We can of course SUM again afterwards to also get a ‘grand total’ for all 3 bikes.

Now that we’ve explained how the metadata persists through the mechanism of rule application, what can we actually do with it in the template? Through the properties and helper methods, we can split the set of results on a piece of metadata. Which in turn allows us to split output for, e.g., a specification page based on metadata present on the results. We will demonstrate the use of metadata to achieve something like this in one of the examples in the next section.

Examples

The template engine is extremely flexible, but can also be complex, especially to start with. Therefore we will provide some examples here to demonstrate the concepts.

Examples will be added in the near future (End of May)