Common Errors and FAQs

Getting Started

Connecting to Cloud Versions of Vista

The below provides an overview of how to connect to cloud or hosted versions of Vista. It takes about 15-30 minutes to complete.

Step 1: Create an Agave User in Vista

The first step is to create a dedicated User to connect to Agave Sync. We recommend using a dedicated User for the integration, so you can track activity from your integration with your PM system.

To create a dedicated User, you can follow Trimble's guide. We recommend naming this user "Agave-User".

Step 2: Create a Ticket with Viewpoint Support Requesting Permissions

If you are using a hosted (cloud) version of Viewpoint Vista, you will need to open a case with Viewpoint Customer Support to add Agave's static IP addresses to your Vista TLS Database 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.

4. Select Support, then Systems/IT.

5. Under Which product are you using?, input the following and select Search Knowledge Base:

• Product: select "Vista".
• Version: select the version of your Vista instance (e.g. 2022 R2).
• Module: select "Vista Server and IT Related".
• Brief Summary: input "TLS Database Endpoint IP Whitelist".

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

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

Hi - we are looking to whitelist our IPs for TLS Database Endpoint connectivity with our Vista 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 name and port are for our instance?

We are also looking to add the following permissions for the "Agave-User" in our Vista instance. Would it be possible to confirm that the following permissions have been > added for the "Agave-User" to the Viewpoint and VPAttachments databases (see below screenshot from Microsoft SQL Server Management Studio)?

1. db_datareader
2. db_datawriter
3. public
4. VCSUsers

8. Press Submit.

9. After submitting a case, you should receive a response from Viewpoint Support within 24-48 hours confirming the connection the IP addresses have been whitelisted, the name of the database name and port, and that the permissions have been applied. Make a note of the hostname (e.g. {hostname}-sql.viewpointdata.cloud) and port number since you will need to use these to make the connection.

Step 3: Notify Agave to Make the Connection

Noting your Agave Account Manager that you are ready to connect Vista to your PM System!

General Errors

Table or Object Not Found

You might encounter an error like:

• "Phase Group for HQ Company X not found!"
• "Job not on file!"

This typically happens when syncing a specific record (e.g., a Subcontract or Job).

Context

The error occurs because a Security Group is restricting access to the table or view required for the sync operation. These restrictions are often in place to protect sensitive data.

Agave relies on stored procedures (e.g., to update Subcontracts or create AP Invoices) during data syncs. These procedures need access to specific tables/views, such as HQCO and bJob. If the SQL user created for the integration lacks permission to access these resources, the stored procedure fails, resulting in an error.

Solution

To resolve this issue, add the SQL user created for the integration (e.g., "Agave-User") to the Security Group that has access to the required tables:

• bJob
• bPMCO
• bHQCO
• bJCCM

To implement the foregoing:

1. Open VA Data Security Setup and press Grid. Note the “Default Security Group” applied to the datatypes “bHQCO” and “bJob”:

2. Go to Viewpoint Administration → VA User Profile:

3. Search for the System User you added (note, this would be the user you created for authenticating; e.g. “Agave-User-Application”):

4. Go to the Security Groups tab and add this user to the Security Group with the appropriate permissions:

5. Press Save:

AP Invoices

How is the Batch Month Determined When Syncing AP Invoices?

When syncing AP Invoices to Vista, we use the latest open AP Batch month. This is the month after the last closed month in GL Company Parameters.

Using the Accounts Payable Last Month Closed from the below screenshot as an example, if an AP Invoice was synced to Vista on 2/5/2022, the Batch Month would be set as "1/22" because this is the month after the last month closed for Accounts Payable (i.e. 12/21):

AR Invoices

How is the Batch Month Determined When Syncing AR Invoices?

When syncing AR Invoices to Vista, we use the latest open AR Batch month. This is the month after the last closed month in GL Company Parameters.

Using the Accounts Receivable Last Month Closed from the below screenshot as an example, if an AR Invoice was synced to Vista on 2/5/2022, the Batch Month would be set as "1/22" because this is the month after the last month closed for Accounts Receivable (i.e. 12/21):

AR Payments

How is the Batch Month Determined When Syncing AR Payments?

When syncing AR Payments (AR Cash Receipts) to Vista, we use the Transaction Date to determine the Batch Month.

For example, if an AR Payment has a date of "12/1/2024" the Batch Month will be set to "12/24".

Budget Line Items

Partial Cost Code Matches

When Budget Line Items are synced to Vista, a Phase Code (Cost Code) is added for a Project (i.e. to JC Job Phase Codes). In order for it to be added, it must either:

1. Fully-match a Phase Code in the Company list of Phase Codes (i.e. in JC Phase Codes), or
2. Match the first N characters of a Phase Code in the Company-list of Phase Codes, where N is determined by the below setting in Vista JC Company Parameters.

In the above example, if the first six characters of a Phase Code in a Budget Line Item match a Phase Code in the Company list, Vista will consider the Phase Code valid and add it to the Project's list of Phase Codes (i.e. to JC Job Phase Codes).

Common Errors

Locked Job Phases

You may encounter an error like the following when attempting to sync Budget Line Items:

This error is from a setting on the Job being enabled that locks Phases for the Job so that only those phases/cost types assigned to this job (in JC Job Phases or JC Job Original Job Estimates) can be used when posting committed or actual costs in the Accounting modules.

To resolve this error:

1. In Vista's Job Cost module, go to JC Jobs and then the the Job record.
2. Unselect the "Phases on This Job Are Locked" checkbox:

3. Resync the record.

Sub Jobs

Partial Cost Code Matches

When Budget Line Items are synced to Vista, a Phase Code (Cost Code) is added for a Project (i.e. to JC Job Phase Codes). In order for it to be added, it must either:

1. Fully-match a Phase Code in the Company list of Phase Codes (i.e. in JC Phase Codes), or
2. Match the first N characters of a Phase Code in the Company-list of Phase Codes, where N is determined by the below setting in Vista JC Company Parameters.

In the above example, if the first six characters of a Phase Code in a Budget Line Item match a Phase Code in the Company list, Vista will consider the Phase Code valid and add it to the Project's list of Phase Codes (i.e. to JC Job Phase Codes).

Common Errors

Locked Job Phases

You may encounter an error like the following when attempting to sync Budget Line Items:

This error is from a setting on the Job being enabled that locks Phases for the Job so that only those phases/cost types assigned to this job (in JC Job Phases or JC Job Original Job Estimates) can be used when posting committed or actual costs in the Accounting modules.

To resolve this error:

1. In Vista's Job Cost module, go to JC Jobs and then the the Job record.
2. Unselect the "Phases on This Job Are Locked" checkbox:

3. Resync the record.

Timecard Entries

How does Agave Sync determine the Batch ID when syncing Timecard Entries to Vista?

Agave Sync determines the Batch ID by:

1. Checking for an Existing Batch ID: Agave Sync looks for an open Batch ID with the correct Batch Month, PR End Date, and PR Group. If it finds one created by the Agave Vista user, it uses that Batch ID.
2. Creating a New Batch ID if None Exists: if no suitable Batch ID exists, the Agave Sync Vista user creates a new Batch ID for the first synced timecard. This newly created Batch ID is then used for subsequent syncs.

How does Agave Sync determine the PR End Date?

Agave Sync will default to Saturday of each week as the PR End date.

note

If you use a different day of the week than Saturday, let your Agave Account Manager know and they can apply a setting to use that day.

How is the Batch Month determined When Syncing Timecard Entries?

When syncing Timecard Entries to Vista, Agave Sync uses the month of the PR End Date.

For example, if a Timecard Entry has a date of "2/28/2025", but the PR End Date is "3/3/2025", the Batch Month will be set to "3/25".

How does Agave Sync Determine the PR Pay Sequence?

Agave Sync applies a default Pay Sequence for all Timecards synced from your PM System to Vista.

You can determine your Pay Sequence by going to PR Pay Period Control, selecting the relevant PR Group, and pressing the Payment Sequence tab:

Unit of Measure

Adding Units of Measure to Vista

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

1. In Vista, go to Headquarters-->HQ Units of Measure:

2. Select New Record:

3. Enter details for the new Unit of Measure and press Save Record: