Vista API Concepts

There are several concepts unique to the Vista API for identifying changes in the Vista database, manipulating data, and making API calls.

API Connection to Vista via App Xchange

The Vista API does not directly connect to or interact with your Vista instance, rather, API calls go to App Xchange, which stores a copy of your Vista data and takes the requested actions.

In order for App Xchange to access and modify your Vista data, the Xchange Agent must be installed. The Xchange Agent is a Windows service that is installed on the same server as your Vista database and provides secure access. The Xchange Agent is what discovers new, updated, and deleted Vista records on a scheduled basis (typically every hour) and updates the cache to match.

See https://direct-api.xchange.trimble.com/update/docs/vista-setup-and-connection

App Xchange Cache

The App Xchange cache exists as a midpoint between the Vista database and the API call.

When you make an API GET call, the data in the API response comes from the Vista data stored in this App Xchange cache. Therefore, it may not reflect the up to the minute state of your Vista database.

Outside of the hourly cache write, actions also update the cache for new or updated records when the action result shows successful.

It is important to understand that the Vista API is fundamentally asynchronous, requiring scheduled cache refreshes and queued actions.

Move Data In and Out of Vista

The Vista API has two primary behaviors for moving data in and out of Vista: action processing and cache writing. These behaviors identify changes in the Vista database and manipulate data as needed.

Action Processing

When an action (such as creating, updating, or deleting data) comes into the App Xchange platform, it is queued and processed before going to the Vista database. The Vista database responds with the results of the action (such as updating a Vista table with new data). The App Xchange cache record updates with the results of the action as well.
Actions are presented as POST endpoints and are used to modify data.

Read more about the nuances of action processing in the section below on Action Processing Responses, especially how to get the result of your request and handle errors.

Cache Writing

The caching behavior looks for changes in the Vista database and replicates those changes in the App Xchange cache, so that they are available to the Vista API. When you make an API call, the data is returning from the App Xchange cache, not your Vista instance.

Data in the cache is presented as GET endpoints. Caching is used to read data.

The section above on the App Xchange Cache describes the cache in more detail.

Vista Document Management file handling

Vista stores attachment metadata and file bytes separately. App Xchange mirrors this split across two data objects in the vista/dm/2 module.

Data objects

The attachments cache tells you that a file exists. It does NOT include file bytes or a download URL. To retrieve file content, call attachment_files/cache_file.

Downloading files from Vista (files out)

1. Discover attachments
   Query or listen to vista/dm/2/attachments for UniqueAttchID, AttachmentID, or KeyID.

2. Stage the file
   POST to vista/dm/2/attachment_files/actions/cache_file

   Request body example:

   {"Attachments": [ { "UniqueAttchID": "b0101539-b31b-4116-9bce-b8075893ae35" } ]}

   Alternative identifiers (use one per attachment):

   {"Attachments": [ { "__key": { "AttachmentID": 12345 } } ]}

   {"Attachments": [ { "__key": { "KeyID": 6789 } } ]}

   Direct API endpoint (replace {subscriber_code}):

   POST https://api.xchange.trimble.com/connect/v1/direct/subscribers/{subscriber_code}/vista/dm/2/data/attachment_files/actions/cache_file

3. Read the response
   Each item in the Attachments array may include:

   • filePointer.location
     Preferred for Direct API integrators. Download URL for the staged file.

   • __file_id
     App Xchange internal file ID. Primarily for flows and AppNetwork files API
     (subscribers/{code}/files/{id}).

   • errors[]
     Per-file failures. The action can return status Successful even when
     individual files fail. Always inspect errors[] per attachment.

   Success response example (simplified):

   {"Attachments": [ { "KeyID": 1881, "AttachmentID": 10, "UniqueAttchID": "b0101539-b31b-4116-9bce-b8075893ae35", "__file_id": "6424dc79-084a-4d86-b5e5-6b86d6a8ade6", "filePointer": { "filename": "invoice.pdf", "contentType": "application/pdf", "size": 245760, "location": "https://api.xchange.trimble.com/connectivity/file/v1/file-pointers/retrieve?token=..." }, "errors": [] } ]}

   Per-file error example (action may still be Successful):

   {"Attachments": [ { "UniqueAttchID": "b0101539-b31b-4116-9bce-b8075893ae35", "errors": [ { "text": "An error occurred while trying to retrieve attachment's keys (KeyID, AttachmentID and UniqueAttchID).", "source": ["HQAT / HQAF"], "details": "Attachment file bytes were not found for 'invoice.pdf'. Verify the Vista DM attachment store configuration (HQAO) and the Attachment Database Connection String on this connection." } ] } ]}

4. Download bytes
   HTTP GET filePointer.location with your Direct API credentials (X-Application-Key) as required.

Behind the scenes, the on-prem Xchange Agent:

• Looks up HQAT metadata on the primary Viewpoint database
• Reads bytes from HQAF (database) or filesystem path (HQAT.DocName) per Vista DM settings
• Uploads bytes to App Xchange file storage
• Returns filePointer and __file_id handles

Uploading files into Vista (files in)

Use vista/dm/2/attachments/add (or a module-specific add-attachment action) with URLToFileBytes pointing to the file to upload:

• Public HTTP(S) URL, or
• An App Xchange / AppNetwork file URL from a prior cache_file or file upload

Request body example:

{"HQCo": 1, "FormName": "AP Invoice Entry", "KeyField": "KeyID = 12345", "TableName": "APHB", "OrigFileName": "invoice.pdf", "DocAttchYN": "Y", "IsEmail": "N", "URLToFileBytes": "https://example.com/files/invoice.pdf"}

The agent downloads those bytes and writes them into Vista per DM attachment options (HQAO):

• HQAF database storage, or
• Filesystem path derived from HQAT.DocName

Attachment database configuration

Vista can store attachment bytes in:

1. Primary Viewpoint database (HQAF on same server as HQAT)
2. Separate attachment database (Vista DM > Attachment Options / HQAO)
3. Filesystem (HQAT.DocName path)

The Xchange Agent connection must match this configuration:

Attachment Database Connection String
- Leave BLANK when attachments are in the primary DB or on the filesystem.
- Set ONLY when HQAO specifies a separate AttachmentDatabaseServer /
AttachmentDatabaseName.
- Server and database MUST match HQAO exactly.

Misconfiguration is a common cause of cache_file failures: HQAT metadata is found
in Viewpoint, but HQAF bytes are read from the wrong store.

Diagnostic SQL (run on both primary Viewpoint DB and configured attachment DB):

SELECT a.AttachmentID, a.OrigFileName, LEN(f.AttachmentData) AS ByteLength
FROM HQAT a
LEFT JOIN HQAF f ON f.AttachmentID = a.AttachmentID
WHERE a.UniqueAttchID = ''

Troubleshooting cache_file

Custom Field Handling

You can make API calls to manipulate data in custom fields on all standard Vista tables, and we now have a separate User Defined Tables module. The hourly cache write automatically picks up changes to custom fields.

When making an API call, you must use the following formatting:

• Custom fields must be an object.
• Line item types must be an array.

Understanding Vista API Endpoints

There are multiple different endpoints you can use to access each Vista record and interact with the data.

For legacy support reasons, you may often see up to four different ways to GET a single data object.

For example, both of the following endpoints get an invoice batch entry object from the cache, but use different paths and parameters to access this data. These are the recommended endpoints to use.

 subscribers/{subscriber_code}/vista/ap/2/data/inv_batch_entries/cache/keyid/{KeyID}

 subscribers/{subscriber_code}/vista/ap/2/data/inv_batch_entries/cache/natural/{Co}/{Mth}/{BatchId}/{BatchSeq}

Both of the following endpoints function but are not recommended. They get an invoice batch entry object for the provided {ryvitId_value}, but use different paths to access this data:

 subscribers/{subscriber_code}/vista/ap/2/data/inv_batch_entries/cache/keyid/{ryvitId_value}

 subscribers/{subscriber_code}/vista/ap/2/data/inv_batch_entries/cache/__ryvitId/{ryvitId_value}

The two endpoints are functionally equivalent. The first rule specifies the index to select by; the second only provides the value with the API, assuming it should use the default __ryvitId index.

NOTE: Support recommends that you use the Vista indexes of keyid or natural. These allow you to interact with the cache using the same keys that Vista uses (as opposed to using the __ryvitId index).

The __ryvitKeys is a standard property which is a list of keys (a string array) for the object.

Endpoint Filtering Clarity

Consider the specific GET or POST request you want to use based on your purposes or what functionality you're trying to build into an integration.

For example, instead of getting all invoice batch entry objects from the cache, which you would use this endpoint to retrieve:

 /subscribers/{subscriber_code}/vista/ap/2/data/inv_batch_entries/cache

Instead target the specific object(s) you want with a more specific GET request, such as this, which uses the KeyID to identify a particular record:

 subscribers/{subscriber_code}/vista/ap/2/data/inv_batch_entries/cache/keyid/{KeyID}

Action Processing Responses

Using a POST request sends an action (such as creating, updating, or deleting data) to the App Xchange platform, where it is queued and processed before going to the Vista database. The initial response includes the following: id, operation (whichever endpoint you called), and status (queued).

Wait for the action to process (this takes about 30–40 seconds), then use this id and call the API again to get the completed response and additional details.