Adding Data to, Publishing, and Managing Lookup Table Revisions - m3ter Documentation

Documentation Index

Fetch the complete documentation index at: /llms.txt

Use this file to discover all available pages before exploring further.

This topic explains how to add string or number values for a Lookup Table Revision data schema and publish and manage Table Revisions. A Revision’s data values only become available for calculations that reference the Lookup Table when the Revision is published:

Data can only be added to a draft Revision.
Only one Revision can be the published Revision for a Lookup Table at any given time.
You cannot change the data values of a published Revision.
If you want to use updated data values for the Lookup Table, you must:
- Create a new draft Revision with the same data schema, add updated values you want to use for the Table, and publish the new Revision.
- Alternatively, you can duplicate the published Revision as a new draft Revision, add updated values you want to use for the Table, and publish the new Revision.
- When you publish a new Revision:
  - The current published Revision is automatically archived
  - Any Lookup functions in your calculations will now use the data values defined for the new published Revision.

In this way, you can manage and deploy Lookup Table Revisions for use cases where you need to quickly and dynamically update the data values used for your calculations. This topic continues the variable discount rate example introduced in the previous topic and goes on to explain how to add data to, publish, and manage Lookup Table Revisions:

Adding and Managing Data for Table Revisions

You can quickly add string and number values to draft Table Revisions. To add data to a Table Revision:

Select Settings>Lookup tables. The Lookup tables page opens.
Select the Name hotlink text of the Lookup Table. The Lookup table details page opens.
Under Revisions, select the Name hotlink text of the draft Revision you want to add data to. The Revision details page opens.
Under Revision data, select Create. The Create page opens.
On Revision data details, enter the required string and number data values for the Revision field schema:

For the current variable discount rate example, we’ve entered two sets of rate and country data field values for the Revision schema we set up in the previous topic.

Select Create revision data. You are returned to the Revision details page and under Revision data the added data values are shown for the Revision fields:

We now have a Table Revision with the data values we want to use for our current discounted rate example added. To make these values available for any Lookup functions used in calculations, we must first publish the Revision - see the following section.

If you want to update the data you’ve added to the Revision before you publish it, under Revision data you can:

Select Edit to edit the Revision data details for all data fields.
Select the Edit button for a single data item to update it:

If you want to delete all the data you’ve added to the Revision:

Under Revision data select Delete. A confirmation dialog appears.
Select to Delete all the Revision’s data.

If you want to delete a single data item:

Select the delete icon for the data item:
A confirmation dialog appears.

Select to Delete the single data item.

Important: Adding data prevents updates to the Revision data field schema! If you add data values to a Revision, you will no longer be able to edit the Revision’s data field schema to add additional fields, delete fields, change field order, or change keyed fields. See the following Managing Table Revisions section.

Publishing Table Revisions

When you’ve added any required data values to a draft Table Revision, you can publish it and make the values available to any Lookup functions used in calculations that reference the Lookup Table. To publish a Table Revision:

Select Settings>Lookup tables. The Lookup tables page opens.
Select the Name hotlink text of the Lookup Table. The Lookup table details page opens.
On the Revisions panel under Actions, select the Publish icon for the DRAFT Revision you want to publish:

The Revisions panel adjusts and shows the Revision’s Status as PUBLISHED:

Alternatively, select the Name hotlink text of the Revision you intend to publish. The Revision details page opens:

On the Revision data panel you can review and check the values of the data fields for the draft Revision before you go ahead and publish it.

On the Revision details panel, select Publish:

A confirmation dialog appears and reminds you that this action will archive the currently published version.

Select Publish to confirm. The Revision details panel adjusts and shows the Revision as PUBLISHED:

Note that:

You cannot update or delete a PUBLISHED Table Revision.
Any Lookup functions used in calculations that reference the Lookup Table will now use the data values on the newly published Revision.
- If you subsequently want to update a Revision to ensure different data values are used by Lookup functions, you must create a new draft Table Revision, populate it with the required data values, and publish the new Revision.
- If you want to use the same data schema for the new Revision, you can simply duplicate the PUBLISHED Revision in draft status, update the data values, and then publish the duplicate to supersede the currently published Revision - see the following section.

We now have a published Revision of the Discount Vol Rates Lookup Table. This will make available to Lookup functions the data values we want to use for our current discounted usage rate example:

The following Worked Example topic explains how to set up a derived field on a Meter with a calculation that uses a Lookup function referencing the Discount Vol Rates Lookup Table. This function will apply the discount rates by country to measured usage. The example goes on to show how to check that Accounts in different countries are billed according to the appropriate discounted usage measures.

Duplicating Table Revisions

In many cases of using Lookup Tables to fulfill dynamic data mapping use cases, you’ll want to use the same data schema as the currently published Table Revision. You can quickly duplicate the currently published Table Revision as a draft, add new data values as required, and then publish the updated draft Revision. To duplicate a Table Revision:

Select Settings>Lookup tables. The Lookup tables page opens.
Select the Name hotlink text of the Lookup Table. The Lookup table details page opens.
Select the Name hotlink text of the Revision you want to duplicate. The Revision details page opens.
On the Revision details panel, select Duplicate:

A confirmation dialog opens:

Select Duplicate to confirm. The Table Revision is duplicated and if you open the Lookup Table details page, the duplicate is now listed on the Revisions panel:

The new duplicate Revision:

Uses the original Revision’s name with “Copy” appended.
Inherits the original Revision’s data schema and any data values.
Is created as a DRAFT Revision.

You can now edit the duplicate Revision, as required.

Archiving Published Revisions

If you have published a Table Revision, created a new draft Revision, and then publish the draft, the existing published Revision is archived automatically. You can also manually archive the Published Revision.

Warning! If you’ve referenced the Lookup Table in a calculation and you archive the published Table Revision, values will not be available for the calculation until you publish another Revision.

To archive the published Table Revision:

Select Settings>Lookup tables. The Lookup tables page opens.
Select the Name hotlink text of the Lookup Table. The Lookup table details page opens.
On the Revisions panel under Actions, select the Archive button for the PUBLISHED Revision:

A confirmation dialog appears:

Select Archive. The Status of the Table Revision now shows as ARCHIVED on the Revisions panel:

Copying Table Revision Data

You can copy a Table Revision’s data to another Revision:

Copy the data from the current Revision to a destination Revision.
Copy the data from a source Revision to the current Revision.

Notes and Warnings:

Check source and destination Revision data schema match! If you attempt to copy data from one Revision to another and their data schema do not match, the copy will fail and you’ll receive an error.
Restrictions when copying Revision data. Some restrictions are imposed when copying Revision data - you cannot:
- Copy data to a PUBLISHED Revision.
- Copy data to or from an ARCHIVED Revision.
- Copy data from a Revision that is empty and has no data values added.

To copy Table Revision data:

Select Settings>Lookup tables. The Lookup tables page opens.
Select the Name hotlink text of the Lookup Table. The Lookup table details page opens.
Select the Name hotlink text of the Table Revision you want to copy data from or copy data to. The Revision details page opens.
On the Revision data panel, select Copy. A drop-down menu appears with two options.
If you want to copy data from the current Revision to another Revision, select Copy data to destination revision. A Select revision dialog appears:

Note that in this example:

The current Revision is Discount Vol Rates Rev 4 and cannot be selected as the destination Revision.
Any ARCHIVED or the PUBLISHED Revision cannot be selected as a destination Revision.

Select the Table Revision you want to copy data to and select Confirm. A copy job is run:

If the copy job completes successfully, a message shows to confirm.
If the copy job fails, you’ll receive an error.
- A common cause of copy data error is when the source and destination Revision data schema do not match.
- You can select Revision data jobs to review and check copy data jobs. See below Reviewing and Managing Revision Data Jobs.

If you want to copy the data from another Revision to the current Revision, then select Copy data from source revision. A Select revision dialog appears:

Note that in this example:

The current Revision is Discount Vol Rates Rev 4 and cannot be selected as the source Revision.
Any ARCHIVED Revisions or empty Revisions - such as Discount Vol Rates Rev 5 in this example - cannot be selected as the source Revision.

Select the Table Revision you want to copy data from and select Confirm. A copy job is run:

Viewing and Comparing Table Revision JSON

As an aid to managing Table Revisions, you can view the JSON for a Revision and open and compare it with another Table Revision’s JSON. To view Table Revision JSON:

Select Settings>Lookup tables. The Lookup tables page opens.
Select the Name hotlink text of the Lookup Table. The Lookup table details page opens.
Select the Name hotlink text of the Table Revision you want to view JSON for. The Revision details page opens.
On the Revision details panel, select View JSON. A modal opens allowing you to review the Revision’s JSON:

You can Copy the JSON to your clipboard.

If you want to compare the Table Revision’s JSON with that of another Revision, use the Select revision to compare drop-down to select the other Revision. The modal adjusts to add in the selected Revision as Comparator to the Original:

Differences in the JSON are highlighted.

Select Close to end your view Revision JSON session.

Downloading Table Revision Data

You can download a Lookup Table Revision’s data in either JSONL or CSV format. To download a Table Revision’s data:

Select Settings>Lookup tables. The Lookup tables page opens.
Select the Name hotlink text of the Lookup Table. The Lookup table details page opens.
Select the Name hotlink text of the Revision whose data you want to download. The Revision details page opens.
On the Revision data panel, select Download data. A popup menu appears.
Select the format which you want to use for the download - Download JSONL or Download CSV:

The revision data is compiled in the selected format and a file downloaded locally.
You can then open the downloaded file using your preferred application and review the Revision’s data.

Tip: Downloading ARCHIVED Revision data? If you open Revision details for an ARCHIVED Revision, then the Revision data panel will show no revision data. This is because when a Revision is archived, its data is stored remotely. However, when you download an ARCHIVED Revision, its data values are retrieved from remote storage and included in the downloaded file.

Uploading Table Revision Data

Instead of manually adding Revision data, as explained in the previous section, you can upload either a JSONL or CSV formatted file to either create the initial Revision schema data values or to update the existing data values.

Note: You can only upload data to a DRAFT Revision.

To upload Table Revision data:

Select Settings>Lookup tables. The Lookup tables page opens.
Select the Name hotlink text of the Lookup Table. The Lookup table details page opens.
Select the Name hotlink text of the Revision you want to upload data values for. The Revision details page opens and the Revision data panel shows the existing data values for the Revision schema fields:
On the Revision data panel, select Upload revision data:

The panel adjusts to allow you to either drag and drop a file or use Select files to open a File upload dialog to select a file for upload:

When you drag & drop or select a JSONL or CSV formatted file, the data values contained in the file are uploaded and used to either create new data values for the Revision schema fields or to overwrite existing values.
At upload, a validation check is performed against selected files. If a file is not correctly JSONL or CSV formatted or contains data fields that don’t match the Revision’s schema, then the upload is blocked and you’ll receive an error.

You’ll receive a confirmation when the upload job has succeeded:

Select Revision data. You can then check that the values contained in the uploaded file have either created new data values or updated the existing values:

Managing Table Revisions

You can edit or delete a draft Table Revision at any time. However:

You cannot edit a published or archived Table Revision.
You cannot delete a published Table Revision.

To manage Lookup Table Revisions:

Select Settings>Lookup tables. The Lookup tables page opens.
Select the Name hotlink text of the Lookup Table. The Lookup table details page opens.
If you want to edit a Table Revision, on the Revisions panel select the Edit icon:

Alternatively, select the Name hotlink text for the Revision to open the Revision details page and then select Edit.

The Edit page opens.

Make your editing changes and select Update revision.

Important: Data already added to a Revision! If you’ve already added data values to a Revision, when you open the Edit page, you will not be able to make any changes to the Revision’s data field schema. You must first delete any data values, re-open the Edit page to make any required changes to the Revision’s data field schema, and then add in new data values.

If you want to delete a Table Revision, on the Revisions panel select the Delete icon:

A confirmation dialog appears.

Select Delete to confirm the delete action.

Reviewing and Managing Revision Data Jobs

On the Revision details page, you can review and manage data jobs that have run for a Revision’s data. There are four types of Lookup Table Revision data jobs:

ARCHIVE. Job runs for the existing PUBLISHED Revision and you publish a DRAFT Revision, which means the existing Revision is automatically archived.
DOWNLOAD. Job runs when you download a Revision’s data.
UPLOAD. Job runs when you upload a data file to create or update a Revision’s data values.
COPY. Job runs when you duplicate a Revision or copy a Revision’s data to another Revision.

You can quickly check the status of a Revision’s data jobs and manage them. If a data job has failed, then a failure reason is given allowing you to follow-up and troubleshoot.

To review and manage Table Revision data jobs:

Select Settings>Lookup tables. The Lookup tables page opens.
Select the Name hotlink text of the Lookup Table. The Lookup table details page opens.
Select the Name hotlink text of the Revision you want to review and manage the data jobs for. The Revision details page opens.
On the Revision data panel, select Review data jobs:

The Status of a Revision data job can be one of three states:

PENDING. The job is queued and has not yet run.
SUCCEEDED. The job ran successfully.
FAILED. The job ran unsuccessfully and you can read-off the Failure reason.

If you want to delete a Revision data job, under Actions select the delete icon:

A confirmation dialog appears.

Select Delete.

Using Multiple Key Fields - Checking Revision Schema Field Order

Your use case when utilizing a Lookup Table might require multiple key fields to be defined for the Lookup Table Revision schema. For example, suppose you want a variable cost amount to be applied which is determined on the basis of three key field values for country, region and charge type. To meet the case you plan to use a Lookup.findNumber() function, such as:

Lookup.findNumber("cost_lookup", "cost", 1, "country", "region", "type")

For this type of case, you must ensure the order in which you’ve set up the three key fields for the published Lookup Table Revision schema corresponds to the order you have used the key fields in the Lookup function. For the above function, the Revision schema key field order would need to be:

Notes:

The top-to-bottom order of the key fields must match the left-to-right order of the key field parameter used in your Lookup function, since this is the order they will be passed into the function.
The names used for the fields in the Revision schema don’t have to match the names used in the Lookup function.
Non-key field order doesn’t need to match.

Reordering Revision Schema Key Fields

After setting up a Table Revision schema, you might need to edit it and reorder the key fields to ensure the order matches the order you’ve used in a Lookup function.

To reorder Revision schema key fields:

Select Settings>Lookup tables. The Lookup tables page opens.
Select the Name hotlink text of the Lookup Table. The Lookup table details page opens.
On the Revisions panel, select the Name hotlink text of the Revision. The Revision details page opens.
Select Edit.
On the Revision fields card, select Revision fields order. A drop-down Order menu appears.

Note that if you’ve already added data values for the Revision schema fields, you won’t be able to edit the field order. You’ll first have to delete any Revision data.

On the Order menu select the field you want to move and drag and drop to where you want to place it in the field order:
When you have achieved the required key field order, select Update revision.