Structure of a Business Mapping

The Structure of a Business Mapping

The JSON payload that is used to define a Business Mapping is called a Mapping Rule. A basic Mapping Rule looks like this

{
  "name": "Continent",
  "defaultValue": "Unallocated",
  "statements": [
    {
      "matchExpression": "DIMENSION['region'] STARTS_WITH 'us-'",
      "valueExpression": "'United States'"
    },
    {
      "matchExpression": "DIMENSION['region'] STARTS_WITH 'eu-'",
      "valueExpression": "'Europe'"
    }
  ]
}

Every Mapping Rule is defined with a meaningful name (as this is the label the resultant Business Dimension or Business Metric will take throughout Cloudability reports), a sequence of statements for testing different match conditions, and a defaultValue which only applied when none of the statements could be successfully matched.

The Expression Language

We have created a DSL especially so that you can to define the matchExpression and valueExpression fields in your Mapping Rules elegantly, and the syntax is pretty simple. If you’ve ever written code in Java, JavaScript, Ruby, Python, or any other popular programming language, the concepts of our expression language should be pretty familiar. Even if you haven't it's very straightforward to create these expressions and Cloudability will provide plenty of examples. For detailed information on the expression language checkout this page.

The Business Dimension

{
    "name": "ATUM - Towers",,
    "kind": "BUSINESS_DIMENSION",
    "defaultValue": "Unmapped",
    "statements": [{
            "matchExpression": "(DIMENSION['service_name'] CONTAINS 'Network' || DIMENSION['enhanced_service_name'] CONTAINS 'Network')",
            "valueExpression": "'Network'"
        },
        {
            "matchExpression": "DIMENSION['enhanced_service_name'] == 'AWS EBS' || DIMENSION['enhanced_service_name'] == 'Azure Storage' || DIMENSION['enhanced_service_name'] == 'GCP Cloud Storage' || DIMENSION['enhanced_service_name'] == 'AWS S3'",
            "valueExpression": "'Storage'"
        },
        {
            "matchExpression": "(DIMENSION['enhanced_service_name'] == 'AWS EC2' || DIMENSION['enhanced_service_name'] == 'Azure Compute' || DIMENSION['enhanced_service_name'] == 'AWS ECS' || DIMENSION['enhanced_service_name'] == 'AWS Lambda')",
            "valueExpression": "'Compute'"
        }
    ]
}

Name

The name field indicates the unique identifier for all the Business Dimension values generated by this rule. Just like Vendor Tags are key/value pairs with unique names for each key, Business Dimensions are also key/value pairs, and this field defines the keys in those key/value pairs.

Statements

Every Mapping Rule also defines an ordered sequence of statements.

Each statement in a Mapping Rule contains two different expressions, written using our custom expression language (described later in this document): the matchExpression is like a test, which will be evaluated as either true or false for every data-point, and the valueExpression evaluates to a string of text representing the value for the resultant Business Dimension.

At runtime, we evaluate each of these statements, sequentially, and when we find a matchExpression that actually matches, we evaluate the corresponding valueExpression expression to generate a text value for the resultant Business Dimension.

Comparing our expression language to other programming languages you might have used before, it’s helpful to think of the matchExpression as being like an if statement and the valueExpression as being like a then statement.

In particular, we only calculate the result value of the valueExpression for statements with a matching matchExpression.

Default Values

If we step through the complete list of statements for a line item and don't find a matching matchExpression, then we use the defaultValue defined at the top-level of the rule as the text-value of this item. Some good examples of default values could be 'Unallocated', 'Non Compliant', 'Not Applicable' etc. i.e chose something that is specific to the Business Dimension you are creating.

Type of Business Mapping

The kind attribute represents the declaration that we are defining a Business Dimension versus a Business Metric for our Business Mapping construct

The Business Metric

{
    "name": "Cost (Storage Backup 10% Surcharge)",
    "kind": "BUSINESS_METRIC",
    "numberFormat": "currency",
    "preMatchExpression": "(DIMENSION['vendor'] == 'amazon' || DIMENSION['vendor'] == 'azure') && DIMENSION['usage_family'] == 'storage'",
    "defaultValueExpression": "METRIC['unblended_cost']",
    "statements": [{
            "matchExpression": "DIMENSION['invoice_date'] == '2019-09-01' && DIMENSION['transaction_type'] == 'usage' && (DIMENSION['usage_type'] CONTAINS 'backup' || DIMENSION['usage_type'] CONTAINS 'snapshot')",
            "valueExpression": "METRIC['unblended_cost'] * 1.10"
        },
        {
            "matchExpression": "DIMENSION['invoice_date'] == '2019-10-01' && DIMENSION['transaction_type'] == 'usage' && (DIMENSION['usage_type'] CONTAINS 'backup' || DIMENSION['usage_type'] CONTAINS 'snapshot')",
            "valueExpression": "METRIC['unblended_cost'] * 1.10"
        },
        {
            "matchExpression": "DIMENSION['invoice_date'] == '2019-11-01' && DIMENSION['transaction_type'] == 'usage' && (DIMENSION['usage_type'] CONTAINS 'backup' || DIMENSION['usage_type'] CONTAINS 'snapshot')",
            "valueExpression": "METRIC['unblended_cost'] * 1.10"
        }
    ]
}

Name

The name field indicates the unique identifier for the Business Metric values generated by the Business Mapping statement rules you have defined. Every Business Metric created requires a name; ideally it should reflect the business context that you are trying to share and be descriptive such that users will quickly make sense of it. The name provided for the custom metric will will appear in Cloudability reports and dashboards.

Statements

Every Business Metric also defines an ordered sequence of Business Mapping statements.

The statements defined for a Business Metric contain two different expressions, written using our custom expression language. the matchExpression is like a test, which will be evaluated as either "True" or "False" for every data-point. and the valueExpression is arithemetically evaluated to a decimal value. At runtime, we evaluate each of these statements sequentially, and when we have a matchExpression that results in "match", the corresponding valueExpression expression is then evaluated to generate a decimal value for the custom metric. You can think of the matchExpression as being like an "if statement" and the valueExpression as being like a "then statement".

Number Format

In addition to a name, the custom metric you create will be evaluated to a number and surfaced as currency or a regular decimal number. The use case driving this custom metric will help you decide on the appropriate number format. For example: if your usecase is to provide a surcharge for management fees, then the custom metric format will be currency.

Default Values

The defaultValueExpression is defined at the top-level and represents the value for this Business Metric if, after stepping through the complete list of Business Mapping statements for a Business Metric, we don't find any data points that match the defined matchExpression(s). The defaultValueExpression should be consistent with the type of Business Metric being created.

Pre-Match Expression

The expression declared in the preMatchExpression section is evaluated first; then expressions are evaludated in the statements section. If no matches are found for the expression defined within the preMatchExpression, then we immediately jump to the defaultValueExpression, skipping the statements section. The preMatchExpression represents a centralized/global expression which is evaluated before all other defined expressions contained within statements section; It can be left empty (without a defined expression).

Type of Business Mapping

The kind attribute represents the declaration that we are defining a Business Metric versus a Business Dimension for our Business Mapping construct