BookmarkBookmark this page!
Oct 1, 2024
Syrinx 365 | Syrinx 365 API Installation

This article will cover the installation of the Syrinx 365 API which is a core server component of the Syrinx 365 system.

  

Topics included in this article

 

Prerequisites

  • Syrinx AppInstaller – The latest version of this program should be downloaded onto the server that will be hosting the Syrinx 365 API. The AppInstaller’s download location is available in the AppInstaller Installation and Upgrade guide.

  • DB_Patch_365_accountno.syp – A patch containing connection security information. Only required for new installations. The patch should be applied to the Syrinx database prior to the installation.
        
  • Patch_365_accountno.syp – A patch containing the Syrinx 365 license information. Only required for new installations. The patch should be applied to the Syrinx database prior to the installation.
      
  • DB_365_accountno_dbname.json – A .json file containing connection information for the SQS listeners.  This .json file will be used later in the installation process. 

 

Note: The accountno and dbname values referenced in the above filenames are a customer’s specific account number and database name.

 

Installation

To begin the Syrinx 365 API installation, select it from the list of available programs in the Syrinx AppInstaller and press the “Install” button at the bottom of the screen:

 

 

After the AppInstaller finishes installing/configuring any required components such as Internet Information Services and the .Net Core 6.x Windows Server Hosting Package, the user will be presented with the following installation options:

 

The following table details those specific options:

Select Website:

Select which website on the web server should host the Syrinx 365 API site. This should normally be left as the default setting “Default Web Site”.

Application Name:

This allows you to override the name of the Syrinx 365 API site. The default setting, “Syrinx365Api,” should normally be left. 

DB Name:

Enter the database name for the Syrinx database. e.g. SyrinxDM

Server Name:

Enter the name of the server that hosts the Syrinx database. The default setting, “(local),” is only applicable if the database is running on a default SQL instance on the web server and will, in most cases, need to be amended with the actual SQL server instance name of the Syrinx database server.

Android Server Url:

Enter the URL for the existing installation of the Syrinx Mobile Web service.  This should normally be left as the default setting if the Syrinx Mobile Web service is running under the default website and listening on the default HTTP port (TCP port 80) on the web server.

Enable Logging?:

Tick this option to enable logging on Syrinx 365 Api site.  This is disabled by default, as the logs will run continuously and will not be overwritten or deleted unless someone does this manually.  Logging can be enabled/disabled at a later point in time simply by amending the “stdoutLogEnabled” value to true (enabled) or false (disabled) in the site's web.config file found in the site's installation directory (e.g., C:\inetpub\wwwroot\Syrinx365Api) and then restarting the application pool in IIS.

 

After selecting the appropriate installation options, press the “Install” button to begin the installation.  No further input is required and the “Syrinx 365 API” installation option will move to the “Installed” tab of the AppInstaller once the installation is complete.

 

*Please note, the server may need to be restarted following the installation before all components begin working properly.

 

Load SQS Listener File

Now that the initial stage of the installation is complete, the SQS connection JSON file (e.g., DB_365_accountno_dbname.json) will need to be copied into the C:\inetpub\wwwroot\Syrinx365Api\Files\js\Listeners folder (or the equivalent directory if the site was installed into an alternative location) for the Syrinx365Api site.  

 

Once the .json file has been copied into the appropriate directory, the Windows service “Syrinx Queue Service” should be restarted to pick up the file and establish the connection to the global database and the Syrinx database.

 

Configure Virtual Directories

If the 365 API installation is to be used with Ecomm, virtual directories must be created against the Syrinx365Api site in IIS for document retrieval from the system:

 

 

The following table details the specific virtual directories. The source for each directory can vary from system to system. The specific paths to these locations can be found in the 365 Desktop via Config\Documents\Root Folders:

 

Directory Name

Source

CRDocs

Custom documents folder

Advice Note Docs

Advice note documents folder

Contract Docs

Hire Contract documents folder

Mobile Images

Mobile Images folder

Ref Docs

The root folder containing all document folders (e.g. SQLDataSP\Docs)

Scanned Docs

Scanned Documents folder

Signatures

Mobile Images folder

 

On some systems, it may also be necessary to grant the IIS_IUSRS groups Read security permissions to the C:\Windows\System32\inetsrv\config directory so that the application pool has visibility of the virtual directories.

  

Testing the Installation

Upon successful completion of the installation, the URL for the Syrinx 365 API’s swagger page (e.g., http://localhost/Syrinx365Api/index.html) should be copied into a web browser such as Chrome, Edge, etc. If the installation was successful, this should open a “Swagger” page as per the below:

 

 

Below are examples of common errors when accessing the Swagger page and their probable causes:

 

HTTP Error 502.5

Process Failure: Incorrect settings in the appsettings.json configuration file, such as DB connection details.   If the defaults were accepted during installation, the appsettings.json configuration would be found in the root of the website directory C:\inetpub\wwwroot\Syrinx365Api. For example, named Instances need to be entered as servername\\instancename (backslash characters need to be escaped, i.e., \\ instead of \).  

 

HTTP Error 404.0 - Not Found

 Incorrect URL for the Swagger page. The default is http://localhost/Syrinx365Api/index.html, but it can be different depending on the options selected during installation.

 

HTTP Error 500.19 - Internal Server Error

 The requested page cannot be accessed because the related configuration data for the page is invalid.  – The Syrinx 365 API relies on the  “ASP.NET Core Runtime 6.x.x hosting bundle”. If this is not installed, you may get the following error when trying to connect to the Swagger page. The installer should install this component during installation if it has not been installed already. However, the latest version of the .Net Core v6 hosting bundle can also be downloaded from Microsoft and installed as a stand-alone package.

 

HTTP Error 503 - Service Unavailable

If this error is being displayed and the Syrinx 365 API web service is stopping when you try to access the Swagger page, and you are receiving an IIS-W3SVC-WP error in Windows event viewer with details “The Module DLL C:\Program Files\IIS\Asp.Net Core Module\V2\aspnetcorev2.dll failed to load. The data is the error.”:

 

This may indicate that the web server is missing the “Microsoft Visual C++ 2015 - 2022 Redistributable” package. If it has not been installed already, the installer should install this component during installation, but it can also be downloaded from Microsoft and installed as a stand-alone package.

 

Amending Configuration Settings

Incorrect settings in the configurable areas of the Syrinx 365 API website’s appsettings.json file can cause the Syrinx 365 API web service to not function correctly.  If there are issues with the site, the appsettings.json file in the root of the Syrinx 365 API web service directory (e.g., C:\inetpub\wwwroot\Syrinx365Api) should be checked to verify that the settings are accurate. The “ServerSettings” area of the appsettings.json file is set during the installation using the answers provided on the “Syrinx 365 API Configuration” screen of the AppInstaller and can be amended manually as follows:

 

Database username and password: The default V5User SQL user is added to a Syrinx database/SQL instance when the system is upgraded to Syrinx version 4.37.5 or higher. You can check that these details are correct by attempting to connect to the database via a different Syrinx program or the Windows ODBC Data Source Administrator with this username and password. The service can run under any valid SQL username/password that has been granted access to the Syrinx database.  It uses this information to get database and user information and then passes that to the Global database or the Syrinx 365 Desktop. If this login information is incorrect, you may see an “Exception in Organisation Service -Login failed for user 'v5User’” message in the site’s log files:

 

mainDatabaseName and mainServerName:  These should be set to the Syrinx database name and the name of the server hosting the Syrinx database. This information can be collected by looking at the existing connection settings for users when they access the Syrinx database via the Syrinx client. As mentioned above, named instances should be entered as “servername\\instancename” as backslashes require an escape character in .json files (i.e., \\ instead of \).   Database connection settings can also be checked by attempting to establish a 32-bit ODBC connection from the web server to the database server using the server/database name values found in the appsettings.json file.

 

DefaultWebApiBaseUrl: This is the URL to the existing Syrinx Mobile Service. The accuracy of this URL can be checked by attempting to access the test page of the Mobile Service by appending the text “checkconnection“ to the URL and then attempting to browse to that URL in a browser (e.g., http://localhost/SyrinxAndroidService/api/syrinx/checkconnection). If you get the following pages (Depending on the browser), it means that the URL for the existing Syrinx Mobile Service has been set correctly:

 

Chrome:

               

 

Internet Explorer (at the bottom of the window):

               

 

FireFox:

               

 

Additional Troubleshooting Resources

If logging has been enabled manually or during the installation, the log files held in C:\inetpub\wwwroot\Syrinx365Api\logs (if installed to the default location) may provide information on the nature of an error. There will be a single aspnetcore-debug.log file that can detail ASP.Net errors, and there can be multiple stdout_xxxxxxxxxx_xxx.log files that can detail errors or exceptions encountered during the API’s operation.

 

More detailed logging can also be enabled by amending the appsettings.json file and setting the “Console” set to “Debug” (The default is “Error,” which means that it will only output error messages:

 

Any errors encountered by the “Syrinx Queue Service” when communicating with the Global database can be logged in Windows Event Viewer and may also be visible in its log files folder, C:\ProgramData\Higher Concept\Syrinx Queue Service\logs.

Trending Articles

Was this article helpful?
Upload Files