Prerequisites

Before installing the Syrinx 365 API, the Syrinx database should be upgraded to Syrinx version 4.38.1 or greater.  If the customer is going to be using the POR One app, the Syrinx Mobile Service should already be installed and configured on a server running IIS within the network and the Syrinx 365 API should be installed on the same web server that is hosting the Syrinx Mobile Service or, at minimum, installed on a server that has access to the Syrinx Mobile Service from within the internal network.  The following files generated for the customer’s database should be supplied prior to installation (accountno is the customer’s specific account number and dbname is the name of the customer’s Syrinx database):

• DB_Patch_365_accountno.syp - A patch containing connection security information.  The patch should be applied to the customer’s database prior to the installation.
• Patch_365_accountno.syp – A patch containing the customer’s Syrinx365 license information.  If the Syinx365 API is being installed solely to provide access for the POR ONE mobile apps to the Syrinx database, this patch is not required.
• 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.  

This guide will not cover upgrading a Syrinx database or installing the Syrinx Mobile Service.  

Installing the Syrinx 365 API Web Service

The current version of the Syrinx Mobile Web Service can be downloaded from the following location:

http://www.syrinxusers.co.uk:443/Syrinx%20365/Syrinx%20365%20Api%20Installer.exe

username: download

password: c0nc3pt

Once downloaded, run the installer and press the “Install” button when prompted and then press “Next” on the subsequent installation screen:

Then, select the “Install” option when prompted for the “Setup Type”:

Next, enter the configuration information for the Syrinx 365 API site:

Finally, click the “Next” button to begin the installation:

The installer will make the appropriate system changes and advise when finished.  When complete, the installer will advise on the URL used to connect to the Swagger utility on the Syrinx 365 Api site and will automatically copy this into the clipboard for testing purposes.  Click the “Finish” button to complete the installation:

*Please note that the web server may need to be restarted following the installation of the "Microsoft .NET Core 3.1.2 - Windows Server Hosting" package (or “Microsoft .Net 6.0.9” when installing later versions) if it was not previously installed on the web server and was installed during this installation process.

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.  If running Syrinx 4.40.6 or earlier, the Syrinx365API application pool should be restarted after this is complete so that the site can then load the details for the SQS listeners specific to the customer’s database.  If running Syrinx 4.41.0 or later, the windows service “Syrinx Queue Service” should be restarted to pick up the file and establish the connection to AWS and the Syrinx database.

Upon successful completion of the installation, the Web API URl (e.g.: http://localhost/Syrinx365Api/index.html) presented at the end of the installation 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:

Browsing and loading the Swagger page also starts the SQS Listeners and effectively starts the API so that it can begin receiving communications for Syrinx365 or the POR ONE apps via AWS.

Create Scheduled Task to Start SQS Listeners on System Restart

*This step is not required if installing Syrinx365Api 1.16.0 for Syrinx 4.41 or later as the SQS listener component is installed as a windows service and no longer runs through IIS.

Run the following command from a command prompt run as Administrator in order to create a scheduled task that will call the 365API swagger page when the system restarts in order to restart the SQS listeners:

schtasks /create /tn "Start SQS Listeners" /tr "powershell -ExecutionPolicy Bypass -Command Invoke-WebRequest 'http://localhost/Syrinx365Api/index.html' -UseBasicParsing" /sc ONSTART /ru System

*Before running the command, verify that the URL for the swagger page is correct for the specific system and update accordingly if it isn’t

Additional Configuration Requirements for Ecommerce

If Ecommerce is also being enabled for a customer’s system the following will also need to be configured during the Syrinx 365 API installation:

• Grant IIS_IUSRS group read & execute privileges to the C:\Windows\System32\inetsrv\config directory so that .Net Core can access virtual directories on the Syrinx365Api site
• Update the Crystal Documents held in C:\inetpub\wwwroot\Syrinx365Api\CRDocs so that they match the format of the documents used by the customer (e.g. Add headers, address info, etc.)
• Create virtual directories under the Syrinx365Api\Documents directory in IIS that mimic the virtual directories set up under SyrinxCWS\Documents (e.g. Advice Note Docs, Contract Docs, Ref Docs, etc.) and set the appropriate windows account against those directories and the Syrinx365Api application pool so that the site can access those shared directories (if hosted on a separate file server) as Ecommerce provides similar document download functionality as SyrinxCWS

*The SQL Server Instance needs to be SQL 2012 or later for the system to be linked to Ecommerce

Common Browser Error Codes When Accessing Swagger Page and 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 will 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 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 3.1.2 hosting bundle” or “ASP.NET Core Runtime 6.0.9 hosting bundle” if installing for Syrinx 4.40.5 or later.  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 but it 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 eventviewer 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 Redistributable” package.  The installer should install this component during installation if it has not been installed already but it can also be downloaded from Microsoft and installed as a stand-alone package.

Amending Configuration Settings in the Appsettings.json File

As mentioned above, incorrect settings in the configurable areas of the 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 are set during the installation using the answers provided on the “Website Configuration” screen of the installer and can be amended manually as follows:

Database username and password: The V5User sql user is patched into the 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 Syrinx SP or Syrinx SP Configuration program 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 pass that to the Global Organisation Service hosted in AWS.  If this logon 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 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 default location) may provide information on the nature of an error.  For example, when the service first starts, it will attempt to register/verify the company and databases against the POR Global database hosted in AWS.  If the database has not been updated to 4.38 or later, the logs may display an “Object reference not set to an instance of an object.” message when attempting to register the database with the Global Organisation Service:

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

With this enabled, it is possible to then see the calls happening between AWS and the Syrinx 365 API (and the Syrinx Android Service if installed for use with the POR One apps):

This can be useful in determining whether or not the Syrinx 365 API is actively communicating with AWS.  Recycling the application pool will also force the Syrinx 365 API to create a new log file.

*If running Syrinx365Api v. 1.16  for Syrinx 4.41 or later, any errors encountered by the new “Syrinx Queue Service” when communicating with AWS will be logged in windows event viewer and will not be in the Syrinx365Api logs.

Note – The log files will be much larger with this option enabled so it should be reset to the default “Error” setting once troubleshooting is complete.

The service may also provide status messages in the “v5-api-log.txt” file found in the root of the Syrinx 365 API web service directory (e.g.: C:\inetpub\wwwroot\Syrinx365Api):

Syrinx 365 Desktop Installation

The current Syrinx 365 Desktop installer can be downloaded from the following location and should match the version of the installed instance of the Syrinx 365 Api:

http://www.syrinxusers.co.uk:443/Syrinx 365/Syrinx 365 Desktop Setup.exe

username: download

password: c0nc3pt

The installer simply needs to be run on the requied clients PCs.  The only input required during the install process is the URL for the Syrinx 365 Api (e.g. http://servername/Syrinx365Api/api/v2):

Once the installer has completed the URL for the Syrinx 365 Api can also be manually set in the “appSettings.json” file found in C:\ProgramData\Higher Concept\Syrinx 365 Desktop\resources.