PowerShell

The PowerShell scripts require a minimum level of version 5.0, which was released in 2017. Any version of Windows released since then includes it or a later version. If the installed version of PowerShell is lower than 5.0, the latest version can be obtained from the Microsoft Store or from the Microsoft web site. The installed version of PowerShell can be determined by executing $psVersionTable in a PowerShell session.

Before running the PowerShell scripts, the host computer's PowerShell execution policy must be set to permit script execution. -RemoteSigned is recommended. The current execution policy can be verified with the Get-ExecutionPolicy command. It should not be Restricted. It can be changed with the Set-ExecutionPolicy command from an administrative PowerShell session (e.g. Set-ExecutionPolicy RemoteSigned).

If you do not have a standard PowerShell environment, with a default scripts folder set up, then it will be necessary to execute the provided PowerShell scripts from their installation folder and prefix the commands with ".\". If there is a default scripts folder, consider copying the SimTransIF PowerShell commands to it and executing them in the same way as any other PowerShell command or script.

.Net

The SimTransIF server requires the .Net 5.0 hosting bundle or later. It must be installed before the server. The latest version of .Net can be obtains from the Microsoft .Net web site.

The .Net client libraries are built to .Net Standard 2.0. In practice, this means the minimum .Net level a client can be built to is .Net Framework 4.6.1 (4.7.2 is the recommended minimum) or .Net Core 2.0 (3.1 is the recommended minimum).

Use the [System.Environment]::Version PowerShell command to determine if .Net 5 or later is installed. The "Major" column will be 5 or higher.

JavaScript

If using the JavaScript client interface, the minimum level required is ECMAScript 2015. In the event that an older version of JavaScript must be used, adapt WebClient.js to the requirements of the available JavaScript version.

To install the server:

1. Create a temporary Installation folder and place the SimTransIF.zip file in it.
2. Copy the contents of SimTransIF.zip into the root of the installation folder.
3. Open a PowerShell session as an administrator and navigate to the Installation folder.
4. If this is an initial installation of the server:
   1. Run: .\Install-SimTransIfServer Server.zip Config.zip.
   2. Refer to the Configuration section, below, to set the server configuration parameters.
5. If this is an update to the server, run: .\Install-SimTransIfServer Server.zip.
6. Start the server:
   • In a PowerShell session execute: Start-Service SimTransIF.Server or
   • From the Start menu, find Services, locate the SimTransIF service and start it.

The server installs into \Program Files\SAWaves\SimTransIF\Server on the current volume. If a different location is required, add the -InstallPath parameter to the installation script that specifies the desired location.

To remove the server, run: Remove-SimTransIfServer. If it is not installed in the default location, then specify the -InstallPath parameter to specify where it can be found. To also remove its configuration, specify the -Config parameter.

There are two .json configuration files located in \ProgramData\SAWaves\SimTransIF. They can be modified with any standard text editor, such as Visual Studio Code. Settings are simple and few in number.

host.json

These are the sections of the configuration file that are of primary interest:

"AllowedHosts": "*",
"urls":  "http://*:5070;https://*:5071",
"Kestrel": {
    "Certificates": {
        "Default": {
            "Location": "LocalMachine",
            "Store": "My",
            "Subject": "{certificateSubject}",
            "AllowInvalid": true
        }
    }
}                        
                            

In most cases very little needs to change. The most common and likely change is the {certificateSubject} that must be replaced with the contents of the HTTPS SSL certificate's subject field, minus the "CN=". If using a default, self-signed certificate, this value will be the server computer's name or the value that was specified on the -Domain parameter when the certificates were created—see the SSL Certificate section. If using a purchased SSL certificate, use the Certificates management console plug-in or the PowerShell Get-ChildItem -Path cert:\LocalMachine\My… command to view the certificate and determine its subject.

If everything is on a private network and only the HTTP protocol is used, then remove the ;https://*:5071 from the urls entry and remove the whole Kestrel section.

If TCP/IP ports 5070 and 5071 are in use on the server, then replace these values with port numbers that are not in use. One of the new port numbers must also be entered in the ClientSettings section of the client's configuration.

By default, the server will respond to any request on the selected ports on the server. If it is required that the server only listen on the standard ports (80 and 443) and there are other web servers using those ports on the server, then it is also necessary to specify the host name in the AllowedHosts section. For example, if the server also hosts a web site on www.domain.com and domain.com and the SimTransIF server must use standard ports and only respond to api.domain.com, then enter that in the AllowedHosts field.

config.json

Config.json has three sections:

ConnectionStrings

This is where the connection string to the SigmaNEST database, that SimTrans is using, is specified.

ClientSettings

A copy of the same configuration file can be used for a SimTransIF client, in which case only this section is used and the others are ignored. Conversely, this section is ignored on the server. Even if a different configuration file is used or the parameters are hard-coded into the client, this section specifies the required parameters.

URI

This is the URI of the server where the SimTransIF server is installed. It must include the protocol and port.

SharedId

This is the same GUID that is specified in the ServerSettings section on the server. It is required to ensure that security tokens on each request are generated and validated correctly.

ServerSettings

The following are required settings for the server:

SharedId

This is a GUID that is used to ensure the same security tokens are generated and validated on the server and the client and that they are unique to this installation. Unless a client knows this server's GUID, the server rejects all traffic from the client, because its security tokens can not be valid. Generate a new GUID on installation and place it here. A GUID can be created by executing the New-Guid Powershell command. Use Ctrl+Shift+C to copy onto the clipboard from a PowerShell session.

ReadAndDelete

When obtaining feedback from SimTrans, the server can be configured to automatically delete the feedback items after retrieving them. In this case, the client only needs to retrieve the feedback and the same items will not be returned more than once. However, if there is an error in the client, the feedback may not be processed correctly and it is then lost. For these reason, this parameter defaults to false. When it is false, the client must explicitly send a delete request to the server in order to delete the items it has retrieved, after it has processed them correctly.

AlwaysUseHttps

When set to true, the encrypted HTTPS protocol is always used. If an un-encrypted HTTP request is received, it is converted into HTTPS and the result is encrypted. An SSL certificate must be configured if it is true. The default is false.

To also remove the configuration when removing the client or server, specify the -Config parameter on the client or server installation script. (e.g. Remove-SimTransIfServer -Config or Remove-SimTransIfClient -Config).

SSL Certificate

In order to use the HTTPS (SSL) protocol for an encrypted connection between the client and the server an SSL certificate is required. The location of the certificate to use is specified in the host.json file.

HTTPS is always the preferred protocol, but HTTP is reasonable to use on a private network. If the network connection is across a public network, an SSL certificate from a reputable provider is recommended. However, for testing and some production purposes a self-signed certificate may be acceptable. A PowerShell script is provided to simplify the creation of a self-signed certificate.

For testing use: New-SimTransIfCertificate -PrivateKeyPassword {strongPassword}. It will create a self-signed trusted root CA certificate and an SSL certificate that are valid for 2 years for the current machine name and localhost.

To specify something other than the local machine's DNS name use: New-SimTransIfCertificate -PrivateKeyPassword {strongPassword} -Domain {machine.domain.com}. Localhost is always automatically added to facilitate local testing. It also creates RootCertificate and Certificate files in .pfx and .cer format in the file system. To have the certificate files placed somewhere other than the current folder, specify the -Path parameter. The .pfx files include the private key and are, therefore, password protected. The .cer files only contain the corresponding public keys.

In order to use a self-signed certificate, the RootCertificate.cer file must be transferred to the client computer and imported into its local computer Trusted Root Certification Authorities folder.

To remove the self-signed certificates, use: Remove-SimTransIfCertificate.

To install the client:

1. Create a temporary Installation folder and place the SimTransIF.zip file in it.
2. Copy the contents of SimTransIF.zip into the root of the installation folder.
3. Open a PowerShell session as an administrator and navigate to the Installation folder.
4. If this is an initial installation of the client and the distributed configuration files are required:
   1. Run: .\Install-SimTransIfClient Client.zip Config.zip.
   2. Refer to the Configuration section, below, to set the client configuration parameters.
5. If this is an update to the client or the distributed configuration files are not required, because the client uses a different configuration mechanism or hard-codes the required parameters, run: .\Install-SimTransIfClient Client.zip.

The client installs into \Program Files\SAWaves\SimTransIF\Client on the current volume. If a different location is required, add the -InstallPath parameter to the installation script that specifies the desired location.

The .Net DLL's are located in a bin sub-folder and the JavaScript and TypeScript modules are located in a js sub-folder.

It may not be necessary, or even desireable to install the client, especially if working with the JavaScript client. In that case, simply open the client.zip file and copy the DLL's or modules to where they are needed.

To remove the client, run: Remove-SimTransIfClient. If it is not installed in the default location, then specify the -InstallPath parameter to specify where it can be found. To also remove its configuration, specify the -Config parameter.