Dictionary Virtual Tags (Beta)

Beta: Dictionary Virtual Tags are currently in Beta. To enable this feature for your account, contact your customer success manager or email [email protected].

Overview

Virtual Tags let you allocate and classify cloud costs using rule-based conditions. Dictionary Virtual Tags take a different approach: instead of writing rules, you supply an external mapping file that maps source values directly to destination values in a one-to-one relationship.

This is designed for situations where the number of distinct values is too large to manage through manual rules — such as mapping thousands of application IDs to application names, or mapping email addresses to squads or cost centers. Finout reads the mapping file from your S3 bucket daily, so any updates you make to the file are automatically reflected without any configuration changes on your end.

When to use Dictionary Virtual Tags:

• You need to map a high-cardinality dimension (hundreds or thousands of values) to a human-readable label.

• Your mapping data already lives in a system of record that can export a CSV file.

• Your mapping changes periodically and you want Finout to stay in sync automatically.

• You need time-bounded mapping — where the same source value maps to a different destination depending on the date.

Note: Each dictionary Virtual Tag is a strict one-to-one mapping. A single source value maps to exactly one destination value. If you need to map values from multiple dimensions (e.g., AWS Account ID and GCP Project ID), first combine them into a single Custom Virtual Tag, then use that Virtual Tag as the source dimension for your dictionary.

How It Works

You provide a CSV mapping file stored in an S3 bucket. Finout reads the file daily through a Read Only Amazon S3 Bucket Endpoint and derives a Virtual Tag from the mappings defined in the file. The tag is then available for filtering and grouping across MegaBill and all reporting surfaces just like any other Virtual Tag.

If you upload an updated version of the file to the same S3 prefix, Finout automatically picks up the latest file on the next daily sync.

Prerequisites

Before setting up a Dictionary Virtual Tag, make sure you have:

• An S3 bucket in your AWS account where you can store the mapping file

• Permission to create an IAM role and inline policy in that AWS account

• A mapping file prepared in the required format detailed below

Setup

Step 1 — Create the Mapping File

Prepare a CSV file that defines how each source value maps to a destination value.

File Format

• Only CSV files are supported. Finout will not process files in any other format.

• The file must use the following column headers exactly as shown. Headers are case-sensitive.

Standard mapping

Use this when each source value always maps to the same destination:

Source	Destination
value-a	Label A
value-b	Label B

Time-bounded mapping

Use this when a source value should map to different destinations depending on the date:

Source	Destination	From	To
value-a	Label A	2024-01-01	2024-06-30
value-a	Label B	2024-07-01

Column details:

• Source — the value as it appears in your MegaBill dimension. Must be an exact match; partial or fuzzy values will appear as Untagged.

• Destination — the label Finout assigns when the source value matches.

• From — the start date for this mapping row (inclusive). Required when using time-bounded mapping.

• To — the end date for this mapping row (inclusive). Leave empty if the mapping has no upper limit and should apply indefinitely from the From date.

Date Format

All common date formats are supported (for example: 2024-01-01, 01/01/2024). Use a consistent format throughout the file and include the format you used when contacting support in Step 4 — Finout configures the mapping based on the format you specify.

File Rules

• Each dictionary Virtual Tag reads from one file in one S3 prefix. If you need multiple dictionaries for the same account (e.g., email-to-squad and email-to-cost-center), create a separate file and a separate prefix for each.

• The file size limit is 500,000 rows.

• Overlapping date ranges for the same source value are not permitted and will cause validation to fail.

• If time-bounded mapping is enabled, every row must have a From date. Rows with a missing From date will fail validation.

Step 2 — Upload the Mapping File to S3

Upload your CSV file to an S3 bucket in your AWS account. Keep the following in mind:

• Use a dedicated prefix for each mapping file. For example: s3://your-bucket/dictionary/email-to-squad/. The prefix should contain only the single mapping file for this dictionary. Finout selects the most recent file in the prefix on each daily run.

• To update the mapping, upload a new version of the file to the same prefix. Finout will automatically pick it up on the next daily sync — no configuration changes needed.

Step 3 — Create an S3 Endpoint in Finout

Finout connects to your S3 bucket through a Read Only Amazon S3 Bucket Endpoint. Follow the Amazon S3 Bucket Endpoint guide to create one, making sure to select Read Only under Bucket Access.

Give the endpoint a clear, descriptive name — you will reference it by name when contacting support in Step 4.

Step 4 — Contact Finout Support to Complete Setup

Once the mapping file is in place and the S3 endpoint is created, contact your customer success manager or email [email protected] with the following information:

Detail	Description
S3 Endpoint Name	The name you gave the endpoint in Step 3
File Name	The exact name of your CSV file (e.g., dict_email_to_squad.csv)
Date Format	The date format used in your From / To columns (e.g., YYYY-MM-DD) — only required if using time-bounded mapping
Time-Bounded Mapping	Whether your file includes From / To columns (Yes or No)

Finout will configure the Dictionary Virtual Tag on your account and notify you when it is ready.

Result

Once configured, the Dictionary Virtual Tag appears in your Virtual Tags list and is immediately available for filtering and grouping across MegaBill and all reporting surfaces. Values from the Destination column become the tag values. Any source value not present in the mapping file appears as Untagged.

FAQs

How often does Finout sync the mapping file?

Finout processes the file once per day. In the prefix includes a single file, Finout will reingest based on modification date. In case of multiple files in the predix, a single file will be ingested, based on the modiciation date as well.

What happens if a source value in my cost data is not in the mapping file?

It appears as Untagged in Finout.

Can I have multiple dictionary Virtual Tags for the same account?

Yes. Each dictionary Virtual Tag maps to one file in one S3 prefix. Create a separate file, prefix, and dictionary Virtual Tag configuration for each mapping you need.

Can I map a source value to multiple different destinations?

No. Each dictionary Virtual Tag has a single Source column and a single Destination column — one mapping per file. If you need the same source dimension to produce multiple different destination tags (for example, AppSpace ID → Team and AppSpace ID → Cost Center), create a separate mapping file and a separate dictionary Virtual Tag for each. Each file should live in its own dedicated S3 prefix:

your-bucket/dictionary/appspace-to-team/mapping.csv
your-bucket/dictionary/appspace-to-costcenter/mapping.csv

Can I use a Virtual Tag as the source dimension for a dictionary?

Yes. Finout supports Virtual Tags as source values in a mapping file, in addition to native MegaBill dimensions. This is useful when you need to combine multiple dimensions — for example, merging AWS Account ID and GCP Project ID into a single Virtual Tag and then building a dictionary on top of it.

What happens if my mapping file fails validation?

The previous version of the mapping file remains active, and your Virtual Tag continues to serve values from the last successful file. Finout will notify you of any validation errors.

What do I do if a row has a To date but no From date?

Rows with a To date but no From date will fail validation. When using time-bounded mapping, every row must include a From date. The To date is optional — leave it empty if the mapping should apply indefinitely.