Use this article to install the ToolWatch Integration Connector and connect it to your Viewpoint Vista database. First, you install the connector, give it access to your Viewpoint database, and check its network connection. Then you send your connection details to ToolWatch, and our team confirms that everything is working. If needed, you can also change the connector region, set up a cost code view, and set up a shared folder for posting files.
Install the ToolWatch Integration Connector
Download the .MSI file from secure.toolwatch.com/g/connector-install.
Run the .MSI file.
After the install is complete, open a web browser and go to http://localhost:5280. A Windows Service now runs in the background.
Record the Connector ID shown on the page.
Grant the Connector Access to the Viewpoint Database
In Microsoft SQL Management Studio, expand the Security menu.
Right-click Logins and select New Login.
Enter a login name, such as TWConnectorUser.
Select SQL Server authentication.
Enter a password of your choice.
Clear the Enforce password policy checkbox.
Make sure the Default database is your Viewpoint database.
Go to the User Mapping page.
Make sure TWConnectorUser and your Viewpoint database are selected.
Grant the user these permissions: db_datareader, public, and VCSUsers.
In your Viewpoint database, expand the Security menu.
Right-click Users and select New User.
Enter the login name you created in step 3 as both the user name and the login name.
Go to the Membership page.
Grant the database user these roles: db_datareader and VCSUsers.
Change the Connector Region (If Needed)
Depending on your ToolWatch region, you may have to change what server the ToolWatch Integration Connector communicates with. By default the Integration Connector communicates with the East region. ToolWatch will inform you during integration setup if this needs to be changed. To change this region on the Windows machine with the connector:
Open a web browser and go to http://localhost:5280/.
Confirm that you see a version number on this page. If you do not, download and install the latest version of the connector.
To the right of API URL, click edit.
On the page that loads, enter the API URL for your region from the Region API URLs list below.
As instructed on the confirmation page, restart the Windows Service.
Refresh the page to see that the change has taken effect.
Region API URLs
Check the Network Connection
Networking rules where the ToolWatch Connector is installed might block traffic to these API endpoints.
On the computer where the ToolWatch Connector is installed, open a web browser.
Go to the API URL for your region.
Make sure the text "ToolWatch Connector API" appears.
To run more connection tests, go to the connector page at http://localhost:5280/.
Click Check connection.
Note: The Check connection link runs a series of connection tests for the current API endpoint. If the first test is successful, you will see "Success!". Otherwise, you will see the response code and error message for the connection request, the DNS name resolution for the API endpoint, and whether you were able to connect to the API endpoint through a TCP connection on port 443. You can run as many connection checks as needed. If the connection check fails, contact ToolWatch Support.
Send Your Connection Details to ToolWatch
Please let us know when the connector has been installed and we will have our team check to confirm everything is working properly. When you reply, please be ready to provide the following information, some of which will be derived from following the install instructions:
Connector ID
Server name
Database name
Database login name
Database login password
Default Company ID
If you would prefer not to send this information via email, then please call our support team at 720-856-3441 and they will be happy to capture the information over the phone.
Set Up the Cost Code View
The Use Cost Code View setting allows the integration to filter cost codes before sending them to ToolWatch. This can be used to filter to cost types or filter out Vista phase codes by number or description. Once this setting is enabled both the mapping and the sync will only access the Vista phases thru an SQL view. To function properly the setting requires a view be created on the Vista SQL database as follows:
The view needs to be created on the hosting Vista SQL database in the dbo schema.
The view needs to be named exactly: ToolWatchCostCodeView
The ToolWatchCostCodeView can not use parameters as no parameters will be passed.
The ToolWatchCostCodeView has to return the expected fields by these exact names: PhaseGroup, Phase, Description, Notes, KeyID, Job, ActiveYN, JCCo
Any and all filters need to be in the WHERE clause or a result of any JOINS added to the view.
The ToolWatchCostCodeView should filter by Vista company.
When ToolWatch selects from tables it starts with this SELECT statement:
SELECT p.PhaseGroup
,p.Phase
,p.Description
,p.Notes
,p.KeyID
,p.Job
,p.ActiveYN
,p.JCCo
FROM bJCJP p WITH (NOLOCK)
JOIN bJCJM j WITH (NOLOCK)
ON p.Job = j.Job
WHERE p.JCCo = (the company number for the sync) its an integer
It is recommended that the view join to the bJCJM on the JobId and set the phase code status to the job status.
JOIN bJCJM j
ON p.Job = j.Job
and pulling the j.ActiveYN so the resulting cost code will have the status of its parent job.
The view should be written and implemented by a SQL professional. ToolWatch is not responsible for maintaining the view as it is on the customer's database. We will help as much as we can to get the view coded and working.
Sample View:
CREATE VIEW ToolWatchCostCodeView AS
SELECT p.JCCo
, p.PhaseGroup
, p.Phase
, p.Job
, p.Description
, p.Notes
, j.ActiveYN
, p.KeyID
FROM dbo.bJCJP p (NOLOCK)
JOIN bJCJM j (NOLOCK)
ON p.Job = j.Job
WHERE p.JCCo = 1
AND p.Description LIKE '%15%'
When the connector is installed, the service will run under the user 'Local Service' by default. If you want posting to send files to a server folder via the 'WriteTextFile', you have to make sure the folder is a shared folder and it allows 'Local Service' to write to that location. You can do that by:
Creating a share folder
Create and name your folder.
Right-click the folder and go to Properties.
Go to the Sharing tab.
Click Share.
Select Everyone from the dropdown list.
Click Share to complete.
Updating permissions on the share folder
Right-click the share folder and go to Properties.
Go to the Security tab.
Click Edit.
Click Add.
Search for Local Service.
Add Local Service to the group.
Click Apply/OK until done.
If the service user is changed, then that Windows user (not Local Service) will need access to the destination folder.
Q: What is the ToolWatch Connector?
A: The ToolWatch Connector is a Windows Service that allows the ToolWatch Cloud to integrate with on-premise systems.
Q: Where should this connector be installed?
A: For Vista, Spectrum, and CMiC integration customers, the connector can be installed on any host that has network access to the database or the APIs exposed by the application server. This can be the database server itself, the application server, or a completely separate host.
For Sage 100 Contractor or Sage 300 CRE integrations, the connector must be installed on a host that has filesystem access to the application database. This can be either via the local filesystem, or via a network share.
Q: What are the network requirements?
A: For all integrations the host must be able to make outbound HTTPS calls to:
api-connector.toolwatch.net
api-connector.east.toolwatch.net
api-connector.central.toolwatch.net
api-connector.west.toolwatch.net
If you need to whitelist these destinations, you must whitelist the domain, and not the IP address, as the IP address will change frequently as our cloud platform elastically scales up and down.
No inbound network access is required.
Q: Are there any requirements for the host?
A: The host only needs to be running Windows with a recent version of the .NET framework. There are no other external requirements such as SQL Management Studio. CPU, memory, and disk requirements are negligible.
Q: How much load will this put on our production system?
A: The load caused by the integration should be negligible relative to a normal workload, but as with all things appropriate testing is advised. A simple approach would be to initially try the integration after hours for load testing. Using a ToolWatch sandbox account would further allow for testing different configurations without worrying about affecting production data.
Q: How do you uninstall the ToolWatch Connector?
A: Use the Windows Add/Remove Programs in Windows Settings. The connector will be listed as "ToolWatch Connector" and can be uninstalled using the remove option.