tigerpaw rest api installation checklist and...

Tigerpaw REST API Installation Checklist of 21 Last modified 05/26/20

Tigerpaw REST API Installation Checklist and Instructions

Tigerpaw REST API Installation Checklist and Instructions

Introduction

The Tigerpaw REST application programming interface (API) is a web service that enables third-party

applications such as remote monitoring and management (RMM) tools to securely query and update

Tigerpaw data in real time.

NOTE: The API must be available to the public Internet, which is achieved by configuring the firewall,

router and DNS correctly. The checklist instructs you to test the API from a device outside of your

network, such as someone's home system or a smart phone that is not linked into your network.

Print the checklist (pages 1-4) and keep this document open so you can easily view the linked

Related Topics for certain steps.

Tigerpaw REST API Components

These components are necessary for two-way communication between Tigerpaw and third-party

applications. The checklist includes setup instructions for each component.

Component Description

Tigerpaw REST API The Tigerpaw REST API is a web service that enables communication between

Tigerpaw Desktop and third-party applications.

Web server The API runs on a web server that is available to the public Internet. Your web

server and SQL Server can be on the same or separate machines.

Customers with 50+ users typically utilize separate machines.

SSL certificate This certificate is required to establish an encrypted link between your server and

the third-party application, to ensure the information remains private.

Tigerpaw Desktop Create at least one Tigerpaw rep record for each third-party application.

Authentication for third-party access to the REST API is provided through public

and private keys generated on these rep records.

Reps created for API processing do not log into Tigerpaw Desktop and therefore

do not consume user licenses.

Installation Checklist

This checklist guides you through the API installation and setup, including setup required in Tigerpaw

Desktop. The rep completing the web server steps must have administrative privileges on the server.

Setup Prerequisites

Follow these steps to prepare for the Tigerpaw API installation.

Setup Steps

___ 1. Contact Tigerpaw Technical Support to process your request for the download files.

NOTE: You will be asked to sign a non-disclosure agreement (NDA), if none is on file.


Setup Steps

___ 2. Verify your web server meets the minimum hardware and software requirements. The server

must be accessible from the public Internet.

Online Document: Server and Client System Requirements – Refer to the "Web Server

Requirements" section.

___ 3. When you receive the download link, extract the ZIP file to the web server or a network

location the server can access.

___ 4. Use one of these methods to create a domain name system (DNS) and register your API. This

process creates the URL for third-party applications to access the API.

Set up the domain at least 2 days before installing the API, to give the DNS changes time to

take effect.

Recommended method: Log into your domain registrar's account management

website and create a DNS host off an existing domain, e.g. api.yourwebsite.com.

Related Topic: Create an External DNS Host for the Tigerpaw API

Alternate method. Purchase a new domain from a domain registrar such as

GoDaddy®, InMotion, HostGator or Network Solutions®, e.g. yourAPIwebsite.com.

The value after the final period (such as .com or .academy) is called the top level domain

(TLD). Tigerpaw accepts TLDs up to 50 characters.

___ 5. The Tigerpaw REST API requires a secure socket layer (SSL) certificate.

Purchase a public SSL certificate from a trusted provider. Ask the provider (or search the IIS

Manager Help files) for instructions to request a certificate.

If you have a wildcard certificate, you do not need a separate SSL certificate for the Tigerpaw

REST API.

IMPORTANT: A self-signed certificate is not valid for this purpose.

Related Topic: REST API Installation Requirements – SSL requirements and information

about trusted providers.

___ 6. Download the SSL certificate file to the web server hosting the website. Ask the provider for

instructions to install the certificate. For additional information, go to

https://www.godaddy.com/help/request-an-ssl-certificate-562.

___ 7. Install the certificate on the web server and bind the SSL certificate to the website. For

additional information, go to https://www.godaddy.com/help/install-ssl-certificates-16623.

___ 8. Create firewall rules and/or port forwarding rules to open the port you will use to make the API

available to the public Internet. The default is port 443. If another site or service on your

network is using port 443, reserve a different port solely for the Tigerpaw API, such as 8443.

___ 9. If using a Let's Encrypt SSL certificate, create firewall rules and/or port forwarding rules to

open port 80. This port must remain open for Let's Encrypt to continue validating your

certificate.

https://support.tigerpawsoftware.com/QuickReferenceGuides/Server_and_Client_System_Requirements.pdf

https://www.godaddy.com/help/request-an-ssl-certificate-562

https://www.godaddy.com/help/install-ssl-certificates-16623


Setup Steps

___ 10. If you use Windows Firewall on the server running SQL Server, create firewall port exceptions

that grant access to SQL Server. Run the "New Inbound Rule Wizard" twice to create these

exceptions:

TCP – Port 1433

UDP – Port 1434

Related Topic: Create Port Exceptions for SQL Server on a Windows Firewall

NOTE: Skip this step if you do not run Windows Firewall on the server.

___ 11. Verify Internet Information Services (IIS) 7, 7.5 or 8 is installed on the web server.

___ 12. Follow the appropriate instructions to add role services for IIS. This step is critical to ensure

the API functions correctly.

Related Topics:

Add Role Services (IIS 7)


___ 13. Verify these frameworks are installed and operational:

Microsoft .NET Framework 3.5

Microsoft .NET Framework 4.5.1 (or higher)

NOTE: Windows Server 2012 and higher auto installs v4.5.1 or higher; v3.5 must be manually

installed, if not already on the machine.

Download and run the ".NET Version Detector" tool to quickly identify installed versions and

download required but missing versions from the Microsoft website.

Related Topic: .NET Version Detector – Detailed instructions to install and run this tool.

___ 14. Select "Roles" in the Server Manager and verify these services are enabled:

Static Content

ASP

.NET 4.5.1 or higher

ASP role

___ 15. Create a separate rep record in Tigerpaw Desktop for each third-party application accessing

the REST API.

Related Topic: Configure Tigerpaw for REST API Users

NOTE: Assign the appropriate security access to ensure the expected records are being

retrieved. For example, if the rep is denied access to the 'Can View Other Reps' Accounts'

permission in the Accounts category, the API may not pull all of the expected service orders.

___ 16. If the third-party application does not already exist as an external product, create an external

product record.

Menu bar > Edit > Master Tables > Accounts > External Products

Online Help Topic: External Products

https://userguide.tigerpawsoftware.com/Tigerpaw/Latest/_TSIGuide.htm#page/UserGuide/ExternalProducts.htm


Install the API

Complete these steps the first time you install the Tigerpaw API. Update instructions are slightly different.

Setup Steps

___ 17. Log into the server as a system administrator.

___ 18. Navigate to the extracted Tigerpaw REST API folder.

___ 19. Right-click the Tigerpaw REST API <version> Setup.exe file and select Run as Administrator.

WARNING: With SQL Server authentication, make sure the credentials have NO

semicolons. A semicolon in the SQL Login ID or Password breaks the web.config

connection string, and the API will be unable to log into your database.

Related Topic: Install the Tigerpaw REST API

___ 20. Configure the API.

Related Topic: Configure the REST API Web Service

___ 21. Browse to your API website through IIS or a web browser, if not already displayed, e.g.

https://api.yourcompany.com/docs/index.

___ 22. Make sure your site is accessible from the public Internet. Access your API website, e.g.

https://api.yourcompany.com/docs/index, from a device outside of your corporate network,

such as someone's home system or a smart phone that is not linked into your network.

CRITICAL: If you can access the site from your corporate network but not from a device

outside the network, something is set up incorrectly with the DNS, router port forwarding rules

or firewall. Check these settings or contact your Internet service provider for assistance.

The API works only if it is available to the public Internet.

.NET Version Detector

Follow these steps to quickly verify the .NET versions installed on your server and download required

versions that are not currently installed.

1. Download this link: https://support.tigerpawsoftware.com/Doc/NetVersionDetector.zip.

2. Right-click the downloaded file. Select Extract All and click .

3. Extract the file to a folder the web server can access.

4. While logged into the web server, open the extracted folder and click dotnet.exe. The ASoft .NET

Version Detector window displays.

https://support.tigerpawsoftware.com/Doc/NetVersionDetector.zip


In this example, the "3.5" text is white, indicating that version 3.5 is already installed.

5. If "3.5" or "4.x.x" is gray, click (Download this framework) for that version. The appropriate

Microsoft download page displays. Download and install the file per instructions on the Microsoft

page.

6. Click to verify the required versions are now installed.

7. Click (Close) to exit the window.


Follow these steps to set role services for the web server in IIS 7:

1. Log into the server as a system administrator.

2. Display server roles on the Server Manager: Start > Administrative Tools > Server Manager > Roles.

3. If the Web Server role is set up, continue to step 4. If this role is not set up, create the role:

Select Server Manager (left pane) and click Add Roles (right pane).

Follow the wizard prompts to create the role.

On the page to select role services, skip step 4 (below) and continue to step 5.


4. Select the Web Server role (left pane) > Add Role Services (right pane).

5. In the right pane, expand Web server and all related sub-options.

6. Select all checkboxes in Web server services.

IMPORTANT: This setup is critical to ensure the web portals function correctly.

We strongly recommend you also select all Management tools services and IIS Hostable web

core. The FTP server services are optional.

Select all options at both levels below Web server. Select IIS hostable web core and all options at both

levels below Management tools.

7. Click .

8. Click .

9. When the installation is complete, click .


Follow these steps to set role services for the web server in IIS 8:

1. Log into the server as a system administrator.

2. Display server roles on the Server Manager: Start > Server Manager > Manage > Add Roles and

Features > Server Selection.

3. If the Web Server role is set up, continue to step 4. If this role is not set up, create the role:

Click Server Roles and follow the wizard prompts to create the role.

On the page to select role services, skip step 4 (below) and continue to step 5.

4. Expand the Web Server role and select Role Services.

5. In the right pane, expand Web server and all related sub-options.

6. Select all checkboxes in Web server services.


IMPORTANT: This setup is critical to ensure the web portals function correctly.

We strongly recommend you also select all Management tools services and IIS Hostable web

core. The FTP server services are optional.

Select all options at both levels below Web server. Select IIS hostable web core and all options at both

levels below Management tools.

7. Click .

8. Click .

9. When the installation is complete, click .

Create an External DNS Host for the REST API

Follow these steps to create an external DNS host record for your API through your domain registrar,

such as InMotion or HostGator. Host records allow you to assign multiple sites to one IP address.

NOTE: These instructions are generic. Refer to your domain registrar's documentation for the specific

instructions and field names to complete these steps.

1. Log into your account with the domain registrar.

2. Display your domains.

3. Select the domain you will use for the API, such as yourcompanywebsite.com.

4. Display domain details.

5. Launch the DNS Manager.


6. Select the option to add a DNS record.

Your domain registrar may display this information in a different layout.

7. Set the Record type to A (Host).

8. Enter a Host name, such as "API".

9. Enter the external (public/routable), IP address for the server. To find this information, you must be

logged into the web server. Open a browser and Google what is my IP. The search results display

your public IP address.

10. Save the new DNS record.

The registered URL for your API website consists of hostname.website, such as

api.yourcompany.com.

11. Log out of the domain registrar's account management site.

Create Port Exceptions for SQL Server on a Windows Firewall

If you use Windows Firewall on the server running SQL Server, follow these steps to create TCP and

UDP port exceptions that allow access to SQL Server. Skip this setup if you do not run Windows Firewall

on the server.

1. Log into the SQL Server machine as an administrator.

SQL Server Configuration Manager

2. Open the SQL Server Configuration Manager.

3. In the left pane, expand SQL Server Network Configuration.

4. Expand Protocols for the TIGERPAW instance of SQL Server.

5. Double-click TCP/IP and select the IP Addresses tab. Several IP addresses appear in the

format IP1, IP2, up to IPAll. One of these is for the IP address of the loopback adapter,

127.0.0.1. Additional IP addresses appear for each IP Address on the computer.

Right-click each address and select Properties to identify the IP address you want to configure.


6. If TCP Dynamic Ports displays 0, indicating the Database Engine is listening on dynamic

ports, delete the 0.

7. Enter 1433 in TCP Port within the IPn Properties section. If another instance of SQL Server

is already using port 1433, enter an alternate port such as 1455.

8. Click .

9. In the left pane, click SQL Server Services.

10. Right-click SQL Server (TIGERPAW) in the details pane and select Restart to stop and

restart SQL Server.

11. Close the SQL Server Configuration Manager.

Windows Firewall

12. On the server, open Windows Firewall with Advanced Security.

13. Right-click Inbound Rules and select New Rule. The New Inbound Rule Wizard displays.

The Program rule type defaults.

14. Select Port.


15. Click .

When you finish updating TCP, you will repeat these steps for UDP.

16. Select TCP.

NOTE: The second time you run the wizard, select UDP.

17. Select Specific local ports and enter 1433 or the alternate port you entered in SQL Server

Configuration Manager.

NOTE: The second time you run the wizard (UDP), enter 1434 (or an alternate port if 1434 is already

in use).

18. Click .

The Allow the connection option defaults selected.

19. Verify Allow the connection is selected.

20. Click .

Initially all three options default selected.


21. Verify Domain is selected.

22. Uncheck Private and Public. The rule should apply only to the corporate domain.

23. Click Next.

The rule name should clearly identify the function or purpose of the rule.

24. Enter a unique and descriptive Name for the port exception rule, such as SQL <port number>

Allow.

25. Enter a Description for the port exception rule.

26. Click .

27. Return to step 3 to repeat this process for UDP.

The new rules display in the Inbound Rules grid.

Install the Tigerpaw REST API

Follow these steps to install the Tigerpaw REST API.

1. Log into the web server as a system administrator.

2. Navigate to the extracted folder titled Tigerpaw_REST_API New Install.


3. Right-click Tigerpaw REST API <version> Setup.exe and select Run as Administrator.

The Welcome page displays when the wizard is ready to run.

IMPORTANT: If your domain name, DNS and firewall are not set up, click Cancel to exit the

wizard and complete the required setup. Then restart the wizard.

4. Click . The License Agreement displays.

Scroll down to read the license agreement or click Print to read a print version.

5. After reading the end user license agreement, select I accept the terms of the license agreement.


6. Click . The API URL page displays.

The registered URL for your API website consists of the new website or hostname.website, such as api.tigerpawsoftware.com.

7. Enter the API URL for your Tigerpaw API.

8. Click . The Database Server page displays.

Information on this page logs you into SQL Server so you can create a SQL user the API will use to access your database.

9. Click beside Database server running Tigerpaw to select the database server.

10. Select the method for connecting to your database:

Windows authentication – Log into SQL Server with a valid network ID and password.


SQL Server authentication – Log into SQL Server with a valid existing SQL Login ID

and Password.

11. Click to select the Tigerpaw database name.

12. Click . The SQL User page displays.

The API will log into your database with this user name and password.

13. Enter a SQL User name you can easily identify when tracking logins via the API, such as "tsiAPI". This user ID grants the API access to the database.

WARNING: Do NOT enter the built-in "sa" user name, as it grants the user full security

access to everything on the server.

14. Enter a Password for the SQL User name. You can review or change the password in the API web.config file.

If the SQL user already exists, the installation wizard deletes/re-creates the user and assigns the

password entered on this page.


15. Click . The Installation Folder page displays.

We recommend you accept the default destination folder.

16. The default Destination folder is C:\inetpub\Tigerpaw_API. Click to select a different destination folder.

IMPORTANT: If you browse to a different folder, make sure the folder already exists and the

path includes the API installation folder name, such as Tigerpaw_API.

Do NOT install the API in the Tigerpaw Web Portal directory or a portal subdirectory.

17. Click . The Ready to Install page displays.

Click if you want to review or change settings.


18. Click to begin installing the API files. The Setup Status window displays.

Text above the status bar indicates the current step in the installation.

When the installation is complete, the Install Wizard Complete page displays.

Additional information displays if errors occurred and the installation was unsuccessful.

19. Click to close the wizard and launch the new API website.


Configure the REST API Web Service

Open the web.config file to configure the REST API for your environment. The rep completing these steps

must have administrative privileges on the web server.

Application Settings

Navigate to the <applicationSettings> element and enter the following values:

Setting Value

SearchMaxPageSize Limit the number of items returned from a search result. The

default value is 50.

NOTE: Increasing this value may cause performance issues.

DiagnosticsTracingTraceLevel Set the tracing level for the REST website:

Off – No messages.

Error – Error handling messages.

Warning – Error and warning messages.

Info – Error, warning and informational messages.

Verbose – All messages.

If logging is left on, especially in Verbose mode, the log files

can quickly consume hard drive space. We recommend you log

at the highest level possible to identify your issue. See

<system.diagnostics> initializeData for information on

configuring the location of the trace log file.

DefaultRESTAuthenticationTimeout Set the number of minutes to use when comparing the request

header date and time against the server date and time. If the

request date and time are out of range, it will be denied.

DocumentUploadPath Enter the physical path used to upload documents.

IMPORTANT: If you use the managed documents feature

in Tigerpaw, the DocumentUploadPath should match the Base

path on the Document and Scanning Options window in

Tigerpaw Desktop.

DocumentSharePath Enter the share path used to access the documents from the

upload location.

IMPORTANT: If you utilize managed document folders,

this value should match the DocumentUploadPath.


Examples of these settings are highlighted for emphasis:

<applicationSettings>

<Tsi.Service.Properties.Settings>

<setting name="SearchMaxPageSize" serializeAs="String">

<value>50</value>

</setting>

</Tsi.Service.Properties.Settings>

<Tsi.Web.Properties.Settings>

<setting name="DiagnosticsTracingTraceLevel" serializeAs="String">

<value>Off</value>

</setting>

<setting name="DefaultRESTAuthenticationTimeout" serializeAs="String">

<value>5</value>

</setting>

<setting name="DocumentUploadPath" serializeAs="String">

<value>C:\WebSites\WebApi\mobileuploads</value>

</setting>

<setting name="DocumentSharePath" serializeAs="String">

<value>\\Server\WebSites\WebApi\mobileuploads</value>

</setting>

</Tsi.Web.Properties.Settings>

</applicationSettings>

Connection Strings

Navigate to the <connectionstrings> element. Enter the following values for your test and live

databases:

Setting Value

SERVERNAME Replace this text with your server name.

DBNAME Replace with the database name.

USERNAME Replace with the SQL user name authorized to access the database. Tigerpaw

maintains an audit log of changes made to the API user information.

PASSWORD Replace with the SQL user's password.

In the following example, highlighted for emphasis, the test and live databases are on the same server

but have different users and passwords. In the web.config file, commented text above these lines

provides a baseline if you need to recreate the connection strings.

<connectionstrings>

<add name ="tsiCN" connectionString ="Data Source=myserver;Initial

Catalog=livedatabase;User ID=tsiAPI;Password=Ch0co!@teSyr^p;Persist

Security Info=True" providerName="System.Data.SqlClient" />

</connectionstrings>

System Diagnostics

Navigate to the <system.diagnostics> element and enter the following values:


Setting Value

switchValue Set a switchValue for each source listed in the section to provide logging of errors

and other information generated by the REST API.

Off – No messages.

Error – Error handling messages.

Warning – Error and warning messages.

Info – Error, warning and informational messages.

Verbose – All messages.

If logging is left on, especially in Verbose mode, the log files can quickly

consume hard drive space. We recommend you log at the highest level possible to

identify your issue.

initializeData Set the initializeData value to the location and name of the log files.

<sharedListeners>

TsiXmlListener – Custom error output to a log by Tigerpaw.

ServiceModelTraceListener – All other errors.

<trace> - Trace information from the REST API web site.

In the following example, highlighted for emphasis, the log files are configured to capture Error level

output and sets the log file location to a local drive on the server. Note that some of the configuration

information has been excluded here for clarity.


<system.diagnostics>

<sources>

<source name="Tsi.Web" switchValue="Error">

...

</source>

<source name="Tsi.Service" switchValue="Error">

...

</source>

<source name="System.ServiceModel.MessageLogging" switchValue="Error">

...

</source>

<source name="System.ServiceModel" switchValue="Error">

...

</source>

<source name="System.Runtime.Serialization" switchValue="Error">

...

</source>

</sources>

<sharedListeners>

<add name="TsiXmlListener" initializeData="c:\WebSites\WebApi\log\Tsi_Web.svclog" type="System.Diagnostics.XmlWriterTraceListener, System, Version=4.0.0.0, Culture=neutral,

PublicKeyToken=b77a5c561934e089" traceOutputOptions="Timestamp" />

<add name="ServiceModelTraceListener" initializeData="c:\WebSites\WebApi\log\Tsi_Service.svclog"

type="System.Diagnostics.XmlWriterTraceListener, System, Version=4.0.0.0, Culture=neutral,

PublicKeyToken=b77a5c561934e089" traceOutputOptions="Timestamp" />

</sharedListeners>

<trace autoflush="false" indentsize="4">

<listeners>

<add initializeData="c:\WebSites\WebApi\log\Tsi_Diagnostics.svclog" type="System.Diagnostics.XmlWriterTraceListener, System, Version=4.0.0.0, Culture=neutral,

PublicKeyToken=b77a5c561934e089" name="TraceServiceModelTraceListener"

traceOutputOptions="Timestamp" />

</listeners>

</trace>

</system.diagnostics>

Configure Tigerpaw for REST API Users

Third-party applications connect to the REST API through API users. REST API users are completely

separate from the RMM API users, which are created with the Tigerpaw RMM API Users Utility.

REST API users are set up as reps in Tigerpaw Desktop. However, they can only access the API. All rep

records in Tigerpaw must be assigned at least one security role and one rep group. Assign the "System

Administrator" security role to users set up for the REST API.

Reps created for API processing do not consume user licenses, so long as you use the rep ID

only for automated processes and do not log in with it.

Consider creating a separate rep group for API users, such as a "REST API" or "API Users" group.

System-generated keys on the API user rep record provide authentication for third-party access to the

API.

Public key – Used by the API to identify the third-party application.

Private key – Used by the third-party application to encrypt communications with the API.

IMPORTANT: Protect the Private key as you would a password.


Follow these steps to create a separate rep profile for each third-party application, plus profiles to use for

development and testing purposes.

1. Open Tigerpaw Desktop main window.

2. Connect to the database the API is configured to use. If the database is not listed in the navigation

menu, click and navigate to the database.

3. Log into the selected database. You must be a Tigerpaw system administrator.

4. Select Menu bar > Edit > Master Tables > Reps > Account Reps > (New).

5. Enter a Rep name that identifies the third-party application, such as first name "<third-party

product>" and last name "Integration".

6. In Email1 on the Contact Info tab, enter a valid email address that exists on your mail server, such as

[email protected].

7. On the Roles & Groups tab, click (Assign security role) and assign the System Administrator role.

8. Click (Assign rep groups) and assign a rep group.

9. Click (Save and exit).

10. Redisplay the rep record you just created.

11. Open the Admin tab.

The REST API fields display at the bottom right of the tab.

12. Click .

13. Copy the Public key and Private key values and send them to the third-party developers. These

values grant the rep access the Tigerpaw REST API.

NOTE: If you need change the keys for an existing API user, click to create new values. Give

the keys to the third-party developers, who will update their application with the new values.

tigerpaw rest api installation checklist and...

Documents