Action disabled: source

1 - RQuest Third Party Service Integration software overview

The link between RQuest and Smart Suite is comprised of the RQuest Agent and the Smart Suite TPSI. The acronym TPSI stands for Third Party Service Integration. From the viewpoint of RQuest any “service” that RQuest can interface with is a Third Party Service.

This manual only describes the Smart Suite TPSI. The RQuest Agent installation is described elsewhere.

2 - Prerequisites

2.1 - Software

The TPSI distribution at the time of writing consists of a ZIP file with the software. You will need to download and install ODBC drivers and its prerequisites for the database of choice. Note that you will need the 64-bit version of the software.

Oracle Database If the Smart Suite database is an Oracle database, you will need to install the Oracle Instant Client and the ODBC drivers. You will also need to install the Visual C++ 2013 x64 C Runtime listed below.

For download links and installation instructions please go to:
https://www.oracle.com/technetwork/database/database-technologies/instant-client/overview/index.html
Download Instant Client and ODBC drivers:
https://www.oracle.com/technetwork/topics/winx64soft-089540.html
Installation Instructions for the ODBC drivers:
https://www.oracle.com/technetwork/database/features/oci/odbc-ic-releasenotes-094306.html

Requires: Visual C++ 2013 x64 C Runtime available at:
https://support.microsoft.com/en-us/help/3179560

Microsoft SQL Server If the Smart Suite database is a Microsoft SQL Server database, you will need to install the the ODBC drivers. You will also need to install the Visual C++ 2017 x64 C Runtime listed below.

For download links and installation instructions please go to:
https://docs.microsoft.com/en-us/sql/connect/odbc/microsoft-odbc-driver-for-sql-server?view=sql-server-2017
and
https://www.microsoft.com/en-us/download/details.aspx?id=56567

Requires: Visual C++ 2017 x64 C Runtime available at:
https://support.microsoft.com/en-ca/help/2977003/the-latest-supported-visual-c-downloads

For Support and Troubleshooting Each TPSI service has a small SQLite database with settings. To have a look at the contents of the database, you will need a tool like Database Browser for SQLite, available at the URL below. Please use the 64-bit version. https://sqlitebrowser.org/dl/ Some of the sensitive settings in the database are encrypted and are only useful on the server that the program created the database on.

Command line parameters are available to show configuration specifics. Use –help to show available options.

2.2 - Environment

Before starting with the installation, you will need to setup the environment. This requires enabling ports for Events and REST API on all Smart Suite servers that you want to install the RQuest Agent and TPSI services on. For consistency, security, availability and performance reasons it is best to install the RQuest Agent and TPSI services on all servers that run Power Server. Event Port Number: You will need to enable the Event integration and take note of the port number.

To enable the Event service start Power Server Management Console and navigate to Server Configuration – Services. Select the HTTP service and check Activate this service as shown above. The default port number is 30980. If the service was not enabled, you will need to restart the Power Server before you can take note of the Event Host name and REST API Host name.

REST API Port Number: You will need to enable the REST API and take note of the port number.

To enable the REST API start Power Server Management Console and navigate to Server Configuration – Services. Select the REST API service and check Activate this service as shown above. The default port number is 5181. If the service was not enabled, you will need to restart the Power Server before you can take note of the Event Host name and REST API Host name.

Event Host Name and REST API Host Name: Start the Power Server Management Console and navigate to Monitor. Select the Services from the four available choices. In Service endpoints panel in the highlighted area at the bottom you will find the OData section listing an URL with the hostname and port number for the REST API, and the OVSD section listing a URL with the hostname and port number for the Event integration. Both URLs start with http. You will need to check these settings on each Power Server instance.

3 - Credentials

You might need any of the credentials below to setup connections. When configuring a TPSI service, the service will ask for specific credentials.

Oracle Database The assumption at time of writing is that there are two accounts for Oracle. One for the Data and one for the Repository. It is recommended to use a read-only account for the TPSI services that require database access. You will need the following: - read-only username and password - “data” user name - “repo” user name as well as: - database server name - database instance or service name - database port (default : 1521)

SQL Server Database You will need the following: - user name with at least read access to the Smart Suite database and password and - database server name - database name - database port or - ODBC System DSN name. Setup of a System DSN for SQL Server is not part of this document.

Smart Suite For the Event interface you will need an application user account with access to Smart Suite. - event interface user name - event interface password

4 - ODBC Driver Installation

4.1 - Oracle

Navigate to directory where you have downloaded the Oracle software. The version numbers might not be the same as shown.

Run Extract All on both files.

Select a directory to extract the Instant Client software, e.g. C:\oracle. This needs to be the same for both extractions.

You will get prompted when running the second Extract all.

After successful extraction of both files you will need to navigate to the instant client subdirectory, and locate the odbc_install.exe program. Run the script to install the drivers. If you want to see the output, you will need to run the script using an elevated command line.

Confirm the Open File - Security Warning by selecting Run. (This does not appear when you run the script from the command line)

If installation was successful, you will see the Oracle ODBC driver entry in the list of Drivers in the ODBC Data Source Administrator. The ODBC Data Source Administrator is part of Windows.

Install the required Visual C++ 2013 x64 C Runtime software. To make sure you have the right distribution, check the Details tab on the vcredist_x64.exe file. It should look similar to the one on the right.

4.2 - Microsoft SQL Server

Locate the download and start it. Accept the Open File- Security Warning

Click Next.

Select I accept the terms in the license agreement.

Click Next.

Click Install

Click Finish

The ODBC Driver should now be available in the list of drivers. The TPSI will support use of a System DSN in the connection definition for a SQL Server database. We will create a System DSN shortly.

Install the required Microsoft Visual C++ 2017 x64 C Runtime software. To make sure you have the right distribution, check the Details tab on the VC_redist.x64.exe file. It should look similar to the one on the right.

Click Windows Start, and type ODBC You might find that there are two versions of the ODBC Administrator, a 32-bit and a 64-bit version. We have noticed that there are sometimes issues when testing connectivity to the configured SQL Server database. In the example below we are using the 64-bit version. You might need to use the 32-bit version or defer testing the database connection. So, start the ODBC Administrator. Navigate to the System DSN tab. Click Add.

From the available drivers select the ODBC Driver 17 for SQL Server. (This list looks vastly different in the 32-bit version of the program) Click Finish

In the “Create a New Data Source for SQL Server” wizard, fill in Name, Description and the name of the server where the Smart Suite database resides. Click Next.

Select the option “With SQL Server authentication using a login ID and password entered by the user. Fill in Login ID and Password. Note: The password is not stored, but only used to test the connection. Click Next.

Accept default settings and click Next.

Again, accept default settings and click Finish

You are shown a summary. Click the Test Data Source … button at the bottom of the screen to test the connection.

When configured correctly, the Test Results should show successful completion. If configuration fails, take note of the error message. In some cases you might want to disregard the failed test and continue.

Click OK until you are back in the ODBC Data Source Administrator window in the System DSN tab, where the newly created System Data Source should be listed.

5 - Smart Suite Configuration

In order to have Smart Suite work with RQuest some of the configuration possibilities of Smart Suite need to be setup. Below is a step by step description of what needs to be added in the Smart Suite admin to make the link between RQuest and Smart Suite possible.

5.1 - Custom Fields

Create a new custom field name DUE_UUID for the Service call entity.

Create a new custom field name RQUEST-ID for the Service call entity.

5.2 - Form Adjustment

Create a tab on the service call form that contains the two custom fields you just created.

This step is optional but can be very useful during testing and for diagnostics, i.e. the DUE_UUID is needed to record a return value that is actually a file name, which can be traced in the log files and archives.

5.3 - Auditing

Activate auditing on the DUE_UUID custom field.

5.4 - Import Mapping

Go in admin to General – Data Exchange Settings – Import Mappings and click Add to create a new import mapping called EI_SERVICECALL.

In this import mapping create item mapping EI_INSERT.

The template that was chosen here is an example. You can use any template. Using one specifically for data that comes from RQuest can be useful to easily identify calls that come from RQuest.

Create the following field mappings for EI_INSERT

The field mapping for EI_INSERT can look something like this.

In the EI_SERVICECALL import mapping create item mapping EI_UPDATE.

The template that was chosen here is an example. You can use any template. Using one specifically for data that comes from RQuest can be useful to easily identify calls that come from RQuest.

Create the following field mappings for EI_UPDATE:

The field mapping for EI_UPDATE can look something like this.

5.5 - Server-side Rules

In Smart Client, go to Administration – Business Logic – Rules. Create a new server-side rule called DUE_RQUEST_UPDATE_NEW in the Service call section.

For action, choose Data Update (External) and create as the screenshot below (make sure to use your own server address).

Create a second server-side rule called DUE_RQUEST_UPDATE_EXISTING in the Service call section.

For action, choose Data Update (External) and create as the screenshot below (make sure to use your own server address).

6 - TPSI Installation

Find the SIS_yyyymmdd-seq-*.zip file you have downloaded or received, and run Extract All. The software is complementary to any existing SIS software, so the default location to install the software is C:\Program Files\PROLIN\Integration Server\.

This should result in the following three directories. - pduewserver – PROLIN Data Update External Web service - rfraserver – Relay From RQuest Agent service - rtraserver – Relay To RQuest Agent service

7 - TPSI Configuration

7.1 - Settings and Defaults

The Smart Suite configuration steps are described in another chapter. The TPSI configuration has settings that have to be in sync with the values below.

Smart Suite Service Call Custom Fields
You will need to create a custom field to record the DUE identifier that the PDUEW server returns. This identifier is used for diagnostics and tracing. The default custom field name is DUE_UUID. You will need to create a custom field to record the RQuest Identifier. The default custom field name is RQuest-ID.
Read about setting up Custom Fields in Smart Suite here

Smart Suite Import Mapping
You will need to create an Import mapping for Insert and Update service calls. The default Import Mapping name is EI_SERVICECALL. The default Import Mapping Class Names are EI_INSERT and EI_UPDATE.

The RQuest Service passes the RQuest Identifier to allow responses to be linked to the correct request. The default external field name is RQUEST-ID and should be mapped to the custom field configured for the RQuest Identifier, default RQuest-ID. The RQuest Service creates messages that contain the user’s email address to be able to identify the Caller in Smart Suite. The default external field name is CALLER_EMAIL. The Service Call Description is a required field. The default external field name is DESCRIPTION.
Read about setting up Import Mapping in Smart Suite here

Directories
The TPSI services use File System Message Queues (FSMQ) to pass messages between services. The default base for these directories and for directories to archive messages is F:\temp\SIS\TPSI. The default base for configuration settings databases is F:\temp\SIS\adm. The default base for log files is F:\temp\SIS\log. The actual values for these directories can be configured in the individual program’s configuration settings file, which is located in their program directory. The storage required depends on the message volume. It is recommended to not use the same drive as the one with the Operating System.

Windows Service Wrapper
The windows service wrapper for each program allows the program to run as a service. The required files are located in the “wsw” subdirectory in the program’s program directory. The service definition is contained in an XML file and contains the complete path name of the executable. The current values assume installation in C:\Program Files\PROLIN\Integration Server.

Once the SIS zip file is extracted, you will need to configure each of the components.

There are a couple of steps that need to be repeated for each service. Below we will go through those steps one by one.

7.2 - RTRA Server

This is the service that fetches messages from the service bus and insert/update data to Smart Suite.

7.2.1 - Configuration

Navigate to C:\Program Files\PROLIN\Integration Server\rtraserver\ and copy the rtraserver.py.config.dist file.

Paste and rename to rtraserver.py.config

Confirm Rename

Check the values and change if necessary. The path names contain “_/_” as separator. These are replaced with the platform specific separator at runtime. You can use the windows “\” separator when adjusting the values. Note: If you want to use a different value, you will need to remove the “#” in front of the line. Note: Please make sure that the RTRA_LOG_DIR value points to a valid directory.

More toward the end of the file is the configuration setting governing the custom field name for the RQuest Identifier. If not configured correctly, return message to the RQuest Server cannot be linked to the correct request.

Open a command window as Administrator or an level of elevation that allows you to create directories and install windows services and run

rtraserver.exe --version

The second run is an initial run without parameters to illustrate that apart from the log directory that is created automatically when possible, the program will not create the other directories it requires, as you need to make sure you specify a drive and path with enough capacity. To be at least a bit helpful, it will print the directories it expects and prints a help message showing command line parameters.

The correct way to run the program for the initial setup and configuration is

rtraserver –-create-directories

The program will try to create the directories it expects and needs, and continue with setting up the default configuration, i.e. the configuration named “default”. The “default” configuration is the configuration that is used when running the RTRA server as a Windows service.

The dialog has different questions for different database setups, and will accept <ENTER> to confirm the displayed default. Passwords are not shown and need to be filled in twice. It will continue to ask until it has received two identical answers. The example shown on the right is for SQL Server using the System DSN we have created earlier. When finished, the program will write the settings to a local database and will ask you to restart the program.

7.2.2 - Testing Connections

Use

rtraserver -–test-connections

to test the connections to Smart Suite application server and the Smart Suite database instance.

7.2.3 - Changing the configuration

When you need to change the settings stored in the database, you need to invoke the program with the –manage-config command line parameter. The program will start the configuration dialog and ask all values it needs. The example shown this time is for when you want to connect to an Oracle database. You will notice that the questions are different compared to the previous run. You can repeat this step as many times as you like, but you need to complete the dialog to enable the program to store the settings. You will need to restart the program or windows service to have the changed settings take effect.

7.2.4 - Get Help on Parameters

When in doubt use the –help command line parameter, as in

rtraserver --help

This will show the available options and a brief description of the command line parameters.

7.2.5 - Perform a manual test run with debug output to the console

When you want to do a test run and see the debug output on screen, use the following command

rtraserver --logstyle stream --loglevel debug

This will show a lot of very useful information. Sensitive values are shown encrypted.

When you have seen enough you can press <CTRL>-C to stop the program. It will print “caught exception” due to the <CTRL>-C.

7.2.6 - Windows Service Wrapper for the RTRA server

The program can run as a Windows service by using the windows service wrapper. The screen print to the right shows the contents of the rtraserver-service.xml configuration file. The <executable> entry should point to the correct location. To install the service run

rtraserver-service.exe install

To start the service run

rtraserver-service.exe start

To get the status of the service run

rtraserver-service.exe status

If the status inquiry returns “Stopped” you will need to take a look in the wsw logfiles and possibly the rtraserver logfile to determine the cause.

7.3 - PDUEW Server

Perform the same type of actions as for the RTRA Server:

  1. Copy config file
  2. Modify config file if necessary
  3. Run using the –create-dirs parameter
  4. Install the service as windows service using the windows service wrapper (wsw)

You can check if the service is running OK by opening a browser and go to the following addres:

http://[servername]:[portname]/about

You should get a page looking like this

7.4 - RFRA Server

Perform the same type of actions as for the RTRA Server:

  1. Copy config file
  2. Modify config file if necessary
  3. Run using the –create-dirs parameter
  4. Install the service as windows service using the windows service wrapper (wsw)

8 - RQuest Agent Configuration

In order to link the RQuest agent to TPSI you need to make sure the inbound and outbound directories point to the same location for both.

Set the correct location of the TPSI inbound and outbound directories in the file channel.config located in the Agent installation directory.

This is the directory structure of the TPSI.

Read here about installing the RQuest Agent