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 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:

Graphical user interface, text, application, chat or text message

Description automatically generated

  • 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.

      Graphical user interface, text, application

Description automatically generated

      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

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

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:

Robert Smith 50.00%

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:

100.00%

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:

  • station.affiliation

  • station.comscoreCallLetter

  • station.comscoreDistributorCode

  • station.displayCallLetter

  • station.displayName

  • station.id

  • station.marketComscoreCode

  • station.marketId

  • station.marketName

  • station.marketNielsenCode

  • station.name

  • station.nielsenCallLetter

  • station.nielsenDistributorCode

varchar(100)

Sales Targeting

salesTargetingSummary

This is a string showing details about the targets set in the Sales module in the form:

target1=option1;option2 | target2=option3

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:

target1=option1;option2 | target2=option3

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:

  • BottomUp

  • TopDown

  • RunOf

  • Freeform.

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:

  • PACKAGE means the invoice line is for a parent of a package. The parent is billed. The Can Invoice box is checked in Sales for the parent.

  • STANDARD means the invoice line is not for the parent.  This can mean the line is a child within a package where that child line has its Can Invoice box checked. It can also mean the child is not part of a package at all, in which case the Package Type column is empty.

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:

  • unlocked

  • locked

  • prior_locked

  • reset

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:

Invoice Units + Invoice Units Adjustment

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):

( UCBD / Net Unit Cost ) * Net Invoice Amount

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:

(Line Item Gross Unit Cost * Net Invoice Amount)
/ Line Item Net Unit Cost

decimal(15,4)

Gross Invoice Amount Adjustment

grossAdjustment

A Gross Invoice Amount Adjustment is calculated whenever there is a Net Invoice Amount Adjustment as:

(Gross Unit Cost * Net Invoice Amount Adjustment) / Net Unit Cost

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:

Net Invoice Amount + Net Invoice Amount Adjustment

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:

Recognized Revenue + Recognized Revenue Adjustment

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.

Primary Performance

- Third-Party Performance

bigint(20)

Performance Discrepancy Percentage

discrepancyPercent

This is the percentage discrepancy  between Primary and Third-Party Performance during the row’s period, calculated as:

(( primaryPerformance  –  thirdPartyPerformance  ) / primaryPerformance ) * 100

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:

Cumulative Primary Performance - Cumulative Third-Party Performance

bigint(20)

Cumulative Performance Discrepancy Percentage

cumulativePerformanceDiscrepancyPercentage

This is the percentage discrepancy  between Cumulative Primary and Third-Party Performance, calculated as:

(Cumulative Primary Performance - Cumulative Third-Party Performance )  / Cumulative Primary Performance

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:

Line Item Net Cost – Cumulative Net Invoice Amount

decimal(15,4)

Remaining Units

remainingInvoiceUnits

This is calculated as:

Line Item Quantity – Cumulative Invoice Units

bigint(20)

Unrecognized Revenue

unrecognizedRevenue

This is calculated as:

Line Item Net Cost
– Cumulative Recognized Revenue

decimal(15,4)

Deferred Revenue

cumulativeDeferredRevenue

This is calculated as:

Cumulative Net Invoice Amount – Cumulative Recognized Revenue

decimal(15,4)

Actual Invoice Units Term Source

unitSource

This shows how Invoice Units derived their Invoice Terms. It is one of the following:

  • invoice_schedule meaning Invoice Terms were set based on the organization or a Sales user.

  • manual meaning that a Finance user either manually set a value for the Invoice Units or manually changed the Invoice Terms.

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:

  • invoice_schedule meaning Invoice Terms were set based on the organization or a Sales user.

  • manual meaning that a Finance user either manually set a value for the Net Invoice Amount or manually changed the Invoice Terms.

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:

  • invoice_org meaning Invoice Terms were set based on the organization.

  • product meaning Invoice Terms were set based on the product overrides.

  • manual meaning that a Finance user either manually set a value for the Recognized Revenue or manually changed the Invoice Terms.

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.

  • true means no invoice lines exist for the deal lines that are later in time than this row.

  • false means invoice lines exist for the same deal line for periods after this row.

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”.