How to set up Vista Spectrum

A Comprehensive Guide to Setting Up Vista Spectrum

Viewpoint Spectrum Authentication

To authorize access to read and write data between your product and Viewpoint Spectrum using Agave, you will need to complete the following steps:

Step 1: Open a Case with Viewpoint Customer Support

Open a case with Viewpoint Customer Support to add Agave's IP address your Viewpoint Spectrum 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 Spectrum.
• Version: select the version of your Spectrum instance (e.g. 2022 R3).
• Module: select "SDX - Data Exchange - Spectrum".
• Brief Summary: input "API Endpoint IP Whitelist".

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

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

Hi - we are looking to whitelist our IPs for Spectrum API Endpoint connectivity with our Spectrum 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, if they differ from Spectrum and 1433?

1. Press Submit.
2. 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.

Step 2: Create Info-Link Users

To enable read API requests (e.g. GET AP Invoices), you will need to create an Info-Link user, and provision them access to specific Viewpoint Spectrum tables which are grouped into "Categories".

1. Login to your Viewpoint Spectrum account.
2. Press the + at the top of the page.
3. Select System Administration, then Installation, then Info-Link.
   
4. Continue to press "Reset" until the User ID for Info-Link is "INFO0003". Then press Save.

5. Return to the Site Map. Select Info-link, then Table Categories Maintenance.

6. Select New, and add a Table Category and Description. You can create these Categories however you see fit. If you would like to keep it simple, we recommend creating one Table Category:

CAUTION

Make sure you have followed step 4 above to ensure the User ID for Info-Link is not "INFO0001" before continuing.

1. Return to the Site Map. Select Info-link, then Table Security Maintenance.
2. Select New, and add the names of Tables for which you want to support read or write requests. Note, we recommend setting Read or Write Access to "9", unless you have more granular security permissions.

For reference, here are a list of frequently requested tables (note that the tab bar scrolls horizontally):

CAUTION

Make sure you add the JC_JOB_MASTER_MC and VN_VENDOR_MASTER_MC tables. These are the default tables we check to confirm the customer's Spectrum account has linked successfully.

If your customer uses Cost Centers, you will also need to add EM_COST_CENTERS_MC. For more info on Cost Centers, see guide.

• AP Invoices
• AP Payments
• AR Invoices
• AR Payments
• Assets (Equipment)
• Bank Accounts
• Budget Line Items
• Cost Codes
• Cost Types
• Customers
• Employees
• Items
• Ledger Accounts
• Prime Contracts
• Projects
• Purchase Orders
• Subcontracts
• Tax Codes
• Timecard Entries
• Vendors

Spectrum Table	Read Access required for...	Write Access required for...
VN_GL_DISTRIBUTION_HEADER_MC	All Operations	PUT / DELETE
VN_GL_DISTRIBUTION_DETAIL_MC	All Operations	PUT / DELETE
VN_INVOICE_APPROVAL_HDR_MC	All Operations	PUT / DELETE
VN_INVOICE_APPROVAL_DET_MC	All Operations	PUT / DELETE
VN_INVOICE_TRAN_HEADER_MC	All Operations	PUT / DELETE
VN_INVOICE_TRAN_DETAIL_MC	All Operations	PUT / DELETE
VN_CURRENT_ROUT_PROCESS_MC	DELETE	DELETE
VN_ROUTING_HISTORY_MC	DELETE	DELETE

For example, adding the below Tables adds support for reading AP Invoice Header and Line Item Tables:

1. Select Update Database.
2. Return to the Site Map. Select Info-link, then User Security Maintenance.
3. Select New, then select a Company, add a Database User and Password, and select the Table Category.

CAUTION

Make sure you have followed step 4 above to ensure the User ID for Info-Link is not "INFO0001" before continuing.

1. Select Update Database.

DANGER

Make sure the Link User you create is uniquely named across Viewpoint Spectrum Companies, otherwise you might run into database validation issues. If you have any concerns, feel free to contact us at api-support@agaveapi.com.

Step 3: Create Authorization ID

Configure an Authorization ID and enable required web services:

1. Login to your Viewpoint Spectrum account.
2. Press the + at the top of the page.
3. Select System Administration, then Installation, then Data Exchange.

1. In Data Exchange screen, select New.

1. Input a name for the Authorization ID (e.g. "Agave").
2. Select a Company Code and Operator Code for the Authorization ID, and select Active for Status.

1. Add a Memo for the Authorization ID (e.g. "API access for Agave").
2. Select Build. Then select the relevant Web Services you are looking to support for the integration. For example, the below authorizes access to retrieve details about Jobs from the Job Cost module.

When creating an Authorization ID, you will need to enable the following Web Services for the corresponding Agave endpoint you plan to use:

Agave Endpoint	Service	Web Service(s)
https://docs.agaveapi.com/reference#tag--ap-invoices	AccountsPayable	AddAPInvoice, APMultiLineInvoice
https://docs.agaveapi.com/reference#tag--ar-invoices	AccountsReceivable	AddARInvoice, ARMultiLineInvoice
https://docs.agaveapi.com/reference#tag--budget-line-items	JobCost	AddPhase, GetPhase, GetPhaseEnhanced, PhaseNotes
https://docs.agaveapi.com/reference#tag--customers	AccountsReceivable	AddCustomer, CustomerNotes, CustomerBillto, CustomerShipto, GetCustomers
https://docs.agaveapi.com/reference#tag--employees	Payroll	GetEmployee, EmployeeNotes
https://docs.agaveapi.com/reference#tag--projects	JobCost	AddJob, GetJob, GetJobContact, GetJobDates, GetJobMain, UpdateJob
https://docs.agaveapi.com/reference#tag--purchase-orders	PurchaseOrder	POBatch, PODetail, POHeader
https://docs.agaveapi.com/reference#tag--timecard-entries	Payroll	PreTimeCard_Batch
https://docs.agaveapi.com/reference#tag--vendors	AccountsPayable	AddVendor, GetVendors, UpdateVendor, UpdateVendor_Locations, VendorNotes

CAUTION

Make sure you always add the GetJobMain Web Service under the JobCost Service. We use this endpoint to confirm the customer's Spectrum account has linked successfully.

1. Select OK.
2. In the Data Exchange Installation page, select Settings and press the checkbox for Enable Enhanced Authentication.

NOTE

You do not need to enable Enhanced Authentication if you would prefer to use Basic Authentication. However, certain endpoints will not supported. For more info, see related FAQ.

Step 4: Authenticate Using Agave Link

To authenticate using Agave Link, you will need to pass the following components:

1. Authorization ID: this is the value for Authorization ID you created above.
2. Company Code: this is the Company Code associated with your Authorization ID. This can be retrieved in the top right corner of the prompt for Edit Authorization ID after Company: {Company Code}.

1. Domain: this is the domain for your Viewpoint Spectrum instance. It is the text that precedes "dexterchaney.com" in the UI. For example, in the URL https://{test}.dexterchaney.com, the domain is {test}.
2. Client ID and Client Secret: the values for these input fields can be retrieved by selecting the Authorization ID, selecting Edit, then selecting Secret Status.

NOTE

Client ID and Client Secret are only required if you have Enhanced Authentication enabled. If you only have Basic Authentication enabled, you do not need to input the Client ID and Client Secret.

CAUTION

If you have enabled Enhanced Authentication, make sure you check the box for Allow self-rotation? This will ensure your Spectrum API access will continue to work after the expiration date.

1. After pressing Next, you have the option to input Info-Link credentials. If you created an Info-Link users, press Yes.

1. Input the Database Hostname. This is the hostname of your database server. For example, if your Spectrum instance is hosted byviewpoint and you access it at https://company-abc.dexterchaney.com, enter company-abc-data.dexterchaney.com. Note that this hostname needs to be accessible to Agave's IPs (even if it is otherwise not publicly accessible).
2. Input the Database Port and Database Name. The default values are are 1433 and Spectrum respectively.
3. Input your Info-Link User and Info-Link Password. These are the credentials you created for the Info-User you added (see above).
4. Select "Yes" or "No" for the Ignore Certificate Check?. If checked, we will not validate the server certificate received by the database. Note that this will make the connection less secure, but might be necessary for certain on-prem instances of Spectrum.
5. Select Set Up Info-Link.