Setting Up Automatic Imports into Vista

Author: Eric Vasbinder

Overview

Often times customers will want to automatically push data into Vista using file imports, such as a CSV file.  Automatic imports, a.k.a "auto-imports", are a powerful way in Vista to allow for the regular, hands-off adding of data from other solutions into Vista.  This can be to provide time data, fuel usage, and more into Vista every day, week, or month, etc.

On-premise customers normally make use of this functionality by designating a specific folder (a.k.a. the "Pickup" directory) that Vista will watch for import files (usually CSV or XLS/XLSX format).  Import files can then be copied to that folder.  Oftentimes that folder is a child directory under the "Viewpoint Repository" folder.   Customers will frequently map that folder as a mapped drive for third party servers to use to drop files into the Pickup directory.  

 When Vista is moved into the cloud however, there will be a few small additional steps necessary in order to enable this operation.

Please see below for additional detailed instructions.

CRITICAL NOTE:  Manual file imports should NOT be processed by dropping files into the pickup folder

Users who desire to manually import files into Vista should use the MANUAL file import option described here: https://help.trimble.com/en/vista/vista/administration/imports/processing/import-a-data-file

 Please be aware that the MANUAL IMPORTS method linked above is available only for Vista clients connecting to the database over Vista Remote Link (VRL).

1. Pre-Requisites

The following are specific prerequisite items that need to be in place before the pickup folder for Vista can be made available to your third-party integrations for use.

1. Ensure you have the private IP address of the Vista database available. 

2. Set up an IPSEC VPN tunnel from the Viewpoint cloud to the location where the server communicating to Vista is located.

   1. To Request an IPSEC VPN tunnel, please see here:  How do I set up an IPSEC VPN to access my Vista database directly? 

3. Ensure you have port 445 for SMB access opened over the firewall from the private IP address of the Vista server in the cloud to and from your network.

4. (OPTIONAL)  You can use a UNC path to access the pickup folder from your server, OR you can map the UNC path to a network mapped Drive letter.

2. Creating an AD Service Account and Enabling Viewpoint Repository Group Membership

You will need to have an AD service account created that can be used to within our network to mount the SMB file share.

You can either do this yourself through our Cascade portal or by creating a support case.

Method A:  Cascade Portal

1. Please use the steps in the following cloud FAQ to create your new Cascade user:  Cascade Portal:  Adding and Importing Users 

2. Then add that user to the appropriate Viewpoint Repository group for your environment, by following the steps in this cloud FAQ:  Cascade Portal:  Adding and Removing Group Members 

3. Request that the new account have its password set to never expire via a support case.

If you have any questions, or do not have access to the appropriate areas in Cascade, please reach out to our cloud support team.

Method B:  Cloud Support Request

1.  Submit a cloud support request if after go-live, or a Transformation support case if prior to go-live.  This support case should request that an AD service account be created and that it be added to the Viewpoint Repository user group.

2. Trimble Viewpoint staff will coordinate with you to provide you with the credentials for this account in a secure fashion.

THIS METHOD MUST BE PERFORMED BY TRIMBLE VIEWPOINT PERSONNEL.   

CRITICAL NOTE:  This account's password will be set to not expire and should NEVER be used by a standard human being interactively logging in to our cloud; ONLY for automatic server to server mounting of the Viewpoint Repository share.

3.  Manually Mounting the SMB Share via the Explorer GUI for Testing

For testing purposes, we should manually mount to the SMB file share first, before proceeding with automatic mounting in the next major step.

3.1.  Open Windows Explorer.

3.2.  Right-click on network.

3.3.  Select Map Network Drive.

3.4.  Pick a drive letter.

3.5.  Enter the address of the remote file share as a UNC path (e.g. \\yyy.yyy.yyy.yyy\Viewpoint Repository\Bulk Inserts).  Replace the "y's" with the actual private IP address of your Vista database server in the cloud.

3.5.1.  Make a note of the entire path name that you will be using, this will be necessary in the next major step.

3.6.  Check the "Reconnect" box

3.7.  Check the "connect using different credentials" box

3.8.  Enter your service account credentials that have been created in the previous step.

3.9.  Click OK

3.10.  Click Finish

Now you may browse to the drive letter that you have mounted and should thus have access to test uploading files for import into the pickup folder.

4.  Manually Mounting the SMB Share via Powershell or Command Prompt for Testing

For testing purposes, we should manually mount to the SMB file share first, before proceeding with automatic mounting in the next major step.

4.1.  Open Powershell or Command Prompt.

4.2.  Type into the prompt, the following command at the command line (where "V" is the drive letter chosen for this mounted drive and YYY are the numbers of the IP address of the Vista database server in the UNC path to the Viewpoint Repository folder in the cloud (e.g. \\yyy.yyy.yyy.yyy\Viewpoint Repository\Bulk Inserts):

net use V: "\\yyy.yyy.yyy.yyy\Viewpoint Repository\Bulk Inserts" /SAVECRED

4.3.  You will then be prompted to enter the username for the share.  Please enter the Service Account name:

username@companyIdentifier

4.4.  You will then be asked to enter the password for this account.  Please enter it.

Now you may browse to the drive letter that you have mounted and should thus have access to test uploading files for import into the pickup folder.

5.  Setting up Auto-Mounting of the SMB Share

Now that we have tested the reliability of mounting the SMB share, we should set up a command to mount this share automatically on the server that will be pushing files to the Vista pickups directory.

5.1.  Open PowerShell or Command Prompt ("cmd.exe")

5.2.  Enter the following command at the command line (where "V" is the drive letter chosen for this mounted drive and YYY are the numbers of the IP address of the Vista database server in the UNC path to the Viewpoint Repository folder in the cloud (e.g. \\yyy.yyy.yyy.yyy\Viewpoint Repository\Bulk Inserts):

net use V: "\\yyy.yyy.yyy.yyy\Viewpoint Repository\Bulk Inserts" /SAVECRED /PERSISTENT:YES

5.3.  You will then be prompted to enter the username for the share.  Please enter the Service Account name:

username@companyIdentifier

5.4.  You will then be asked to enter the password for this account.  Please enter it.

Your drive letter should now persist on the server after reboots.

6.  Configuring Third-Party Tools

Third-party integrations need to be manually configured to point to the new location of the Vista pickup directory in the Viewpoint cloud.  In order to execute this task, for each integration, please reach out to your third-party vendor for more information on how to configure their solution.

7.  Configuring Vista to Scan the Pickup Directory at Regular Intervals

Once the third-party tools have been configured to point to the new location of the pickup directory, Vista itself should be configured to scan that pickup directory in the cloud to pick up on newly added import files. These actions to configure the scanning frequency and location of the pickup folder will be performed by Viewpoint's Cloud Transformations team. 

7.1  IM Auto Import Profile Setup

As part of this process, you may need to set up an IM Auto Import Profile if you do not already have one.   Please use the following instructions as a guide ere are the instructions for that task:

1.  Go to the IM Module in Vista.

2. Open the IM Auto Import Profile Setup form.

3. Click the New button on the toolbar to create a new profile.

4. Fill in the various directories for "Pickup", "Archive", "Error", and "Log".

   1. Usually these would be in the form of "\\SERVERNAME\...", where your SERVERNAME is your Vista App server in our cloud.

   2. Please reach out to cloud support for assistance if you do not know the server names or do not have access to this form.

5. Set a Default Company. Most import templates will default items based on the company you're using; this just tells the import the company from which you are running the import.

6. Save the Import Profile.

7.2  Create Vista Auto Import User

1. Open VA User Profile form.

2. Create a user for the Auto Imports.

   1. Jot down the password you set for the user. No other form permissions need to be set up for this user because it is only used for this auto import process. However, datatype security might need to be considered. When importing things like PR Timecards, access should be granted to this user to any secured datatypes affected by the import. Be sure to record the password.

   2. IMPORTANT:  The import user MUST BE A SQL USER added within VA User Profile.  It is recommended to add this user from the Vista client using the VA User Profile program in it.  Here is a Vista Cloud FAQ article that will provide more details on this topic:  https://sites.google.com/trimble.com/vista-cloud-faq/home/integration-technology/creating-sql-accounts

   3. IMPORTANT:  The vcsautoimports pre-existing user should not be used because, by default, that password is randomized when the Vista Application Server Installer is run. 

   4. The software does not require that the import user's password be rotated or updated at all. However, if your organization has an internal password policy for changing/updating user passwords with a certain cadence, this user may fall under that policy.

7.3  Configuring Viewpoint Remote Service

The next step is to configure the Viewpoint Remote Service to scan the pickup folder and how frequently to do so.  Please note that this required step is, for customers on our standard environments, only possible for our cloud support personnel.  As such, to configure the import frequency, please file a support case with our cloud support team.

7.4  Testing Auto Imports

Once you have gotten to this stage, you can test the auto imports functionality by browsing to the mapped import "Pickup" folder from above.  Then, drop an import file into Pickup folder.  Auto Imports will both import and upload the file, and if successful, the file will be moved to the Archive folder; if not, it will go into the Error folder. Activity logs will be written to the Log folder.

7.5  Setting up Notifications for Imports (OPTIONAL)

Optional: Set up a notification from the Notifications tab of the import template. Because auto imports are unattended, it is helpful to have an indicator of the success or failure of the process.

Please see the below screenshot for how you might configure the IM Template for notifications.