Sage Intacct: Dimension & custom field mappings

​

Overview

Dimensions and custom fields let you push additional categorization and data from Alvys into Sage Intacct on every exported bill and invoice. Configuring them (also called field matching or dimension setup) involves work in two systems: you create the values in Sage Intacct first, then map them to the corresponding Alvys fields from your integration settings. This article walks through all four (4) phases; setting up dimension values in Sage Intacct, mapping those dimensions in Alvys, creating custom fields in Sage Intacct, and mapping custom fields in Alvys — plus the available fields and FAQs.

• Also referred to as: Field matching · Dimension Setup · Dimension Mapping

​

Before You Start

Confirm the following before you begin:

• The Sage Intacct setup wizard in Alvys is complete. The Dimensions and Custom Fields tab does not appear until the wizard finishes.
• You know which Sage Intacct dimension types you want to use. Alvys supports the 11 standard types (Location, Department, Class, Customer, Vendor, Employee, Project, Item, Asset, Contract, and Warehouse) as well as custom dimensions built through the Sage Intacct Platform Apps framework (for example, a custom Equipment dimension).
• If you’re using a custom dimension, its containing Application is deployed in Sage Intacct Platform Services and the Web Services user’s role has List/View access to it under Role Subscriptions. See Sage Intacct: Prerequisites — an undeployed or unpermissioned Application will not appear in the Alvys mapping interface.
• Any required dimensions (those with a red Required badge in Alvys) have dimension values created in Sage Intacct and will have a Default Value set. Required dimensions without a Default Value will block financial exports.
• If you are mapping custom fields, you know which Sage object each should attach to: AR Invoice, AR Invoice Item, AP Bill, or AP Bill Item.
• Required role: Admin or Partner Admin.

​

Steps

Complete the four phases in order. Phases 1 and 3 are performed in Sage Intacct; phases 2 and 4 are performed in Alvys.

​

Phase 1: Set up dimension values in Sage Intacct

A dimension in Sage Intacct is a classification system — think of it as a tag with a set of values — that lets you sort and report on financial data across business segments such as location, department, or class without complicating your chart of accounts. Create the dimension values you need in Sage Intacct before mapping them in Alvys, and repeat this sub-process for each value.

• Navigate to the relevant dimension module. For Location and Department, go to Company > Setup. For other standard dimension types, go to Reports > Setup > Dimensions to manage all dimension types.

• Click Add to begin creating a new dimension value.

• Enter a unique ID for the dimension value. We recommend choosing this ID carefully, as it cannot be changed after creation.

• Enter a Name for the dimension value. Unlike the ID, the name can be updated later if needed.
• Optionally provide a Description or other relevant details depending on the dimension type. For locations, you may also configure a primary Contact with address details that appear on invoices and forms.
• To build a parent-child hierarchy, specify a Parent to nest the new value under an existing one. Leave it blank if the value should sit at the top level.
• Set the Status: Active allows transactions to post against the value. Active Non-Posting, which is available for Department, Location, Class, Customer, Vendor, and Project dimensions, makes the value available for reporting and roll-ups but prevents Alvys from posting transactions directly to it.
• Click Save. The dimension value will now appear in your list and become available for tagging on transactions throughout the system.

Repeat these steps for each additional value you need before mapping in Alvys.

​

Phase 2: Map dimensions in Alvys

After creating dimension values in Sage Intacct, map each dimension to an Alvys field from Settings > Connections > Sage Intacct > Dimensions and Custom Fields. Each dimension is mapped to one Alvys field. The available Alvys fields are:

• Subsidiary: The Alvys subsidiary associated with the transaction.
• Fleet: The fleet assigned to the load or trip.

• Office: The load office associated with the transaction. *Image showing the Load office on the load details page with the change office button highlighted *
• Driver: The driver assigned to the trip.
• Truck: The truck assigned to the trip.
• Trailer: The trailer assigned to the trip.
• Contractor Type: The contractor type of the driver (e.g., Company Driver, Owner Operator).

The Dimension Mappings table shows two (2) columns: Sage Field (the dimension name from Sage; required dimensions carry a red “Required” badge and must be mapped, or exports fail with validation errors) and Alvys Field (an “Add Mapping” dropdown to choose which Alvys field maps to the dimension). Select the appropriate Alvys field from the dropdown for each dimension. Once a dimension is mapped to an Alvys field, control how individual values are matched between the two systems. The mapping panel provides two levels of control: a Default Value and Specific Value Mappings. Default Value. The Default value is a fallback: when an exported transaction’s Alvys value has no specific mapping, Alvys applies the Default as the Sage dimension value, so every transaction is tagged with a valid value. If a dimension is Required in Sage, always set a Default to prevent export failures. With no Default and no specific mapping, Alvys passes the Alvys value through as-is, which may cause validation errors in Sage. Specific Value Mappings. Specific Value Mappings define exact one-to-one matches between individual Alvys values and Sage dimension values — for example, mapping the Alvys “Brokerage” office to the Sage location “Boston” and the Alvys “Inc” office to “San Diego Terminal”. Any value without a specific mapping falls back to the Default. To map values, click the Map Values button next to the dimension in the Dimension Mappings table. A panel opens with two columns — Sage Values (the dimension values from your Sage environment) and Alvys Values (the values from the Alvys field you selected). Match each Sage value to the appropriate Alvys value, and set the Default Value at the top of the panel. After mapping values, the Map Values button updates to show how many values are mapped (e.g., “3 Value(s)”) so you can quickly see which dimensions have value mappings configured.

​

Phase 3: Create a custom field in Sage Intacct

Custom fields are user-defined fields added to standard Sage objects; the Alvys integration can populate them with Alvys data on every exported transaction. They are supported on four Sage objects: AR Invoice (header), AR Invoice Item (line item), AP Bill (header), and AP Bill Item (line item). The object you pick determines where the field appears. Custom fields must exist in Sage Intacct before you can map them in Alvys — repeat this sub-process for each one. Depending on your subscription, navigate to Platform Services > All > Object Customization (or Customization Services > All > Object Customization) and click Add next to Custom Fields. Select the Object to which you want to add the custom field from the dropdown list and click Next. This is where you choose the object type, for example AR Invoice, AP Bill, AR Invoice Item, or AP Bill Item. Select the Data Type for your custom field and click Next. The data type determines what kind of information the field will accept. Only the following data types are supported by the Alvys integration:

• Date: Date values.
• Currency: Monetary amounts.
• Number: Numeric values.
• Text: Short text strings (up to the character limit defined in Sage Intacct).
• Text Area: Longer text content.

Do not select these unsupported types, as they cannot be mapped to Alvys: Picklist, Picklist (multi-select), Checkbox, Email, Percent, Sequence, URL, or Password. Unsupported custom field types will not appear in the mapping interface. Enter a Label for the field. This is the text that will appear next to the field in the user interface. Sage Intacct will auto-suggest a Field ID based on the label. The Field ID is used by APIs and cannot contain spaces. Define any additional field characteristics based on the data type you selected, such as field length, decimal places, default values, or picklist values, and click Next. Configure Deployment Options and click Done: set whether the field is required, and the section and tab where it appears on the Sage record.

​

Phase 4: Map custom fields in Alvys

Alvys provides built-in fields, organized into seven groups, that can be mapped to Sage custom fields:

• Load Fields: Carrier Invoice Number, Subsidiary, PO Number, Order Number, BOL Number, Office, Fleet, Equipment, Commodity, Weight, Volume, Invoiced Date, Created Date.
• Customer Fields: Net Payment Terms, Miles, Sales Agent.
• Dispatch Fields: Total Miles, Loaded Miles, Empty Miles, Dispatched By, Dispatched Date.
• Shipper Fields: Name, Address, City, State, Country, Pickup Date.
• Consignee Fields: Name, Address, City, State, Country, Delivery Date.
• Equipment Fields: Truck, Trailer.
• Driver Fields: Primary, Secondary, Fleet.

In addition, two Custom Reference types can be mapped: Custom Load References (resolved from the load at export) and Custom Trip References (resolved from the trip at export). These appear in the Alvys Field dropdown grouped under their own headings. Custom references are managed under Settings > Custom References, organized into six tabs (Loads, Trips, Stops, Drivers, Trucks, Trailers). From there you can create a New Reference, name and describe it, pick a field type (Text, Date, etc.), and configure whether it shows within Alvys and on documents. The Custom Field Mappings table displays seven columns: Sage Field, Code, Object, ID, Type, Chars (max character length), and Alvys Field (a dropdown grouped by category). To map a custom field, find it in the table and select the Alvys field in the last column — only type-compatible Alvys fields appear. Custom field mappings can be configured during initial setup or any time afterward. During initial setup, they are configured at Step 5: Advanced Settings, where Alvys retrieves your available Sage custom fields and you select the Alvys field for each. After setup, modify mappings from Settings > Connections > Sage Intacct: click the integration for your subsidiary, select the Dimensions and Custom Fields tab, and use the same mapping interface. Mapping changes apply to future exports only — invoices and bills already in Sage are not retroactively updated.

​

Result

After completing all four phases:

• Dimension mappings are active: every financial export from Alvys includes the configured dimension values in the corresponding Sage Intacct fields.
• Custom field mappings are active: every export includes Alvys data in the configured custom fields on the selected Sage objects.
• Required dimensions with a Default Value set no longer block financial exports.
• Tip: export one test transaction and verify the values land correctly in Sage before bulk exporting.

​

Variations

• Updating mappings after initial setup: Add, change, or remove dimension and custom field mappings any time from the Dimensions and Custom Fields tab. Changes apply to future exports only.
• Required dimension with no Default Value: If a required dimension has no Default Value and an unmapped Alvys value reaches export, the export fails. Open Map Values for that dimension and set a Default Value.

​

Troubleshooting

​

Financial exports fail after dimension mapping is configured

• Open Settings > Connections > Sage Intacct > Dimensions and Custom Fields and expand Dimension Mappings.
• Identify any dimension with a red Required badge, and confirm an Alvys field is selected for each.
• Click Map Values for each required dimension and confirm a Default Value is set — exports fail for any unmapped Alvys value when no Default is configured.
• If a required dimension does not appear, confirm the matching Sage subscription is active (Asset → Fixed Assets Management; Contract → Contracts; Warehouse → Inventory).
• If none of the above apply, contact Alvys support.

​

A custom dimension does not appear in the Alvys mapping interface

• In Sage Intacct, confirm the Application containing the custom dimension (for example, “WD Reports”) is deployed in Platform Services. An undeployed Application’s objects never appear in Role Subscriptions or in the Alvys mapping interface.
• Go to Company > Roles > (the Web Services user’s role) > Subscriptions, open the Application’s permissions, and confirm List and View are checked for the custom dimension under Objects.
• If recently deployed or permissioned, refresh the Sage Intacct integration settings page and expand Dimension Mappings again.
• If it still does not appear, contact Alvys support.

​

A custom field does not appear in the Alvys mapping interface

• Confirm the field uses a supported data type (Date, Currency, Number, Text, Text Area). Unsupported types are not displayed.
• Confirm the field is on a supported object (AR Invoice, AR Invoice Item, AP Bill, AP Bill Item).
• If recently created, refresh the Sage Intacct integration settings page and expand Custom Field Mappings again.
• If it still does not appear, contact Alvys support.

​

Exported values are truncated in Sage Intacct

• In the Custom Field Mappings table, check the Chars column for the field’s maximum length in Sage.
• If the Alvys value typically exceeds that limit, increase the field’s maximum length in Sage via Object Customization and export again.
• If the limit cannot be increased, map a shorter Alvys field or use a Custom Reference with a truncated value.

​

FAQs

Q: What is the main benefit of dimensions instead of modifying my chart of accounts? A: Dimensions let you tag, slice, and report on financial data across business segments (location, fleet, driver) without overcomplicating your chart of accounts. When you add a new dimension value, all existing account codes automatically become available to it. Q: Can I use Custom Dimensions with the Alvys integration? A: Yes, in addition to the 11 standard dimension types (Location, Department, Class, Customer, Vendor, Employee, Project, Item, Asset, Contract, Warehouse). A custom dimension built through Sage Intacct Platform Apps must have its containing Application deployed, with List/View permissions granted to the Web Services user’s role under Role Subscriptions, before it appears in Alvys. See Sage Intacct: Prerequisites. Q: What does “Active Non-Posting” status mean for a dimension value? A: The value is available for reporting and roll-ups in Sage Intacct, but Alvys cannot post transactions directly to it. Q: What is the difference between a Default Value and a Specific Value Mapping? A Specific Value Mapping is an exact one-to-one match between an Alvys value and a Sage dimension value (e.g., Alvys “Brokerage” → Sage “Boston”). The Default Value is the fallback applied when an Alvys value has no specific mapping, preventing export errors. Q: What happens if a dimension has a red “Required” badge in the mapping table? A: It is required by your GL accounts in Sage. You must map it in Alvys and set a Default Value, otherwise exports fail with validation errors. Q: Which Sage Intacct object types support custom fields in this integration? A: Four: AR Invoice (header), AR Invoice Item (line item), AP Bill (header), and AP Bill Item (line item). Q: What data types are supported when creating custom fields for Alvys mapping? A: Date, Currency, Number, Text, and Text Area. Unsupported types (Picklist, multi-select Picklist, Checkbox, Email, Percent, Sequence, URL, Password) do not appear in the Alvys mapping interface. Q: Which Alvys Custom References can I map to Sage Intacct? A: Two: Custom Load References and Custom Trip References (of the six custom reference entities Alvys supports). Q: If I update a custom field mapping today, will it update my past invoices in Sage? A: No. Mapping changes take effect on future exports only; previously exported transactions are never retroactively updated. Q: Why should I pay attention to the “Chars” column in the Custom Field Mappings table? A: It shows the maximum character length Sage Intacct allows for that text field. If the Alvys value exceeds it, the value is truncated on export.

​

Go Deeper

• Sage Intacct: Transaction Export and Modification
• Sage Intacct Integration Collection