Exporting Invoices
Exporting creates a CSV file containing invoice data along with data from the Sales module reflecting the last time the deal went active. This is typically imported into your Financial or invoicing application to create the actual billing data that you send to customers. This can also be done to review invoice data before sending it to an external system.
This topic contains:
-
Export File Format including Data Formats, Configuration Options and Supported Export Fields.
Export Actions
From the main Invoices grid, you can export one or more invoices as needed. Which invoices export depends on whether invoice rows are checked in the grid and the Finance Workflow if it is configured.
-
If any rows are checked, only the checked rows on the currently displayed page are exported.
-
If no rows are checked, all rows for which the current filter applies are exported, across all pages.
The Export button is enabled when exactly one Billing Period is filtered or you have checked specific invoices. When you click Export, you are prompted to choose the format/template and destination:
-
Choose a Template lists any export formats/templates that were configured for the Invoicing Organization. Operative can configure multiple templates on request and the names can be customized. This lets you have a different file format for reviewing invoice data versus the file format needed by your consuming financial system.
-
Choose Destination lets you choose between two options depending on your roles’ permissions:
-
Download/Email sends a link to access the file (or error details) to the email address of the user who clicks the Export button. The file is also accessible with the notifications icon in the upper right. Depending on how many invoices are involved, it may take over a minute for the file to appear.
The link to access the file remains valid for seven days through both the email and notification.
-
-
Financial System transfers the file to a location accessible to your internal processes that import the file into your Financial System. This is done typically via S3 or S/FTP. When this is checked, the system also produces and delivers a control file that describes the export file. This helps an external system verify the integrity of the file and its ingestion into the financial system.
Separate permissions control the two destination options, so some users can be restricted from exporting to the Financial System or from Download/Email depending on the needs of your organization.
If you use the Finance Workflow, it may control when you can or cannot export depending on how the workflow is configured. The Export button prevents requesting an action that is not allowed for a specific invoice, but when requesting to export multiple invoices when at least one invoice in the filtered set across all pages allows the action, the export option appears for selection. If some invoices are not allowed to export in their current status, then those invoices do not appear in the export but others will. Exporting to the Finance System outranks exporting to download. For example, if you select four invoices and only two of them are allowed to export to the Financial System, even if you have selected both export to download and export to Financial System, only the two invoices allowed on the Financial System appear in the generated file. In addition, after exporting, the Invoice Status can automatically change based on when the export starts or completes.
When you export an invoice to a Finance System, AOS keeps track of some additional details, which can optionally appear within subsequent exports. These fields are stored in the system after the export is started, so are not reflected on that export itself. However, on any future export, they show what happened previously. These fields are intended for reporting purposes or if you export multiple times:
-
First Exported Date is the date and time a specific invoice was exported to a financial system.
-
First Exported By is the user login who first exported a specific invoice to a financial system.
-
Latest Export Date (Invocies Grid ) or Previous Export Date (Export) is the date and time a specific invoice was most recently exported to a financial system.
-
Previous Exported By is the user login who last exported to a financial system.
-
Number of Exports is a count of exports to a financial system.
The Number of Exports and Latest Export Date fields are in the Invoices Grid and the export, but the other fields are only exposed within the Finance Export at this time. The date, user, and count correspond to the invoice and not the invoice line item.
Export File Format
The following sections describe the available Finance export file fields and current formatting conventions. A Finance export also called an invoice export, is a CSV file containing the details of the invoice lines along with their associated invoices, deal lines, and deals. The file is typically imported into an accounting system from which you generate your actual invoices to send to your customers.
Data Formats
-
Each row in the export represents an invoice line. Although the file can be configured to also include rows for Non-Invoice CLIs.
-
At this time, the Export file is available only as a CSV file, where commas are the field delimiters.
-
Dates appear in YYYY-MM-DD format.
-
Dates with time appear in YYYY-MM-DD hh:mm:ss format and convert to the time zone of the user who requested the export. However, the date stamp in the file name is always in UTC.
-
Line breaks use line feed without carriage return, as is common in Unix-based systems (including Apple). However, Windows and Excel will interpret this properly in most cases.
-
At this time, strings are only quoted when they contain an ambiguous character.
-
Characters use UNICODE.
Note: Be aware that if you open the files in Excel, non-English UTF-8 characters (e.g., é ß, €, £, Ä) appear incorrectly because by default Excel does not expect UNICODE. Confirm the characters appear correctly in a UNICODE text editor and then adjust Excel’s file encoding if you need to use Excel The export is designed for data exchanges between systems rather than for Excel, and most systems prefer UTF-8.
-
Many monetary values show four decimal places, but the last two may be zeroes depending how the system is configured as explained in Decimal Precision.
-
The name of the file is configurable on the backend. A prefix is defined along with the export format and this gets appended with a timestamp in UTC using the form - YYYYMMDDThhmmssZ. For example, if the file prefix is configured as “General-Invoice-Export” and the export request is made at 11:05 AM EST on January 4, 2022, from New York, the name of the file reflects UTC (4:05 PM) and is “General-Invoice-Export-20220104T160500Z.CSV”.
-
Multi-select fields that are concatenated into single-cell strings have their values separated by semicolons. For example, if more than one Tag is set on a Product, the Product Tags field shows all the Tags:
Tag Number 1;Tag Number 2
An exception to using semicolons to separate multiselect options is made for Grouped, Boolean Expression, and (FreeWheel) Combination targets which use commas to match the same friendly syntax that appears elsewhere within AOS.
Configuration Options
When AOS is first installed, a single export template named “Total Fields List” is usually available for all invoicing organizations. This produces a file whose name is prefixed with “FinanceTotalFieldList”. This lets you evaluate most available fields, but Operative does not recommend using this format. Instead, you should use this documentation to determine which columns you actually need and work with Operative to set up customized templates for your organizations. It is not a good idea to take all available fields just in case you might need them in the future as this creates unnecessary large files and increased processing time.
Operative can set up as many different export templates as you need and associate them with different invoicing organizations. At this time, Operative must configure export files for you.
The following are configurable by Operative on your behalf:
-
Which fields from the set of supported fields. You can remove any columns you do not wish to use and if a field is documented as supported by the export but does not appear, you can add it. Not all fields in the system are supported. You can only use those documented in the Supported Export Fields Finance export topics that directly follow this one.
-
The sequence (order) of the columns.
-
The column labels/headers. While you can change the column header, this is not recommended because if you open a support case, Operative may not be aware of what column you are referring to.
-
The prefix of the file name, preceding the time stamp and file extension
-
The display name a user selects in the Choose a template drop-down list when exporting.
-
The invoicing organizations that use the template. A template can be used with a single invoicing organization or shared across multiple organizations depending on your needs.
You can also have blank columns, duplicate columns with the same or different headings, or columns that have a hard coded value across all rows.
Supported Export Fields
The following tables describe the fields available for export. The Internal Key column is used when internally defining the export format. Using the Default Header is recommended so that Operative support is best able to assist you with any issues that arise in the future. However, if you need to customize the header, any standard English language character is supported. If a field is not listed in these tables, that field is not currently supported and cannot be added to the export file without a feature request and development effort.
Fields can be exported at the following levels
-
Export Meta Data meta data
Deal Header Fields
The following fields appear for the Deal Header level data as set in the Sales module. Most fields reflect values at the time the deal was last sent to Finance. When a deal is undergoing a revision, the revision details are only exposed to Finance after the deal moves completely through the Sales revision workflow. These fields will repeat across all rows for all invoice lines in the same deal.
Default Header |
Internal Key |
Description |
Type |
---|---|---|---|
Deal ID |
dealFriendlyId |
This is the unique integer Deal ID that appears throughout AOS. |
int(11) |
Internal Deal ID |
dealId |
This is a unique internal string for the Deal ID that appears with the API and data stream. |
12-byte hexadecimal or use string (e.g., varchar(50)) |
Deal Name |
dealName |
This is the name of the deal from Sales. |
varchar(250) |
Deal Start Date |
dealStartDate |
This is the Start Date in Sales. |
date |
Deal End Date |
dealEndDate |
This is the End Date in Sales. |
date |
Deal Gross Cost |
dealGrossCost |
This is the gross monetary value of the deal as it appears in the Sales module. It does not reflect delivery or invoice data. |
decimal(19,4) |
Deal Net Cost |
dealNetCost |
This is the net monetary value of the deal as it appears in the Sales module. It does not reflect delivery or invoice data. |
decimal(19,4) |
Deal Quantity |
dealQuantity |
This is the total Quantity value of the deal as it appears in the Sales module. It does not reflect delivery or invoice data. |
bigint(20) |
Deal Revision Status |
dealRevisionStatus |
This reflects the current Revision Status of the deal in the Sales module, letting Finance users know when a deal may be undergoing changes. For deals that have never gone through a revision, this shows [NONE]. This is the only field that reflects a real-time state in the Sales module. All the other fields reflect only the values the deal had when it last completed the Sales workflow. |
varchar(255) |
Internal Billing Account ID |
dealBillableAccountId |
This is a unique internal string ID for the account set to be billed. It is useful when using the API or data stream. On the deal’s Accounts tab, if an account is explicitly set with the Billing role, that account is used. If not, then if there is only one advertiser and one agency, the agency is billed. If there is no agency, then the advertiser itself is billed. Note: The Finance Sync from Sales may fail if the three default roles of AOS Billing, Buying, and Paying have their names changed in the System Configuration module. |
12-byte hexadecimal or use string (e.g., varchar(50)) |
Billing Account ID |
dealBillableAccountAOSAccId |
This is the unique friendly ID for the account set to be billed. This is typically an integer unless a non-standard configuration is set up. It is the ID field that appears when you open the advertiser or agency within the Master Data Management module. On the deal’s Accounts tab, if an account is explicitly set with the Billing role, that account is used. If not, then if there is only one advertiser and one agency, the agency is billed. If there is no agency, then the advertiser itself is billed. |
varchar(100) |
Billing Account MDM ID |
billingAccountMdmId |
This adds the MDM ID field from the Master Data Management module for the deal's billing account. In some cases, this field is labeled CRM ID in the Master Data Management module. |
varchar(100) |
Billing Account Name |
dealBillableAccountName |
This is the name of the advertiser or agency set to be billed for the deal. |
varchar(100) |
Billing Account Credit Status |
dealBillableAccountCreditStatus |
This shows the Credit Status for the account as it appears in the Master Data Management module. |
varchar(100) |
Billing Account Active |
dealBillableAccountStatus |
True indicates the account is active in the Master Data Management and False indicates it is inactive. |
boolean |
Billing Account Type |
dealBillableAccountType |
This is “advertiser” or “agency” depending on which is billed. |
varchar(25) |
Billing Account Address 1 |
billingAccountAddress1 |
This is the Address/Street 1 field from the Master Data Management module for the address marked as the Billing role for the Billing Account on the deal's Accounts tab. If an address is explicitly, set with the Billing role on the deal's Accounts tab when the deal last went active, that address is used with its latest details from the Master Data Management module. If no address appears under the account on the deal's Accounts tab, then if one and only one address has the Billing role for the account within the Master Data Management module, that address is used. This applies to all the following Billing Account address fields. |
varchar(255) |
Billing Account Address 2 |
billingAccountAddress2 |
This is the Address/Street 2 field from the Master Data Management module for the address marked as the Billing role for the Billing Account on the deal's Accounts tab. |
varchar(255) |
Billing Account City |
billingAccountCity |
This is the City field from the Master Data Management module for the address marked as the Billing role for the Billing Account on the deal's Accounts tab. |
varchar(100) |
Billing Account Country |
billingAccountCountry |
This is the Country field from the Master Data Management module for the address marked as the Billing role for the Billing Account on the deal's Accounts tab. |
varchar(100) |
Billing Account State Region |
billingAccountState |
This is the State field from the Master Data Management module for the address marked as the Billing role for the Billing Account on the deal's Accounts tab. |
varchar(100) |
Billing Account Postal Code |
billingAccountPostalCode |
This is the Zip (Postal) Code field from the Master Data Management module for the address marked as the Billing role for the Billing Account on the deal's Accounts tab. |
varchar(100) |
Billing Account Email |
billingAccountEmail |
This is the Email from the Master Data Management module for the address marked as the Billing role for the Billing Account on the deal's Accounts tab. |
varchar(100) |
Billing Account Phone |
billingAccountPhone |
This is the Phone from the Master Data Management module for the address marked as the Billing role for the Billing Account on the deal's Accounts tab. |
varchar(50) |
Billing Contact ID |
dealBillableContactId |
If a contact has the billing role on the deal’s Accounts tab, this is a unique internal string ID for that contact. |
12-byte hexadecimal or use string (e.g., varchar(50)) |
Billing Contact Name |
dealBillableContactName |
If a contact has the billing role on the deal’s Accounts tab, this is the first and last name. |
varchar(201) |
Billing Contact Address 1 |
billingContactAddress1 |
This is the Address/Street 1 field from the Master Data Management module for the address marked as the Billing role for the Billing Contact on the deal's Accounts tab. If an address is explicitly, set under the Billing Account with the Billing role on the deal's Accounts tab, that address is used with its latest details from the Master Data Management module. If no address appears under the contact on the deal's Accounts tab, then if one and only one address has the Billing role for the contact within the Master Data Management module, that address is used. This applies to all the following Billing Contact address fields. |
varchar(255) |
Billing Contact Address 2 |
billingContactAddress2 |
This is the Address/Street 2 field from the Master Data Management module for the address marked as the Billing role for the Billing Contact on the deal's Accounts tab. |
varchar(255) |
Billing Contact City |
billingContactCity |
This is the City field from the Master Data Management module for the address marked as the Billing role for the Billing Contact on the deal's Accounts tab. |
varchar(100) |
Billing Contact Country |
billingContactCountry |
This is the Country field from the Master Data Management module for the address marked as the Billing role for the Billing Contact on the deal's Accounts tab. |
varchar(100) |
Billing Contact State Region |
billingContactState |
This is the State field from the Master Data Management module for the address marked as the Billing role for the Billing Contact on the deal's Accounts tab. |
varchar(100) |
Billing Contact Postal Code |
billingContactPostalCode |
This is the Zip (Postal) Code field from the Master Data Management module for the address marked as the Billing role for the Billing Contact on the deal's Accounts tab. |
varchar(100) |
Billing Contact Email |
billingContactEmail |
This is email field from the Master Data Management module for the address marked as the Billing role for the Billing Contact on the deal's Accounts tab. |
varchar(100) |
Billing Contact Phone |
billingContactPhone |
This is phone field from the Master Data Management module for the address marked as the Billing role for the Billing Contact on the deal's Accounts tab. |
varchar(100) |
Internal Advertiser ID |
dealAdvertiserId |
This is a unique internal string ID for the advertiser for the deal. It is useful when using the API or data stream. |
12-byte hexadecimal or use string (e.g., varchar(50)) |
Advertiser ID |
dealAdvertiserAOSAccId |
This is the unique friendly ID for the advertiser. This is typically an integer unless a non-standard configuration is set up. It is the ID field that appears when you open the advertiser within the Master Data Management module. |
varchar(100) |
Advertiser MDM ID |
advertiserMdmId |
This adds the MDM ID field from the Master Data Management module for the deal's advertiser. In some cases, this field is labeled CRM ID in the Master Data Management module. |
varchar(100) |
Advertiser Name |
dealAdvertiserName |
This is the name of the advertiser for the deal. |
varchar(250) |
Advertiser Industry |
dealAdvertiserIndustry |
This shows the industry Category field from the Master Data Management module. |
varchar(250) |
Advertiser Active |
dealAdvertiserStatus |
True indicates the account is active in the Master Data Management and False indicates it is inactive. |
boolean |
Advertiser Contact ID |
dealAdvertiserContactId |
If a contact with a role other than billing is on the deal’s Accounts tab under the advertiser, this is a unique internal string ID for that contact. If there are multiple contacts, they are separated by semicolons sorted by the last name. |
Each contact is 12-byte hexadecimal or use string (e.g., varchar(50)) BUT s can contain n contacts. Practically speaking this is unlikely to exceed 250 to 1000 characters. |
Advertiser Contact Name |
dealAdvertiserContactName |
If a contact with a role other than billing is on the deal’s Accounts tab under the advertiser, this is the first and last name. If there are multiple contacts, they are separated by semicolons sorted by the last name. |
String. This concatenates if there are multiple contacts. A single contact will not exceed 201 characters, but this can contain n contacts. Practically speaking this is unlikely to exceed 400 to 1000 characters. |
Internal Agency ID |
dealAgencyId |
This is a unique internal string ID for the buying agency for the deal. It is useful when using the API or data stream. |
12-byte hexadecimal or use string (e.g., varchar(50)) |
Agency ID |
dealAgencyAOSAccId |
This is the unique friendly ID for the buying agency. This is typically an integer unless a non-standard configuration is set up. It is the ID field that appears when you open the agency within the Master Data Management module. |
varchar(100) |
Agency MDM ID |
agencyMdmId |
This adds the MDM ID field from the Master Data Management module for the deal's buying agency. In some cases, this field is labeled CRM ID in the Master Data Management module. |
varchar(100) |
Agency Name |
dealAgencyName |
This is normally the name of the Buying Agency from the deal. If there is only one Agency on the deal, and it does not have the Buying role, it will appear and be used for the other Agency fields. If two agencies have the Buying role, only one appears and which is arbitrary. You should avoid having multiple agencies on a deal with the Buying role. Note: The Finance Sync from Sales may fail if the three default roles of AOS Billing, Buying, and Paying have their names changed in the System Configuration module. |
varchar(250) |
Agency Active |
dealAgencyStatus |
True indicates the account is active in the Master Data Management and False indicates it is inactive. |
boolean |
Agency Contact ID |
dealAgencyContactId |
If a contact with a role other than billing is on the deal’s Accounts tab under the agency, this is a unique internal string ID for that contact. If there are multiple contacts, they are separated by semicolons sorted by the last name. |
Each contact is 12-byte hexadecimal or use string (e.g., varchar(50)) BUT s can contain n contacts. Practically speaking this is unlikely to exceed 250 to 1000 characters. |
Agency Contact Name |
dealAgencyContactName |
If a contact with a role other than billing is on the deal’s Accounts tab under the agency, this is the first and last name. If there are multiple contacts, they are separated by semicolons sorted by the last name. |
String. This concatenates if there are multiple contacts. A single contact will not exceed 201 characters, but this can contain n contacts. Practically speaking this is unlikely to exceed 400 to 1000 characters. |
Calendar ID |
dealCalendarId |
This is a unique string ID for the Calendar matching the underlying key for the System Configuration module which is used in the Calendar API. |
varchar(250) |
Calendar Name |
dealCalendarName |
This is the name of the calendar used by the invoice. |
varchar(250) |
Organization ID |
dealOrganizationId |
This is the primary key integer ID for the Invoicing Organization. It will be the same for all rows. |
int(10) |
Invoicing Organization |
dealInvoicingOrganization |
This is the name of the Invoicing Organization set on the Deal and inherited by the invoice. |
varchar(50) |
Sales Team |
dealTeam |
This is the name of the Team from the Deal Header. It appears in the Sales module popup window that launches through the dots next to the Primary Account Executive. If there are multiple users, it is the Sales Team for the Primary Account Executive. |
varchar(50) |
Organization Parent Organization |
parentOrganizationName |
This is the name of the organization above the Invoicing Organization within the hierarchy in the System configuration module’s Organization’s page. This is empty for the Global Organization. |
varchar(50) |
Organization Phone |
phone |
This is the Phone field that appears for the Invoicing Organization. |
varchar(25) |
Organization Email |
|
This is the Email field that appears for the Invoicing Organization. |
varchar(50) |
Organization Description |
description |
This is the Description field that appears for the Invoicing Organization. |
text |
Organization Billing Address Line 1 |
billingAddressLine1 |
This is the Address Line 1 field that appears with the Billing Address details of the Invoicing Organization. |
varchar(255) |
Organization Billing Address Line 2 |
billingAddressLine2 |
This is the Address Line 2 field that appears with the Billing Address details of the Invoicing Organization. |
varchar(255) |
Organization Billing Address City |
billingAddressCity |
This is the City field that appears with the Billing Address details of the Invoicing Organization. |
varchar(50) |
Organization Billing Address State Region |
billingAddressStateProvinceRegion |
This is the State/Province/Region field that appears with the Billing Address details of the Invoicing Organization. |
varchar(50) |
Organization Billing Address Postal Code |
billingAddressZipPostalCode |
This is the Zip/Postal Code field that appears with the Billing Address details of the Invoicing Organization. |
varchar(25) |
Organization Billing Address Country |
billingAddressCountry |
This is the Country field that appears with the Billing Address details of the Invoicing Organization. |
varchar(50) |
Owner ID |
dealOwnerId |
This is the system login name for the deal’s Owner if one is set on the deal header in the Sales module popup window that launches through the dots next to the Primary Account Executive. |
varchar(50) per each |
Owner Name |
dealOwnerName |
This is the first and last name for the deal’s Owner if one is set on the deal header in the Sales module popup window that launches through the dots next to the Primary Account Executive. |
varchar(100) |
Primary Sales Person ID |
dealSalesPersonId |
This is the system login name for the deal’s Primary Account Executive user. |
varchar(50) |
Primary Sales Person Name |
dealSalesPersonName |
This is the first and last name for the deal’s Primary Account Executive user. |
varchar(100) |
Primary Salesperson with Commission |
dealPrimarySalesPersonWithCommission |
This is the first and last name of the order's primary account executive, and it also includes the salesperson's Commission Split %. For example:
|
varchar(110) |
Primary Salesperson Commission |
dealPrimarySalesPersonCommission |
This is the commission split % for the Primary Account Executive expressed as a percentage, not a decimal. For example, 10% does not appear as ".10". It appears literally as:
The value includes the "%" character, so it might be interpreted as a string. Whether to import and persist it as a string or decimal is up to your needs. You may wish to convert it. At this time, the decimal places are always zeroes, but support for up to two decimal places is planned. |
See Description |
Primary Salesperson Employee ID |
dealSalesPersonEmployeeId |
This is the Employee ID field that appears with the Primary Account Executive's details in the User Management module. |
varchar(50) |
Primary Salesperson Address Line 1 |
primarySalesPersonAddress.addressLine1 |
This is the Address Line 1 field that appears with the Primary Account Executive's details in the User Management module. |
varchar(255) |
Primary Salesperson Address Line 2 |
primarySalesPersonAddress.addressLine2 |
This is the Address Line 2 field that appears with the Primary Account Executive's details in the User Management module. |
varchar(255) |
Primary Salesperson City |
primarySalesPersonAddress.city |
This is the City field that appears with the Primary Account Executive's details in the User Management module. |
varchar(100) |
Primary Salesperson Country |
primarySalesPersonAddress.country |
This is the Country field that appears with the Primary Account Executive's details in the User Management module. |
varchar(100) |
Primary Salesperson Zip |
primarySalesPersonAddress.zip |
This is the Zip / Postal Code field that appears with the Primary Account Executive's details in the User Management module. |
varchar(100) |
Primary Salesperson Email |
primarySalesPersonAddress.email |
This is the Email field that appears with the Primary Account Executive's details in the User Management module. |
varchar(100) |
Primary Salesperson Phone |
primarySalesPersonAddress.phone |
This is the Phone field that appears with the Primary Account Executive's details in the User Management module. |
varchar(100) |
Primary Salesperson Mobile |
primarySalesPersonAddress.mobile |
This is the Mobile field that appears with the Primary Account Executive's details in the User Management module. |
varchar(100) |
Primary Salesperson Fax |
primarySalesPersonAddress.fax |
This is the Fax field that appears with the Primary Account Executive's details in the User Management module. |
varchar(100) |
Additional Salesperson |
dealAdditionalSalesperson |
This shows any Account Executives who are not the Primary Account Executive on the deal. More than one are semicolon separated. This concatenates multiple account executives, so the size of the field depends on how many account executives you expect on deals. |
varchar size based on usage |
Additional Salesperson with Commission |
dealAdditionalSalesPersonWithCommission |
This shows any Account Executives who are not the Primary Account Executive on the deal along with their commission splits. If there is more than one, they are semicolon separated. The size of the field depends on how many account executives you ever have on a deal. |
varchar size based on usage |
Terms And Conditions ID |
termsAndConditions.id |
This shows the internal system ID for the Terms and Conditions on the Deal Header. This is useful with the API and data stream. |
12-byte hexadecimal or use string (e.g., varchar(50)) |
Terms And Conditions Name |
termsAndConditions.name |
This shows the Terms and Conditions name if those were set on the Deal Header. This field must be enabled within the Sales module if it does not appear. |
varchar(250) |
Billing Terms ID |
billingTerm.id |
This shows the internal system ID for the Billing Terms set on the Deal Header. This is useful with the API and data stream. |
12-byte hexadecimal or use string (e.g., varchar(50)) |
Billing Terms Name |
billingTerm.name |
This shows the Billing Terms set on the Deal Header. This field must be enabled within the Sales module if it does not appear. Note: Billing Terms are categories assigned to the deal and do not affect calculations. They are not related to the invoice terms that do affect calculations. |
varchar(100) |
Order Type Name |
orderType.name |
This shows the Order Type set on the Deal Header. |
varchar(100) |
Currency Code |
currencyCode |
This is the three-letter currency code (e.g., USD) for the deal. |
varchar(5) |
Deal Notes |
dealNotes |
This shows the optional Deal Notes text area field on the Deal Header. This field is directly on the header, and It is not related to the separate Notes that are launched using the notes icon. This field may need to be enabled by Operative in order to appear within the Sales module. The internal name is planNotes. |
varchar(1000) |
CPE |
cpe |
This shows the CPE from the Deal Header. This field must be enabled within the Sales module if it does not appear. |
varchar(255) |
RFP ID |
rfpId |
This shows the RFP ID set on the Deal Header. This field must be enabled within the Sales module if it does not appear. |
varchar(255) |
Deal Created By |
dealCreatedBy |
This shows the login ID of the AOS account that created the deal within the Sales module. It matches the Created By field that normally appears at the bottom of the default deal header in the Sales module. |
varchar(100) |
Deal Created Date |
dealCreatedDate |
This shows the Created On date and time reflecting the first time the deal header was saved within the Sales module. It matches the Created On field that normally appears at the bottom of the default deal header in the Sales module. |
dateTime |
Sales Line Item Fields
The following fields appear for the Line Item data as they were set in the Sales module.
Default Header |
Internal Key |
Description |
Type |
---|---|---|---|
Internal Line Item ID |
internalLineItemId |
This is a unique internal string for the Sales Line Item ID that appears with the API and data stream. |
12-byte hexadecimal or use string (e.g., varchar(50)) |
Line Item ID |
lineItemID |
This is a friendly integer ID for the Sales Line Item within the deal that is unique across deals. It is sometimes referred to as a sequential ID. |
bigint |
Line Item Number |
lineItemNumber |
This is the ID of the Sales Line Item within the deal that is only unique within the deal itself, and not unique across deals. It can be a decimal when there are packages and the child lines have the integer portion of their parent. For example, if the parent line number is 3 and the package has two children, the children have the numbers 3.1 and 3.2. |
decimal(10,4) |
Line Item Name |
deallineName |
This is the name of the line item. |
varchar(250) |
Is Cancelled |
isCancelled |
This shows TRUE only if the Sales module cancel feature was used on the line item in a revision and that revision completed its workflow. It does not indicate when the cancellation occurred though. Whether to bill the value or not is up to your internal processes. A cancelled line may still have delivered before being cancelled. If you exported when this was FALSE, but it was later cancelled, subsequent exports will show TRUE when the Sales workflow completes as this field reflects Sales values rather than Finance values. The Finance module treats cancelled lines as modifications and does not do anything special with them. |
boolean |
Line Item Net Cost |
deallineNetCost |
This is the Net Cost as it appears in the Sales module. It does not reflect delivery or invoice data. |
decimal(15,4) |
Line Item Net Unit Cost |
deallineNetUnitCost |
This is the line item Net Unit Cost as it appears in the Sales module. |
decimal(15,4) |
Line Item Quantity |
deallineQuantity |
This is the line item Quantity as it appears in the Sales module. It does not reflect delivery or invoice data. |
bigint(20) |
Line Item Start Date |
deallineStartDate |
This is the line item Start Date, not the invoice line date. |
date |
Line Item End Date |
deallineEndDate |
This is the line item End Date, not the invoice line date. |
date |
Unit Type |
deallineUnitType |
This is the Unit Type that will reflect what the Primary Performance and Third-Party Performance correspond to. |
varchar(100) |
Cost Method |
deallineCostMethod |
This is the Cost Method that determines how values are calculated along with the Invoice Terms, Net Unit Cost, Net Cost, Quantity, delivery, and other considerations. |
varchar(100) |
Line Item Unit Cost Without Discounts |
unitCostBeforeDiscounts |
This is the Unit Cost Before Discounts as it appears for the line item in the Sales module. |
decimal(15,4) |
Line Item Gross Unit Cost |
deallineGrossUnitCost |
This is the Gross Unit Cost as it appears for the line item in the Sales module. |
decimal(15,4) |
Line Item Gross Cost |
deallineGrossLineItemCost |
This is the Gross Cost as it appears in the Sales module. It does not reflect delivery or invoice data. |
decimal(15,4) |
Line Item Net Bonus |
deallineNetBonus |
This shows the Line Item Value only when Bonus is True based on the Line Class. When Bonus is False, this shows 0. It is not based on the invoice line and delivery information, This is the Sales bonus value for the entire line item that sometimes is referred to as the Added Value Amount as sold. |
decimal(15,4) |
Forecast Category |
deallineForecast |
This is the forecast category that Sales chose based on the context of the deal and line. |
varchar(100) |
Billable Third Party Server |
deallineThirdPartyPSDefinitionName |
This shows which Third-Party system's data is used for Third-Party performance numbers. A Sales user can set this on a line item. No Third-Party data appears for a line item unless this is set. |
decimal(15,4) |
Makegood Links |
makeGoodDone |
For a line item using a Makegood Line Class, this reflects the Makegood Done field, which a Sales user can set on the Advanced Edit pane on the digital Workspace of a deal. The Sales user can set this to one or more IDs for other Deal Lines on any deal with the same advertiser. When there is more than one ID set in Sales, they are separated by a semicolon in the Finance export. |
Each ID is no more than 25 characters. varchar(255) is probably safe depending in your usage patterns. |
Line Class |
deallineClassName |
This is the line class that can determine if a line is a bonus, makegood, or regular line. The actual names are configurable in the System Configuration module. Based on how the line class is configured within the System Configuration module, it may always show the Net Cost as zero. A user chooses this on a line item within Sales. |
decimal(15,4) |
Makegood |
makegood |
This shows if the line item is a makegood. The system does not calculate amounts for makegood lines, but it does calculate units and revenue. This is based on the Line Class and reflects its Makegood checkbox in the System Configuration module when the deal went active. |
boolean |
ADU |
adu |
This shows if the line item is a ADU (Audience Deficienty Units). The system does not calculate either amounts or revenue for ADU lines. This is based on the Line Class and reflects its ADU checkbox in the System Configuration module when the deal went active. |
boolean |
Bonus |
bonus |
This shows if the line item is a Bonus (Added Value). The system does not calculate either amounts or revenue for bonus lines. This is based on the Line Class and reflects its Bonus checkbox in the System Configuration module when the deal went active. |
boolean |
Can Invoice |
canInvoice |
This is always True unless you are reviewing a child line item within a package that is not directly billed. Those Can Invoice False records only appear in special invoice exports that expose additional package details. |
boolean |
Line Item Total Discounts |
deallineTotalDiscount |
This is the total discount % as it was set on a line item’s pricing tab. Discounts are set at the line item level and how they apply depends on the discount profile configured in the System Configuration module. This is expressed as a % value rather than a decimal. For example, 10% appears as 10 instead of .1. |
decimal(15,4) |
Line Item Production Buffer |
deallineProductionBuffer |
This is the Production Buffer percentage as it appears for the line item in Sales. It reflects the variation between the Quantity and Production Quantity in the Sales module. |
decimal(15,4) |
Line Item Production Quantity |
deallineProductionQuantity |
This is the Production Quantity from the line item, which can be different than the Quantity in some cases. The Quantity is the number used by Finance and the Production Quantity is the number you actually traffic. In some cases, it is necessary to traffic a higher buffered number to ensure an actual Quantity goal is met. |
bigint(20) |
Line Item Value |
deallineValue |
This is typically the same as the Net Cost, but for Makegood or Bonus lines when the Net Cost is zero, this shows what the Net Cost would have been if the line was not a Makegood or Bonus. The Line Class can set whether the line is a Makegood or Bonus depending on how the Line Class is configured in the System Configuration module. |
decimal(15,4) |
Station |
station.stationMarketName |
This shows the Station and Market as they appears within the Invoices UI. In addition to this field, a custom export can also include additional details about the station if they are populated within the System Configuration module (MRD). However, the System Configuration module (MRD) does not always populate them as expected. The following keys are supported:
|
varchar(100) |
Sales Targeting |
salesTargetingSummary |
This is a string showing details about the targets set in the Sales module in the form:
Note: Embedded targets are in the Product Embedded Targeting field instead. |
Text (This is variable length and there is effectively no limit. It will concatenate as much targeting as is set on the line.) |
Product Embedded Targeting |
productEmbeddedTargettingSummary |
This is a string showing details about the targets embedded in the product from the Product module in the form:
Note: This reflects the product's targeting at the time the line item was created and NOT the current published state. The other product related field reflect current published state or for unpublished products, the current state. |
Text (This is variable length and there is effectively no limit. It will concatenate as much targeting as is set on the product.) |
Package Type |
deallinePackageType |
This is the package type (group type) for a line item that is the parent or child within a package product. For example:
Information on packages is in the Products module documentation. |
varchar(25) |
Standard or Package |
deallineItemType |
This shows if the invoice line corresponds directly to a package or not. It can be one of the following values:
|
varchar(25) |
Internal Product ID |
internalProductID |
This is a unique internal string for the Product ID that appears with the API and data stream. When billing a package parent line, this reflects the package. |
12-byte hexadecimal or use string (e.g., varchar(50)) |
Product ID |
deallineProductId |
This is the unique integer for the product as it appears within the Products module. When billing a package parent line, this reflects the package. |
bigint(20) |
Product Name |
deallineProductName |
This is the name of the line item’s product. When billing a package parent line, this reflects the package. |
varchar(250) |
Internal Package ID |
internalPackageID |
When billing a package parent line or when a line is within a package, this is a unique internal string for the Package ID that appears with the API and data stream. |
12-byte hexadecimal or use string (e.g., varchar(50)) |
Package ID |
packageID |
When billing a package parent line or when a line is within a package, this is the unique integer for the package as it appears within the Products module. |
bigint(20) |
Package Name |
packageName |
When billing a package parent line or when a line is within a package, this is the name of the line item’s package. |
varchar(250) |
Internal Parent Line Item ID |
internalParentLineItemID |
When a line is a child within a package, this is a unique internal string for the parent line item ID that appears with the API and data stream. |
12-byte hexadecimal or use string (e.g., varchar(50)) |
Parent Line Item ID |
parentLineItemID |
When a line is a child within a package, this is the Line Item ID for its parent. |
bigint |
Parent Line Item Number |
parentLineItemNumber |
When a line is a child within a package, this is the Line Item Number of its parent line item. |
decimal(10,4) |
Parent Line Item Name |
parentLineItemName |
When a line is a child within a package, this is the name of the parent line item. |
varchar(250) |
Product Tags |
productTagNames |
This shows the product tags set in the Products module. |
Text (This is variable length and will concatenate the multi-select field from the product.) |
Product Billing ID |
productBillingId |
This shows the Billing ID from the Finance Settings pane in the Products module. |
varchar(255) |
Product Category |
productCategoryNames |
This shows the Product Categories set in the Products module. |
Text (This is variable length and will concatenate the multi-select field from the product.) |
Product Genre |
productGenreNames |
This shows the Genres chosen in the Products module. |
Text (This is variable length and will concatenate the multi-select field from the product.) |
Product Forecast Category |
productOperativeForecastCategoryName |
This is the Forecast Category field as was set in the Products module. |
varchar(100) |
Product External Forecast Category |
productExternalForecastCategoryName |
This is the External Forecast Category field as it was set in the Products module. |
varchar(100) |
Product Type |
productType |
At this time, this always says DIGITAL. However, in the future, it will also support LINEAR. |
varchar(50) |
Product Template |
productTemplateName |
This is the Template that defines which fields appear within the Product module itself. It is NOT the Targeting Template. In many environments, this will always say Digital, but if users choose a different name from a Template drop-down list when they first enter the Product module, this reflects that choice. |
varchar(100) |
Creative Specifications |
productCreativeSpecProfileName |
This is the Creative Specifications set on the product. |
varchar(100) |
Note: Product attributes are not frozen to reflect the deal at the time it went active and reflect the data within the Product module in the Published or Unpublished status with the exception of embedded targeting. Embedded targeting reflects what Sales sends to Orders. For cases where a parent package is billed, most fields reflect the package details. The child details are not aggregated into the parent in any of these fields. For example, the tags for the package parent reflect the tags that show when you open that package in the Product module. They will not automatically include the tags of the children.
Invoice Fields
The following fields appear for Invoice level data. These fields will repeat across all rows for all invoice lines in the same invoice.
Default Header |
Internal Key |
Description |
Type |
---|---|---|---|
Invoice ID |
invoiceId |
This is the unique invoice integer ID key for the invoice. |
bigint(20) |
Invoice Name |
invoiceName |
This is the invoice name, which is typically in the form: Deal_Name - Billing_Period_Name |
varchar(300) |
Total Net Invoice Amount |
totalNetInvoiceAmount |
This is the sum of the Net Invoice Amount for all invoice lines within the same invoice. It includes adjustments if any are applied. |
decimal(15,4) |
Total Net Invoice Amount Adjustment |
totalInvoiceAmountAdjustments |
This is the sum of all Net Invoice Amount Adjustments across all lines in the invoice. |
decimal(15,4) |
Total Gross Invoice Amount |
totalGrossInvoiceAmount |
This is the sum of the Adjusted Gross Invoice Amount for all invoice lines within the same invoice. It includes adjustments if any are applied. |
decimal(15,4) |
Total Gross Invoice Amount Adjustment |
totalGrossInvoiceAmountAdjustments |
This is the sum of all Gross Invoice Amount Adjustments across all lines in the invoice. A user cannot enter a gross adjustment but one is calculated based on any Net Invoice Amount Adjustment. |
decimal(15,4) |
Total Gross Less Net |
totalGrossLessNet |
This shows the difference between the Total Gross Invoice Amount and Total Net Invoice Amount at the invoice level. Depending on how your discount profiles are set up, this may be considered the Total Agency Discount and the column header can be renamed on request if needed. |
decimal(15,4) |
Total Recognized Revenue |
totalRecognizedRevenue |
This is the sum of the Recognized Revenue for all invoice lines within the same invoice. It includes adjustments if any are applied. |
decimal(15,4) |
Total Recognized Revenue Adjustment |
totalRecognizedRevenueAdjustments |
This is the sum of all Recognized Revenue Adjustments across all lines in the invoice. |
decimal(15,4) |
Total Invoice Units |
totalInvoiceUnits |
This is the sum of the Invoice Units for all invoice lines within the same invoice, regardless of unit types. This may not make sense for deals that sell a mix of different units (impressions, clicks, flat rate lines, etc.). It includes adjustments if any are applied. |
bigint(20) |
Total Invoice Units Adjustment |
totalInvoiceUnitsAdjustments |
This is the sum of all Invoice Units Adjustments across all lines in the invoice. |
bigint(20) |
Lock Status |
lockStatus |
This is the lock status of the invoice which can be one of the following:
|
varchar(25) |
First Lock Date |
firstLockDate |
This is the date and time when the invoice was first locked. This is never updated if the invoice is unlocked and then locked again. It shows in the time zone of the user who triggered the export. |
timestamp |
Latest Lock Date |
lastLockDate |
This is the date and time when the invoice was last locked. If the invoice is only locked one time, it matches the First Lock Date. It shows in the time zone of the user who triggered the export. |
timestamp |
First Lock User |
firstLockUser |
This is the user login of the user who first locked the invoice. |
varchar(50) |
Latest Lock User |
lastLockUser |
This is the user login of the user who last locked the invoice. |
varchar(50) |
Billing Period Name |
billingPeriodDisplayName |
This is the Billing Period Name within the calendar. |
varchar(100) |
Billing Period Start Date |
billingPeriodStartDate |
This is the Start Date for the Billing Period. |
date |
Billing Period End Date |
billingPeriodEndDate |
This is the End Date for the Billing Period. |
date |
Invoice Status |
invoiceStatus |
This is the Finance workflow status that can be set in a number of different ways depending on how your system is configured. |
varchar(100) |
Processed Date |
processedDate |
If you use the Invoice Pull operation to have AOS import information from your Financial System after exporting, this shows the Process Date set by the Financial System. |
timestamp |
Export Process Details |
exportProcessDetails |
If you use the Invoice Pull operation to have AOS import information from your Financial System after exporting, this shows any details sent from that system back into AOS, up to 255 characters. |
varchar(255) |
Payment Amount |
paymentAmount |
If you use the Invoice Pull operation to have AOS import information from your Financial System after exporting, this shows any payment amount sent from that system back into AOS, as a monetary value up to four decimal places. |
decimal(15,2) |
Invoice Start Date |
invoiceStartDate |
This shows the first date for the invoice, which can be later than the Billing Period Start Date if the earliest line item starts after the period begins. |
date |
Invoice End Date |
invoiceEndDate |
This shows the last date for the invoice, which can be earlier than the Billing Period End Date if the latest line item ends before the period ends. |
date |
First Exported Date |
firstExportedDate |
This shows the date and time when the specific invoice was exported to a financial system. This is stored by AOS after the invoice is first exported to a financial system. Therefore, it will not have a value in that first export file. |
timestamp |
First Exported By |
firstExportedBy |
This shows the login of the user who first triggered the export to a financial system. This is stored by AOS after the invoice is first exported to a financial system. Therefore, it will not have a value in that first export file. |
varchar(50) |
Previous Exported Date |
lastExportedDate |
This shows the date and time when the specific invoice was last exported to a financial system. This is stored by AOS after the invoice is exported to a financial system. Therefore, it will not reflect the date and time of that export itself. The date and time of that export itself are available as the Export Time, which has a common value across all rows. The actual time stamp for export is also reflected in the file name using a common UTC time zone. |
timestamp |
Previous Exported By |
lastExportedBy |
This shows the login of the user who last triggered the export to a financial system. This is stored by AOS after the invoice is exported to a financial system. Therefore, it will not reflect the user exporting the invoice itself. The Export User field reflects the export itself. This shows the Latest Export Date from the Invoices Grid at the time the export is requested, which can change when the export completes. |
varchar(50) |
Number of Previous Exports |
totalExportCount |
This is a count of the number of times an invoice was previously exported to a Financial System. This is incremented by AOS after the invoice is exported to a financial system. |
int(11) |
Assignees |
assignedUsers |
This shows the first and last names of users assigned to an invoice. Multiple users are separated by semicolons. |
String. This concatenates if there are multiple users. A single contact will not exceed 101 characters, but this can contain n users. Practically speaking this is unlikely to exceed 400 to 1000 characters |
Finance Team |
assignedTeam |
This is an invoice specific Finance Team that can vary from the Sales team depending on the needs of your Finance department. By defaults, it is the same as the Sales Team. However, assignment rules or manual selection within the Finance module can set a separate team per invoice. |
varchar(50) |
Invoice Line Fields
The following fields appear for the Invoice line-level data, which represent the majority of data originating within the Finance module.
Default Header |
Internal Key |
Description |
Type |
---|---|---|---|
Invoice Line ID |
invoiceLineId |
This is the unique integer ID key for the invoice line item, representing the portion of the deal line within the invoice. If the export includes Can Invoice False child lines, then for those child rows, this is the Invoice Line ID of the parent line that is Can Invoice True and not a unique key. |
bigint(20) |
Invoice Line Start Date |
invoiceObjectStartDate |
This is the earliest date that the line item runs within the invoice. It is calculated as: IF Line Item Start Date > Invoice Start Date THEN Line Item Start Date ELSE Invoice Start Date |
date |
Invoice Line End Date |
invoiceObjectEndDate |
This is the latest date that the line item runs within the invoice. It is calculated as: IF Line Item End Date < Invoice End Date THEN Line Item End Date ELSE Invoice End Date |
date |
CLI Units Ratio |
invoiceUnitsRatio |
By default, this is empty unless you enable the Non-Invoice CLIs feature for the export template. When Can Invoice=False, this can contain the ratio reflecting the child's weight in its package's Invoice Units. This is multiplied against the parent Invoice Units to derive the child value. |
decimal(9,8) |
CLI Uncapped Invoice Units |
uncappedInvoicUnits |
This shows the units used to calculate the CLI Units Ratio within the package. It only has a value for Can Invoice False lines within packages with the Non-Invoice CLIs feature. |
bigint(20) |
Adjustment Category |
categoryName |
This is the predefined category for why an adjustment is made. Administrators define the categories in the System Configuration module under System Configuration > System > Finance Adjustment Category. |
varchar(255) |
Adjustment Comments |
adjustmentComments |
This is a free text description about the adjustment. |
varchar(255) |
Last Adjusted By |
lastAdjustedBy |
This shows the login of the user who last saved an adjustment number, category, or comment. |
varchar(125) |
Last Adjusted Date |
lastAdjustedDate |
This shows the most recent date when a user saved an adjustment number, category, or comment. |
date time |
Invoice Units |
units |
This is the quantity you show on the invoice based on the Invoice Terms and Unit Type. |
bigint(20) |
Invoice Units Adjustment |
invoiceUnitsAdjustment |
This is a positive or negative whole number that is the adjustment to apply to the Invoice Units. |
bigint(20) |
Adjusted Invoice Units |
adjustedInvoiceUnits |
This is:
|
bigint(20) |
Cumulative Invoice Units |
cumulativeInvoiceUnits |
This is the total Invoice Units for the deal line up to and including the row’s invoice. It is the sum of the row’s Invoice Units plus those for any invoice lines for the same deal line for billing periods earlier than that period. For example, if the line item runs from July through December and the row’s invoice line is for September, it reflects July, August, and September. It includes adjustments if any are applied. |
bigint(20) |
CLI Amount Ratio |
netInvoiceAmountRatio |
By default, this is empty unless you enable the Non-Invoice CLIs feature for the export template. When Can Invoice=False, this can contain the ratio reflecting the child's weight in its package's Net Invoice Amount. This is multiplied against the parent Net Invoice Amount and Gross Invoice Amount to derive the child values. |
decimal(9,8) |
Invoice Amount without Discounts |
amountBeforeDiscount |
This converts the Net Invoice Amount to reflect a value without any discounts applied using the ratio of Net Unit Cost to Unit Cost Before Discounts (UCBD):
At this time, this field is calculated by the export itself, so is not available within the user interface. Cumulative and invoice total versions of this field are also not available. This field has no value when there are no Unit Costs available, such as when packages have the Various Cost Method. |
decimal(15,4) |
Gross Invoice Amount |
grossInvoiceAmt |
This is the gross value for how much you bill. How this calculates depends on the Amount Terms. If the Amount Terms are NOT Manual, then it uses the same calculation as the Net Invoice Amount but substitutes the Line Item Gross Unit Cost for the Line Item Net Unit Cost and substitutes the Gross Cost for the Net Cost to determine the cap. However, if the Amount Terms are Manual, the system calculates the Gross Invoice Amount using a ratio applied to the Net Invoice Amount:
|
decimal(15,4) |
Gross Invoice Amount Adjustment |
grossAdjustment |
A Gross Invoice Amount Adjustment is calculated whenever there is a Net Invoice Amount Adjustment as:
However, if Unit Costs are zero then Gross Cost and Net Cost are used, which is the case for a Package with the Various Cost Method. |
decimal(15,4) |
Adjusted Gross Invoice Amount |
adjustedGross |
This is calculated as: Gross Invoice Amount + Gross Invoice Amount Adjustment |
decimal(15,4) |
Cumulative Gross Invoice Amount |
cumulativeGrossInvoiceAmount |
This is the sum of the row’s Gross Invoice Amount plus those for any invoice lines for the same deal line for billing periods earlier than that period. For example, if the line item runs from July through December and the row’s invoice line is for September, it reflects July, August, and September. It includes adjustments if any are applied. |
decimal(15,4) |
CLI Uncapped Net Invoice Amount |
uncappedNetInvoiceamount |
This shows the monetary value used to calculate the CLI Amount Ratio within the package. It only has a value for Can Invoice False lines within packages with the Non-Invoice CLIs feature. |
decimal(15,4) |
Net Invoice Amount |
amount |
This is the monetary value you bill the customer on the invoice based on the Invoice Terms. |
decimal(15,4) |
Net Invoice Amount Adjustment |
invoiceAmountAdjustment |
This is a positive or negative number that is the adjustment to apply to the Net Invoice Amount. > |
decimal(15,4) |
Adjusted Net Invoice Amount |
adjustedInvoiceAmount |
This is calculated as:
|
decimal(15,4) |
Cumulative Net Invoice Amount |
cumulativeNetInvoiceAmount |
This is the total Net Invoice Amount for the deal line up to and including the row’s invoice. It is the sum of the row’s Net Invoice Amount plus those for any invoice lines for the same deal line for billing periods earlier than that period. For example, if the line item runs from July through December and the row’s invoice line is for September, it reflects July, August, and September. It includes adjustments if any are applied. |
decimal(15,4) |
Gross Less Net |
grossLessNet |
This shows the difference between the Gross Invoice Amount and Net Invoice Amount at the invoice line level. Depending on how your discount profiles are set up, this may be considered the Agency Discount and the column header can be renamed on request if needed. |
decimal(15,4) |
CLI Revenue Ratio |
recognizedRevenueRatio |
By default, this is empty unless you enable the Non-Invoice CLIs feature for the export template. When Can Invoice=False, this can contain the ratio reflecting the child's weight in its package's Recognized Revenue. This is multiplied against the parent Recognized Revenue derive the child value. |
decimal(9,8) |
CLI Uncapped Recognized Revenue |
uncappedRecognizedRevenue |
This shows the monetary value used to calculate the CLI Revenue Ratio within the package. It only has a value for Can Invoice False lines within packages with the Non-Invoice CLIs feature. |
decimal(15,4) |
Recognized Revenue |
recognizedRevenue |
This is the monetary value you internally recognize as revenue for the invoice based on the Invoice Terms. |
decimal(15,4) |
Recognized Revenue Adjustment |
recognizedRevenueAdjustment |
This is a positive or negative number that is applied to the Recognized Revenue as an adjustment. |
decimal(15,4) |
Adjusted Recognized Revenue |
adjustedRecognizedRevenue |
This is:
|
decimal(15,4) |
Cumulative Recognized Revenue |
cumulativeRecognizedRevenue |
This is the total Recognized Revenue for the deal line up to and including the row’s invoice. It is the sum of the Recognized Revenue plus those for any invoice lines for the same deal line for billing periods earlier than that period. For example, if the line item runs from July through December and the row’s invoice line is for September, it reflects July, August, and September. It includes adjustments if any are applied. |
decimal(15,4) |
Primary Performance |
primaryPerformance |
This is the uncapped delivery data for the invoice line’s dates from the first-party publisher system when available within AOS. |
bigint(20) |
Primary Gross |
primaryGross |
This reflects Gross Unit Cost applied to Primary Performance without capping. It is not calculated when the Cost Method is Flat Rate or SOV Flat Rate or for a Makegood, Bonus, or ADU line. |
decimal(15,4) |
Primary Net |
primaryAmount |
This reflects Net Unit Cost applied to Primary Performance without capping. It is not calculated when the Cost Method is Flat Rate or SOV Flat Rate or for a Makegood, Bonus, or ADU line. |
decimal(15,4) |
Third Party Performance |
thirdPartyPerformanceNumber |
This is the uncapped delivery data for the invoice line’s dates from the deal line’s Billable Third-Party Server when that data is available within AOS. |
bigint(20) |
Third Party Gross |
thirdPartyGross |
This reflects Gross Unit Cost applied to Third Party Performance Delivery without capping. It is not calculated when the Cost Method is Flat Rate or SOV Flat Rate or for a Makegood, Bonus, or ADU line. |
decimal(15,4) |
Third Party Net |
thirdPartyAmount |
This reflects Net Unit Cost applied to Third Party Performance Delivery without capping. It is not calculated when the Cost Method is Flat Rate or SOV Flat Rate or for a Makegood, Bonus, or ADU line. |
decimal(15,4) |
Performance Discrepancy |
performanceDiscrepancy |
This shows the difference between Primary and Third-Party Performance during the row’s period, calculated as.
|
bigint(20) |
Performance Discrepancy Percentage |
discrepancyPercent |
This is the percentage discrepancy between Primary and Third-Party Performance during the row’s period, calculated as:
However, if one of the two performance numbers is zero and the other is not zero, this is always 100% discrepant. If neither has delivery, this is always zero. |
decimal(15,6) |
Cumulative Primary Performance |
cumulativePrimaryPerformance |
This is the uncapped Primary Performance for the deal line up to and including the row’s invoice. |
bigint(20) |
Cumulative Third Party Performance |
cumulativeThirdPartyPerformance |
This is the uncapped Third-Party Performance for the deal line up to and including the row’s invoice. |
bigint(20) |
Cumulative Performance Discrepancy |
cumulativePerformanceDiscrepancy |
This shows the difference between Cumulative Primary and Third-Party Performance for the row’s period and all previous periods, calculated as:
|
bigint(20) |
Cumulative Performance Discrepancy Percentage |
cumulativePerformanceDiscrepancyPercentage |
This is the percentage discrepancy between Cumulative Primary and Third-Party Performance, calculated as:
If both are 0, it will be 0%. If only Primary is 0, it is 100%. |
decimal(15,6) |
Remaining Amount |
remainingInvoiceAmount |
This is calculated as:
|
decimal(15,4) |
Remaining Units |
remainingInvoiceUnits |
This is calculated as:
|
bigint(20) |
Unrecognized Revenue |
unrecognizedRevenue |
This is calculated as:
|
decimal(15,4) |
Deferred Revenue |
cumulativeDeferredRevenue |
This is calculated as:
|
decimal(15,4) |
Actual Invoice Units Term Source |
unitSource |
This shows how Invoice Units derived their Invoice Terms. It is one of the following:
|
varchar(50) |
Actual Invoice Units Term Used |
unitTermApplied |
This shows which Invoice Terms were used to calculate the Invoice Units for the row. |
varchar(50) |
Actual Net Invoice Amount Term Source |
amountSource |
This shows how Net Invoice Amount derived its Invoice Terms. It is one of the following:
|
varchar(50) |
Actual Net Invoice Amount Term Used |
amountTermApplied |
This shows which Invoice Terms were used to calculate the Net Invoice Amount for the row. |
varchar(50) |
Actual Revenue Recognition Term Source |
recognizedRevenueSource |
This shows how the Recognized Revenue derived its Invoice Terms. It is one of the following:
|
varchar(50) |
Actual Revenue Recognition Term Used |
recognizedRevenueTermApplied |
This shows which Invoice Terms were used to calculate the Recognized Revenue for the row. |
varchar(50) |
Suggested Invoice Amount |
suggestedAmount |
For contracted terms (prorated or straightline), this is the contracted amount for the period, which matches the Net Invoice Amount unless values were manually changed within the Finance module. This has no value for performance terms. |
decimal(15,4) |
Cumulative Suggested Invoice Amount |
cumulativeSuggestedAmount |
For contracted terms (prorated or straightline), this is the contracted amount for the period and any earlier ones, which matches the Cumulative Net Invoice Amount unless values were manually changed within the Finance module. This has no value for performance terms or for non-invoice child lines. |
decimal(15,4) |
Suggested Amount Terms |
suggestedAmountTerm |
This shows the Invoice Terms that appeared on the Finance Summary tab in Sales when the deal last went active. It lets you review the terms that were sold in comparison with the Actual Net Invoice Amount Term Used. For non-invoice child lines, it reflects the parent terms. |
varchar(50) |
Suggested Invoice Units |
suggestedUnits |
For contracted terms (prorated or straightline), these are the contracted units for the period, which matches Invoice Units unless values were manually changed within the Finance module. This has no value for performance terms. |
bigint(20) |
Cumulative Suggested Invoice Units |
cumulativeSuggestedUnits |
For contracted terms (prorated or straightline), these are the contracted units for the period and any earlier periods, which matches Cumulative Invoice Units unless values were manually changed within the Finance module. This has no value for performance terms or for non-invoice child lines. |
bigint(20) |
Suggested Unit Terms |
suggestedUnitTerm |
This shows the Invoice Terms that appeared on the Finance Summary tab in Sales when the deal last went active. It lets you review the terms that were sold in comparison with the Actual Invoice Unit Term Used. For non-invoice child lines, it reflects the parent terms. |
varchar(50) |
Comments |
invoiceObjectComments |
This supports up to 255 characters of free text that a Finance user can optionally leave for other users to see or for exporting with the lines. When an invoice is locked, if you use adjustments, you can use the Adjustment Comments field instead. |
varchar(255) |
Last Billing Period |
lastBillingPeriod |
This is a Boolean flag reflecting whether the row is the last invoice line for a deal line.
|
boolean |
Export Meta Data
The following fields are the same for all rows and relate to the export action itself.
Default Header |
Internal Key |
Description |
Type |
---|---|---|---|
Export Time |
exportTime |
This is the time when the invoice export was requested. This may not exactly match the Last Export Date that appears on the Invoices Grid. The Last Export Date within the interface is only saved on to the invoice when exporting to a Financial System. Also, the Last Export Date is written during the export process, but the export time stamp within the Export itself is based on when that process began. This shows in the time zone of the user who triggered the export. This can also be derived from the file name, so you do not really need to include it in the export unless you cannot derive it. |
timestamp |
Export User |
exportUser |
This is the login of the user who requested the export. It does not get saved onto the invoice, does not appear in the interface, and is written directly onto the export file |
varchar(50) |
Custom Fields
In addition to the system fields, Operative can configure custom fields. These are the fields that appear on the Deal Header that correspond to the fields within the System Configuration module under Targets & Custom Fields > Custom Fields. You need to identify the Fixed Names for the custom fields you want to appear in the export from the Custom Fields page in the System Configuration module. Operative can then use that to configure the specific fields. You need to specify which custom fields you wish to appear and where within the file you want them to appear. The system does not dynamically add custom fields to the export. The column and headers are always a fixed structure.
Custom fields for the following can be added to the export on request:
-
Deal (Deal Header): These are the fields configured with Object=PLAN in the System Configuration module. These reflect the custom field at the time the deal last went active.
-
Deal Line Items: These are the fields configured with Object=PLANLINE in the System Configuration module. These reflect the custom field at the time the deal line item last went active.
-
Products or Packages: For products, these have Object=PRODUCT, and for packages, they show PRODUCT_GROUP. Product and package custom fields reflect the current published or unpublished state of the product and are not frozen with the deal when it goes active or an invoice is locked. A package custom field is only used when a package is Can Invoice=True. For packages, custom fields are only those set explicitly on the package itself and not an aggregation of its children.
-
Billing Account: For advertisers, these have Object=ADVERTISER, and for agencies, they show AGENCY. When billing the agency, they come from the agency. When billing an advertiser directly, they come from the advertiser. The custom field values reflect how they appear within the Master Data Management (MDM) module at the time of the export. They are not frozen at the time the deal moved through the Sales workflow nor when an invoice is locked.
To add custom fields to an export, you must open a support ticket and tell Operative support each custom field's Fixed Name as it appears in the System Configuration module. Support can then adjust the template on the backend using the details below:
-
Deal custom fields are specified in the export format template using:
dealCustomFieldValues.<FixedName>
For example, if a text custom field has the Fixed Name dealHeaderNotes:
dealCustomFieldValues.dealHeaderNotes
-
Deal Line Items custom fields are specified in the export format template using:
deallineCustomFieldValues.<FixedName>
For example, if a text custom field has the Fixed Name lineNotes:
deallineCustomFieldValues.lineNotes
-
Product/Pacakge are specified in the export format template using:
deallineProductCustomFields.<FixedName>
For example, if a text custom field has the Fixed Name productNotes:
deallineProductCustomFields.productNotes
-
Billing Account custom fields are specified in the export format template using:
billingAccountCustomFields.<FixedName>
For example, if a text custom field has the Fixed Name accountNotes:
billingAccountCustomFields.accountNotes
Targeting Fields
In AOS, digital targets are either:
-
Sales targets which a user can manipulate in the Sales module Target Chooser (based on the targeting templates). In the Finance export, all of these targets applied to the line appear as a single string in the Sales Targeting column (key is salesTargetingSummary).
-
Product embedded targets are set within the Product module’s Target Chooser and inherited in Sales when a line item is created. Sales users cannot manipulate them. In the Finance export, all of these targets applied to the line appear as a single string in Product Embedded Targeting column (key is productEmbeddedTargettingSummary). However, be aware that those targets reflect those at the time the line item is created and not based on the current state of the published product.
In addition to these columns that show the targets in a single field, Operative can now optionally configure any target to appear in its own column. For example, if the Sales Targeting column contains:
Day of Week=Saturday;Sunday | Countries=Belgium;Belarus;Belize | Size=970x250;300x600;728x90;1330x300 | Ad Unit= News_App > News
In custom export templates, Operative can optionally configure columns to show Day of Week, Countries, Size, and Ad Unit. For example:
These target can be configured one by one to appear anywhere in the file, you do not need to include all of them, and they do not need to appear next to each other. However, a column for a specific target always appears even when the target is not in any line items within the export. AOS does not dynamically add target columns based on the presence of values, but the AOS behavior ensures the sequence and location of columns does not vary.
To add a target on its own, open a support ticket and tell Operative the current target names. Operative must specify the target by its name in the configuration file that defines the export template. This configuration file is handled by Operative support on your behalf.
Note: If the target name changes in the System Configuration module, the export must be reconfigured
-
For Sales targets, Operative support must use:
${lineItems.salesTargets.<targetName>}
For example, for a target named Ad Unit:
${lineItems.salesTargets.Ad_Unit}
-
For Product embedded targets, Operative support uses the form:
${lineItems.embeddedTargets.<targetName>}
For example, for a target named Ad Unit:
${lineItems.embeddedTargets.Ad_Unit}
If a target is used in an Exclude context in the Target Chooser, then when it is appear in the target summary fields (Sales Targeting, Product Embedded Targeting), it has “-excluded” appended to its name. For individual target columns, targets whose names contain characters other than letters or numbers must be specified by substituting those characters with underscores.
For grouped targets, (FreeWheel) combination targets, or (GAM) Boolean Expression targets, the details appear using the same friendly syntax that appear throughout AOS. Be aware that multi-selects within these types of targets may be commas separated instead of semicolon to match their common syntax.
Discount Percentage Fields
In addition to the system fields, Operative can enable line item discount percentage fields. These are the percentage numbers that appear on the Sales Workspace on a line item’s Pricing tab in the Advanced Edit view. The values in the export are the same percentage values from the Sales module and not the monetary value they represent on the line item or invoice line. Which fields appear and when are based on the discount profile which can vary depending on how your system is configured.
You need to identify the field names as they appear within the Workspace interface, and Operative can then use that to configure the specific fields. You need to specify which discount fields you wish to appear and where within the file you want them to appear. The system does not dynamically add discounts to the export. The column and headers are always a fixed structure. If the discount field names ever change, Operative must update the export configuration.
Operative support can add the discount field to the export template pre-pended by the following:
discounts
.
For example, if the discount name is “Other”:
discounts.Other
If the discount name has a space in it, use an underscore for the space. For example, “Agency Discount” should be:
discounts.Agency_Discount
Deal Users
In the Sales module on a Deal's header, when you click the three dots next to the Primary Account Executive, you can add additional users with additional Deal Roles to the deal. The roles can be configured in the System Configuration module under Sales > Deal Roles. Operative can add columns to the Finance export for each role. When this is done, the first and last names of users having the role are shown. If more than one user has the same role, they are semicolon separated.
Operative support can add user roles to the export template by pre-pending the role name by the following:
users.
For example, if the role name is “FinanceManager”:
users.FinanceManager
If the role's name has a space in it or any character other than a letter or number, use an underscore for the space or character. For example, “Finance Manager” would be:
users.Finance_Manager
Accounts
In the Sales module on a Deal’s Accounts tab, you can add additional accounts with or without additional roles. If you want accounts other than one Advertiser, one Agency, and whichever is the Billing Account to appear in the Finance export, Operative can configure the template to show accounts based on role on the Deal's Accounts tab. A column can also show advertisers with no roles and another column can also show agencies with no roles.
Operative support can add account roles to the export template using the following details:
-
For a column based on Advertisers having a specific role use:
advertisers.<roleName>
For example, if the role is "Paying":
advertisers.Paying
-
For a column to show Advertisers without roles, use "Undefined" as the role:
advertisers.Undefined
-
For a column based on Agencies having a specific role use:
agencies.<roleName>
For example, if the role is "Paying":
agencies.Paying
-
For a column to show Agencies without roles, use "Undefined" as the role:
agencies.Undefined
If the role's name has a space in it or any character other than a letter or number, use an underscore for the space or character.
Note: Custom roles are supported but the three default roles of AOS Billing, Buying, and Paying cannot have their names changed. The Finance Sync from Sales may fail if these default role names are modified.
Account System Mapping IDs
Operative can configure some Account External IDs to appear in the export. These correspond to the External ID field that appears on an Advertiser’s or Agency’s System Mapping tab in the Master Data Management module. Within the export file’s configuration template, you need to specify the name that appears in the External System column on the System Mapping tab, and the value in the corresponding External ID column can appear in the export file. However, there can be multiple sources for the system mappings and the MDM module stores them in different ways depending on how they are added, even though they all appear in the same grid. You should confirm with Operative support whether the mapping you wish to surface is supported. Through the API, those that appear under externalSourceSystems can appear while those under psMappings cannot without additional development work as part of a future release.
This is supported for:
-
The deal’s Advertiser specified as:
externaldealAdvertiser.<ExternalSystem>
For example, if the External System name is OnAir:
externaldealAdvertiser.OnAir
-
The deal’s Agency specified as:
externaldealAgency.<ExternalSystem>
For example, if the External System name is OnAir:
externaldealAgency.OnAir
-
Whichever account is set to be billed is specified as:
externalBillableSystem.<ExternalSystem>
For example, if the External System name is OnAir:
externalBillableSystem.OnAir
If there are spaces in the system’s name, use an underscore for the space. If an External System has more than one mapping, they are concatenated.
CRM Opportunity ID
If AOS integrates with a CRM system for Opportunities created outside AOS, the Opportunity ID passed from the CRM system appears on a Deal Header next to the Order Type. The Export can contain this ID if Operative configures it for you on request. If you want this in the export, reach out to Operative with the External System name for the CRM system as defined in the System Configuration module under System > External System.
Operative will need to look up the system ID for the CRM External System.
This key is then used within the export configuration:
dealExternalId.<ExternalSystemID>
For example, if the External System ID is bFpn2iv9Tp6kOfmBlSlkmg:
dealExternalId.bFpn2iv9Tp6kOfmBlSlkmg
Note: In the Operative.One Finance Export, this field was called “Order - Opportunity External ID”.