Skip to main content

Common Errors and FAQs

Getting Started - Authentication​

To authorize access to read and write data between Viewpoint Spectrum and Agave, you will need to complete the following steps:

Step 1: Whitelist Static IP Addresses​

Step 1A: Hosted or Cloud Versions of Viewpoint Spectrum​

Open a case with Viewpoint Customer Support to add Agave's IP address to your Viewpoint Spectrum Endpoint IP whitelist:

  1. Go to https://support.viewpoint.com/s/
  2. Log in to your Customer Support account.
  3. Select My Resources, then Submit a Case.
  1. Select Support, then Systems/IT
  1. Under Which product are you using?, input the following and select Search Knowledge Base:
  • Product: select Spectrum.
  • Version: select the version of your Spectrum instance (e.g. 2022 R3).
  • Module: select "SDX - Data Exchange - Spectrum".
  • Brief Summary: input "Endpoint IP Whitelist".

  1. Scroll to the bottom of the page and press Continue to Case Creation.

  2. Under Case Create, select a Priority. Under Description, add the following:

Hi - we are looking to whitelist our IPs for Spectrum Endpoint connectivity with our Spectrum instance. Here are our static IPs:

  1. 13.58.14.240
  2. 18.219.160.98
  3. 3.143.37.24

Could you also let us know what the database hostname (xyz-data.dexterchaney.com), database name (Spectrum_00xxxxx), and port are for our instance?

  1. Press Submit.

  2. After submitting a case, you should receive a response from Viewpoint Support within 24-48 hours confirming that the IP addresses have been whitelisted.

Step 1B: On-premise Versions of Viewpoint Spectrum​

If you are on an on-premise version of Viewpoint Spectrum, you will need the following three static IP addresses to connect to your SQL server by adding them to your firewall for your network:

  1. 13.58.14.240
  2. 18.219.160.98
  3. 3.143.37.24
note

If you are unable to authenticate with Agave Link even after adding the above static IP addresses, we recommend following our guide on troubleshooting common issues with on-premise connections.

Step 2: Create Authorization ID​

The next step is to configure an Authorization ID and enable required the Web Services in Spectrum. Agave uses the Web Services to write data back to Spectrum.

To enable Web Services:

  1. Login to your Viewpoint Spectrum account.
  2. Press the + at the top of the page.
  3. Select System Administration, then Installation, then Data Exchange.
  1. In Data Exchange screen, select New.

  1. Input a name for the Authorization ID (e.g. "Agave").

  2. Select a Company Code and Operator Code for the Authorization ID, and select Active for Status.

  1. Add a Memo for the Authorization ID (e.g. "Access for Agave").

  2. Select Build. Then select the relevant Web Services you are looking to support for the integration. For example, the below authorizes access to retrieve details about Jobs from the Job Cost module.

When creating an Authorization ID, you will need to enable the following Web Services for the corresponding Agave endpoint you plan to use:

DataServiceWeb Service(s)
AP InvoicesAccountsPayableAddAPInvoice, APMultiLineInvoice
AR InvoicesAccountsReceivableAddARInvoice, ARMultiLineInvoice
AR PaymentsAccountsReceivableAdd_CashReceipts
Budget Line ItemsJobCostAddPhase, GetPhase, GetPhaseEnhanced, PhaseNotes
Change OrdersAccountsReceivableARChangeRequest, ARChngReqBlankBIUpdate
CustomersAccountsReceivableAddCustomer, CustomerNotes, CustomerBillto, CustomerShipto, GetCustomers
EmployeesPayrollGetEmployee, EmployeeNotes
InventoryInventoryAddInv_Req,UpdateInv_SellPrice
Prime ContractsAccountsReceivableARScheduleOfValues
ProjectsJobCostAddJob, GetJob, GetJobContact, GetJobDates, GetJobMain, UpdateJob
Purchase OrdersPurchaseOrderPOBatch, PODetail, POHeader
Service SitesWorkOrderAddWOSiteAddress
SubcontractsAccountsPayableUpdateSubcontract, UpdateSubcontractPhases, SubcontractNotes
Timecard EntriesPayrollPreTimeCard_Batch
VendorsAccountsPayableAddVendor, GetVendors, UpdateVendor, UpdateVendor_Locations, VendorNotes
Work OrdersWorkOrderWorkOrderHeader
caution

Make sure you always add the GetJobMain Web Service under the JobCost Service. We use this endpoint to confirm the customer's Spectrum account has linked successfully.

This section is under construction. Please check back later for updates.

  1. Select OK.

Agave Sync uses Spectrum's Info-Link module to read records from Spectrum to your PM System.

You will need to create an Info-Link user, and provision them access to specific Viewpoint Spectrum tables which are grouped into "Categories".

To enable an Info-Link user:

  1. Login to your Viewpoint Spectrum account.
  2. Press the + at the top of the page.
  3. Select System Administration, then Installation, then Info-Link.
  1. Continue to press "Reset" until the User ID for Info-Link is incremented at least twice. For example, if you started at "INFO0001", it should now be "INFO0003". Then press Save.
note

Spectrum needs to be refreshed to connect with Agave. This will not reset your existing info link connections
  1. Return to the Site Map. Select Info-link, then Table Categories Maintenance.
  1. Select New, and add a Table Category and Description. You can create these Categories however you see fit. If you would like to keep it simple, we recommend creating one Table Category:
caution

Make sure you have followed step 4 above to ensure the User ID for Info-Link has been incremented at least twice before continuing.

  1. Return to the Site Map. Select Info-link, then Table Security Maintenance.

  2. Select New, and add the names of Tables for which you want to support read or write requests. Note, we recommend setting Read or Write Access to "9", unless you have more granular security permissions.

caution

Make sure you add the JC_JOB_MASTER_MC and VN_VENDOR_MASTER_MC tables. You will also need VN_VENDOR_MASTER_MC and VN_VENDOR_CONTACT_DETAIL. These are the default tables we check to confirm your Spectrum account has linked successfully.

If you use Cost Centers, you will also need to add EM_COST_CENTERS_MC.

For reference, here are links to the sections on each Info-Link table you will need:

note

You only need to enable Info-Link tables for records you plan to sync.

For example, adding the below Tables adds support for reading AP Invoice Header and Line Item Tables:

  1. Select Update Database.

  2. Return to the Site Map. Select Info-link, then User Security Maintenance.

  3. Select New, then select a Company. Either add an existing Database user by selecting from the drop-down or type in a new Database user. If it's a new Database user, press the "Enter" (or "Return") key, and input a Password. The select the Table Category.

caution

Make sure you have followed step 4 above to ensure the User ID for Info-Link has been incremented at least twice before continuing.

Make sure the Link User you create is uniquely named across Viewpoint Spectrum Companies, otherwise you might run into database validation issues. If you have any concerns, feel free to contact us at support@agaveapi.com.
  1. Select Update Database.

Once you have completed the above steps, let your Agave Account Manager know and you will be able to authenticate Agave with Spectrum.

General Errors​

Locked Tables​

You may encounter an error like the following when attempting to sync a record (e.g. a Purchase Order):

Spectrum Locked Tables

This error is from another Viewpoint Spectrum User having a window with this record open, which causes the table for the record to be locked.

To unlock the table:

  1. From the Sitemap, go to System Administration-->Utilities-->View Locked Database Tables:

Spectrum Locked Tables
  1. Here you can see a list of locked tables. You can either email the Spectrum User that has locked the table, or alternatively press Remove Session:

Spectrum Locked Tables
  1. If you selected Remove Session, input the Session ID and press OK:

Spectrum Locked Tables
  1. A window will appear confirming you have removed the session. Returning to the View Locked Database Tables page will show no sessions.

Spectrum Locked Tables

Spectrum Locked Tables

500 Internal Server Error​

You may encounter an error like the following when attempting to sync a record for the first time: 500 Internal Server Error: {"code":500,"message":"There was an error processing your request.

This issue only applies to Spectrum instances that were set up before November 2020. Newer installations should have the correct configuration from the start.

To resolve this issue:

  1. From the sitemap, go to Enterprise Management-->Maintenance-->Enterprise Installation:

Spectrum Locked Tables
  1. Select the Company tab. If your Company Code does not appear there, press Add Company.

Spectrum Locked Tables
  1. Return to the Site Map. Go to *System Administration-->Installation-->Accounts Payable.

Spectrum Locked Tables
  1. Press Save. You should no longer encounter this error.

Spectrum Locked Tables

AP Invoices​

The following Info-Link tables are required when syncing AP Invoices from or to Spectrum:

  1. VN_GL_DISTRIBUTION_HEADER_MC
  2. VN_GL_DISTRIBUTION_DETAIL_MC
  3. VN_INVOICE_APPROVAL_HDR_MC
  4. VN_INVOICE_APPROVAL_DET_MC
  5. VN_INVOICE_TRAN_HEADER_MC6
  6. VN_INVOICE_TRAN_DETAIL_MC
  7. VN_CURRENT_ROUT_PROCESS_MC
  8. VN_ROUTING_HISTORY_MC

For details on enabling Info-Link tables for your user, see Steps 2.7 in our Spectrum authentication guide.

How is the Batch Number determined?​

If your PM System does not include a Batch Number, Agave Sync automatically assigns one based on the AP Invoice date. The Batch Number is set to the Saturday date of the week when the AP Invoice was synced, using the format "YYYYMMDD".

For example, if the sync occurs during the week of September 7, 2024 (Saturday), the Batch Number will be "20240907".

note

Agave Sync has a custom setting that allows for you to pick the day of the week you would like to use for the Batch Number date. If you would like to use a different day than Saturday, let your Agave Account Manager know.

AR Invoices​

The following Info-Link tables are required when syncing Customer AR Invoices from or to Spectrum:

  1. CR_INVOICE_HEADER_MC
  2. CR_INVOICE_DETAIL_MC

Work Order AR Invoices require the following tables:

  1. WO_OTHER_COST_DETAIL_MC
  2. WO_OTHER_COST_HIST_DETAIL_MC
  3. WO_MATERIAL_DETAIL_MC
  4. WO_MATERIAL_DETAIL_HIST_MC

For details on enabling Info-Link tables for your user, see Steps 2.7 in our Spectrum authentication guide.

How is the Batch Number determined?​

If your PM System does not include a Batch Number, Agave Sync automatically assigns one based on the AR Invoice date. The Batch Number is set to the Saturday date of the week when the AR Invoice was synced, using the format "YYYYMMDD".

For example, if the sync occurs during the week of September 7, 2024 (Saturday), the Batch Number will be "20240907".

note

Agave Sync has a custom setting that allows for you to pick the day of the week you would like to use for the Batch Number date. If you would like to use a different day than Saturday, let your Agave Account Manager know.

Error: 500 Internal Server Error: "There was an error processing your request. It has been logged"​

This error can occur if your GL processing dates have not yet been setup. Verify this under System Administration > Installation > Processing Dates.

If that does not fix the issue, try going to System Administration > Installation > Accounts Receivable, and hit the "Save" button on the top left. This error can occur if you are on a new instance of Spectrum and have never saved the installation.

How is the Spectrum Invoice Type determined?​

  1. If the AR Invoice amount is a positive number, Agave Sync sets the Invoice Type to “Regular”.
  2. If the AR Invoice amount is a negative number, Agave Sync sets the Invoice Type to “Credit Memo”.

AR Payments​

The following Info-Link tables are required when syncing AR Payments from or to Spectrum:

  1. CR_CASH_RECEIPT_TRAN_MC
  2. CR_CASH_RECEIPT_TRAN_DET_MC
  3. CR_CASH_RECEIPT_GL_HIST_MC
  4. CR_CASH_RECEIPT_GL_DETAIL_MC
  5. CR_TRANSACTION_MC
  6. CR_PAY_ADJUST_HISTORY_MC

For details on enabling Info-Link tables for your user, see Steps 2.7 in our Spectrum authentication guide.

Budget Line Items​

The following Info-Link tables are required when syncing Cost Types from or to Spectrum:

  1. JC_COST_TYPE_MASTER_MC
  2. JC_PHASE_MASTER_MC
  3. JC_PHASE_PROJECTED_TOTAL_MC
  4. JC_PHASE_ESTIMATE_TOTAL_MC

For details on enabling Info-Link tables for your user, see Steps 2.7 in our Spectrum authentication guide.

Change Orders​

The following Info-Link tables are required when syncing Change Orders from or to Spectrum:

  1. CR_CHNG_REQ_CON_DET_MC
  2. CR_CHNG_REQ_HDR_MC
  3. CR_CHNG_REQ_REV_MC
  4. CR_CHNG_REQ_STATUS_MC

For details on enabling Info-Link tables for your user, see Steps 2.7 in our Spectrum authentication guide.

Cost Codes​

The following Info-Link tables are required when syncing Cost Codes from or to Spectrum:

  1. JC_STD_PHASE_DESCRIPTION_MC
  2. JC_PHASE_MASTER_MC

For details on enabling Info-Link tables for your user, see Steps 2.7 in our Spectrum authentication guide.

Cost Types​

The following Info-Link tables are required when syncing Cost Types from or to Spectrum:

  1. JC_COST_TYPE_MASTER_MC
  2. JC_PHASE_MASTER_MC

For details on enabling Info-Link tables for your user, see Steps 2.7 in our Spectrum authentication guide.

Customers​

The following Info-Link tables are required when syncing Customers from or to Spectrum:

  1. CR_CUSTOMER_MASTER_MC
  2. CR_TERMS_MASTER_MC
  3. CR_CUSTOMER_CONTACTS_MC
  4. PA_CONTACTS_MASTER

For details on enabling Info-Link tables for your user, see Steps 2.7 in our Spectrum authentication guide.

Departments​

The following Info-Link tables are required when linking Departments (Cost Centers):

  1. EM_Cost_Centers_MC

For details on enabling Info-Link tables for your user, see Steps 2.7 in our Spectrum authentication guide.

Employees​

The following Info-Link tables are required when syncing Employees from or to Spectrum:

  1. PR_EMPLOYEE_MASTER_MC
  2. PR_EMPLOYEE_MASTER_1_MC
  3. PR_EMPLOYEE_MASTER_2_MC
  4. PR_EMPLOYEE_MASTER_3_MC

For details on enabling Info-Link tables for your user, see Steps 2.7 in our Spectrum authentication guide.

Inventory Locations​

The following Info-Link tables are required when linking Inventory Locations (Warehouses) with Spectrum:

  1. IM_WAREHOUSE_MASTER_MC

For details on enabling Info-Link tables for your user, see Steps 2.7 in our Spectrum authentication guide.

Item Receipts​

The following Info-Link tables are required when syncing Item Receipts to or from Spectrum:

  1. PO_PACK_LIST_HEADER_MC
  2. PO_PACK_LIST_DETAIL_MC

For details on enabling Info-Link tables for your user, see Steps 2.7 in our Spectrum authentication guide.

Items​

The following Info-Link tables are required when syncing Items to or from Spectrum:

  1. IM_ITEM_MASTER_MC
  2. IM_CATEGORY_MASTER_MC

For details on enabling Info-Link tables for your user, see Steps 2.7 in our Spectrum authentication guide.

Job Costs​

The following Info-Link tables are required when syncing Job Costs from Spectrum:

  1. JC_TRANSACTION_HISTORY_MC
  2. JC_COST_TRANSACTION_MC

For details on enabling Info-Link tables for your user, see Steps 2.7 in our Spectrum authentication guide.

Prime Contracts​

The following Info-Link tables are required when syncing Prime Contracts from or to Spectrum:

  1. CR_BID_ITEM_DES_MC
  2. CR_CONTRACT_MASTER1_V
  3. CR_CONTRACT_MASTER_MC
  4. CR_DRAW_REQUEST_DETAIL_MC
  5. CR_DRAW_UNIT_PRICE_BILL_MC

For details on enabling Info-Link tables for your user, see Steps 2.7 in our Spectrum authentication guide.

Projects​

The following Info-Link tables are required when syncing Projects from or to Spectrum:

  1. JC_JOB_MASTER_MC
  2. JC_JOB_CONTACT_DETAIL_MC
  3. JC_PHASE_ESTIMATES
  4. JC_PHASE_PROJECTED_TOTAL_MC
  5. JC_PHASE_MASTER_MC

For details on enabling Info-Link tables for your user, see Steps 2.7 in our Spectrum authentication guide.

Purchase Orders​

The following Info-Link tables are required when syncing Purchase Orders from or to Spectrum:

  1. PO_PURCHASE_ORDER_HEADER_MC
  2. PO_PURCHASE_ORDER_DETAIL_MC

For details on enabling Info-Link tables for your user, see Steps 2.7 in our Spectrum authentication guide.

Error: Invalid GL Account for Job/Phase/Cost Type​

If you receive the error Invalid GL Account for Job/Phase/Cost Type, it is because we are unable to determine the Ledger Account for a Purchase Order Line Item when it is synced to Spectrum.

Since your Project Management system does not have a General Ledger and General Ledger Accounts are required for creating Purchase Orders in Spectrum, Agave Sync will use one of the following General Ledger Accounts if available:

  1. The Cost Type's Default General Ledger Account in Spectrum (if available)
  2. A default Expense General Ledger Account value you provide your Agave Account Manager (e.g. "5150" for "Material Expenses"), or
  3. The Vendor's Default General Ledger Account in Spectrum (if available)

Setting a Vendor's Default General Ledger Account​

To set a Vendor's Default General Ledger Account:

  1. From the Spectrum Sitemap, go to Accounts Payable-->Maintenance-->Vendors:

Procore and Spectrum AR Invoice Visual Mapping
  1. Select a Vendor, then press Defaults and enter a value for G/L Distribution:

Procore and Spectrum AR Invoice Visual Mapping

Setting a Cost Type's Default General Ledger Account​

To set a Cost Type's Default General Ledger Account:

  1. From the Spectrum Sitemap, go to Job Cost-->Maintenance-->Cost Type:

Procore and Spectrum AR Invoice Visual Mapping
  1. Select a Cost Type, then press Edit and enter a value for G/L Account Code:

Procore and Spectrum AR Invoice Visual Mapping

Error: Value contains invalid character(s)?​

This is most commonly due to a special character in the Vendor Code in Spectrum. Per Spectrum's documentation, special characters cannot be used in the Vendor and Customer Codes in their Web Services.

Although you can use these characters in the Vendor Code in Spectrum's interface, the Web Service will reject any Contracts, Changes, or Invoices for these vendors.

You can resolve this by changing the Vendor Code to not use the special character in Accounts Payable > Utilities > Change Vendor Codes:

Spectrum Subcontracts

Note that you will then need to do a one-time re-link of the Vendor in Agave.

Service Sites​

The following Info-Link tables are required when syncing Customer Locations (Service Sites) to or from Spectrum:

  1. WO_ADDRESS_MC

For details on enabling Info-Link tables for your user, see Steps 2.7 in our Spectrum authentication guide.

Subcontracts​

The following Info-Link tables are required when syncing Subcontracts from or to Spectrum:

  1. VN_SUBCONTRACT_MC
  2. VN_SUBCONTRACT_PHASE_MC

For details on enabling Info-Link tables for your user, see Steps 2.7 in our Spectrum authentication guide.

Error: Invalid GL Account for Job/Phase/Cost Type​

If you receive the error Invalid GL Account for Job/Phase/Cost Type, it is because we are unable to determine the Ledger Account for a Subcontract Line Item when it is synced to Spectrum.

Since your Project Management system does not have a General Ledger and General Ledger Accounts are required for creating Subcontracts in Spectrum, Agave Sync will use one of the following General Ledger Accounts if available:

  1. The Cost Type's Default General Ledger Account in Spectrum (if available)
  2. A default Expense General Ledger Account value you provide your Agave Account Manager (e.g. "5400" for "Subcontractor Expenses"), or
  3. The Vendor's Default General Ledger Account in Spectrum (if available)

Setting a Vendor's Default General Ledger Account​

To set a Vendor's Default General Ledger Account:

  1. From the Spectrum Sitemap, go to Accounts Payable-->Maintenance-->Vendors:

Procore and Spectrum AR Invoice Visual Mapping
  1. Select a Vendor, then press Defaults and enter a value for G/L Distribution:

Procore and Spectrum AR Invoice Visual Mapping

Setting a Cost Type's Default General Ledger Account​

To set a Cost Type's Default General Ledger Account:

  1. From the Spectrum Sitemap, go to Job Cost-->Maintenance-->Cost Type:

Procore and Spectrum AR Invoice Visual Mapping
  1. Select a Cost Type, then press Edit and enter a value for G/L Account Code:

Procore and Spectrum AR Invoice Visual Mapping

Error: All Line Items Must Have the Same GL Account​

If you receive the error All Line Items Must Have the Same GL Account, it is because Spectrum requires that all Cost Types are enabled for the default GL Account on the Subcontract.

For context, a default GL Account is required when creating a Subcontract in Spectrum. Each GL Account can only have a single Cost Type assigned to it. For example, in the below image, the GL Account "5300 - Subcontractors" has a single Cost Type of "S" (for Subcontracts) assigned to it:

Procore and Spectrum AR Invoice Visual Mapping

Spectrum prohibits adding Subcontract Line Items with Cost Types that do not match the GL Account in the header. For reference, here is what is returned from the Spectrum website when you attempt to do so (in the below example, the Cost Type "O" is not associated with the Subcontract Header's GL Account of "5300"):

Procore and Spectrum AR Invoice Visual Mapping

Procore and Spectrum AR Invoice Visual Mapping

To fix this error, only use the Cost Type that is enabled for the Subcontractor Header for the Subcontract's Line Items.

Error: Value contains invalid character(s)?​

This is most commonly due to a special character in the Vendor Code in Spectrum. Per Spectrum's documentation, special characters cannot be used in the Vendor and Customer Codes in their Web Services.

Although you can use these characters in the Vendor Code in Spectrum's interface, the Web Service will reject any Contracts, Changes, or Invoices for these vendors.

You can resolve this by changing the Vendor Code to not use the special character in Accounts Payable > Utilities > Change Vendor Codes:

Spectrum Subcontracts

Note that you will then need to do a one-time re-link of the Vendor in Agave.

Tax Codes​

The following Info-Link tables are required when syncing Customer Locations (Service Sites) to or from Spectrum:

  1. CR_SALES_TAX_MASTER_MC
  2. GL_VALUE_ADDED_TAX_MC
  3. VN_USE_TAX_MASTER_MC

For details on enabling Info-Link tables for your user, see Steps 2.7 in our Spectrum authentication guide.

Timecard Entries​

The following Info-Link tables are required when syncing Timecard Entries from or to Spectrum:

  1. PR_PRE_TC_IMPORT_ERR_MC
  2. PR_PRE_TIME_CARD_MC
  3. PR_TIME_CARD_DETAIL_MC
  4. PR_TIME_CARD_HISTORY_MC
  5. PR_VOL_DEDUCT_MASTER_MC

For details on enabling Info-Link tables for your user, see Steps 2.7 in our Spectrum authentication guide.

How is the Batch Number determined?​

If your PM System does not include a Batch Number, Agave Sync automatically assigns one based on the Timecard Entry date. The Batch Number is set to the Saturday date of the week when the Timecard Entry was synced, using the format "YYYYMMDD".

For example, if the sync occurs during the week of September 7, 2024 (Saturday), the Batch Number will be "20240907".

note

Agave Sync has a custom setting that allows for you to pick the day of the week you would like to use for the Batch Number date. If you would like to use a different day than Saturday, let your Agave Account Manager know.

Units Of Measure​

Adding Units of Measure​

If you receive an error like the following: "The Unit of Measure associated with this model (SM) has not been synced", it's possible the Unit of Measure may not exist in Spectrum. To fix this error:

  1. From Spectrum's Sitemap, go to Accounts Receivable--> Maintenance--> Unit of Measure.

Spectrum Units of Measure
  1. Select New and enter details on the Unit of Measure you would like to add:

Spectrum Units of Measure

Spectrum Units of Measure
  1. Return to the Agave website. Go to the Units of Measure tab and link the new Unit of Measure.

Spectrum Units of Measure

The following Info-Link tables are required when linking Units of Measure to Spectrum:

  1. CR_UNIT_OF_MEASURE_MC

For details on enabling Info-Link tables for your user, see Steps 2.7 in our Spectrum authentication guide.

Vendors​

The following Info-Link tables are required when syncing Vendors from or to Spectrum:

  1. VN_VENDOR_MASTER_MC
  2. VN_VENDOR_CONTACT_DETAIL

For details on enabling Info-Link tables for your user, see Steps 2.7 in our Spectrum authentication guide.

Work Orders (Jobs)​

The following Info-Link tables are required when syncing Work Orders to or from Spectrum:

  1. WO_DISPATCH_STATUS_MC
  2. WO_HEADER_MC
  3. WO_PRIORITY_MC
  4. WO_TYPE_MC

For details on enabling Info-Link tables for your user, see Steps 2.7 in our Spectrum authentication guide.