Viewpoint Vista Guide

Setting up the Viewpoint Vista Integration

The Viewpoint Vista integration is available only to customers with an enterprise contract. Vista is a construction ERP from Trimble, and the connection runs through Trimble's App Xchange integration platform, so setup is a guided onboarding process rather than a self-serve flow.

Contact the Rutter team to discuss your use case and determine whether your organization qualifies for access to this integration.

User Authentication with Viewpoint Vista

A Rutter Connection is created when your end user is onboarded to Viewpoint Vista with the help of the Rutter team. This in turn allows you to access their account data via the Rutter API.

Rutter never connects directly to a customer's Vista database. Instead, data moves through App Xchange:

1
Vista ⇄ App Xchange Agent ⇄ Trimble App Xchange ⇄ Rutter

Each Rutter Connection corresponds to one App Xchange customer deployment for your end user's Vista environment. Rutter will provide detailed onboarding instructions, and your end user will need the following:

• Cloud-hosted Vista. The integration supports Vista environments hosted by Trimble (Trimble Construction One customers). Self-hosted installations require the App Xchange Agent to be installed locally.
• A Vista admin to create a dedicated Vista service user for the integration.
• An App Xchange user to accept the App Xchange invitation and enter the Vista connector configuration, including the Vista company numbers (Co) Rutter should read from and post to.
• Trimble Support to install the App Xchange Agent on the Vista environment. This typically takes 1-3 business days.

For invoice writes, also collect the default customer group (CustGroup) and, optionally, the default receivable type (RecType) to use on new invoices.

Supported Endpoints

Rutter can read the following from Viewpoint Vista:

• Customers
• Vendors
• Items (materials and equipment)
• Accounts
• Tax rates
• Payment terms
• Invoices
• Projects (Vista jobs)
• Tasks (Vista job phases)
• Locations (Vista inventory locations)
• Employees (limited to non-sensitive fields; bank, pay, and other sensitive Vista employee data is never stored)

Rutter can create invoices in Viewpoint Vista.

Viewpoint Vista Specifics

Data syncs are push-based, not polled

Because App Xchange cannot be called from outside, Rutter does not poll Vista. App Xchange flows push Vista data to Rutter after an initial load. Reads are served from App Xchange's cache, which refreshes about hourly, so recent changes in Vista can take up to an hour to appear in Rutter. Vista records are matched to Rutter objects using a stable ID built from Vista's composite keys (for example, a customer ID is the customer group and customer number joined with |).

Creating invoices is asynchronous

POST /accounting/invoices returns an async job. Rutter queues the invoice, and an App Xchange flow picks it up on a schedule (about every 15 minutes) and posts it to Vista as a batch, an invoice entry, and a post step. A write typically completes within 15-20 minutes. Poll GET /jobs/{job_id}: a successful job returns the posted invoice, and a failed job returns the Vista step that failed.

Invoice writes have these constraints:

• Non-contract AR invoices only. Contract billing (job cost) invoices are not supported.
• The invoice month must be open in Vista. Writes outside open AR posting months fail with a message such as Month must be between ....
• Length limits. document_number is limited to 10 characters, and memo and line description to 30 characters. Longer values are rejected with a 400 instead of being truncated, so distinct invoice numbers cannot collide.
• Duplicates are rejected. An invoice with the same number for the same customer as an existing or in-progress invoice fails.
• Equipment items cannot be invoiced. Lines that reference an equipment item are rejected with a 400. Lines can reference materials or general ledger accounts.

Account and ID formatting

Vista pads many codes with leading or trailing spaces, such as general ledger account numbers ( 1000.) and job numbers. Rutter trims these in invoice and project IDs where it can, but you should pass account IDs back to Rutter exactly as you received them.

Field coverage

Some Vista data is only available in platform_data. For example, a Vista job's customer lives on the contract rather than the job, so projects do not have a customer link, and the Rutter task object has no project field. Equipment is returned as service items alongside materials, with no prices.