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.

Create a new custom field name “Request from customer” for the Service call entity

Create a new custom field name “Request to customer” for the Service call entity

Create a new custom field name “Customer dialog” for the Service call entity

This last field can be used to append changes from “Request from customer” and “Request to customer”

5.2 - Form Adjustment

Create a tab on the service call form that contains the first 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.

Create another tab on the service call form that contains the three conversation custom fields you just created.

This step is useful for showing the conversation between Smart Suite and REQUEST in one page.

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).

Create a third server-side rule called STATUS_UPDATE_CONVERSATION 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).

To fill the Customer Dialog with “Request from customer” and “Request to customer” you can even add two extra server-side rules ADD_REQUST_FROM with action

ADD_REQUEST_TO with action

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-directories 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-directories parameter
  4. Install the service as windows service using the windows service wrapper (wsw)

7.5 - Useful settings

The configuration files for RFRA, RTRA and PDUE can be used to change the configuration. The location of queues, logfiles and configuration databases should not be changed

Note: after changing the configuration the service has to be restarted.

rfraserver\rfraserver.py.config

# Use this encoding before sending data to Smart Suite via HTTP Event
#
RFRA_EVENT_ENCODING = "latin-1"

rtraserver\rtraserver.py.config

# Mapping of Smart Suite status to Request status
RTRA_FIELD_SMART_SUITE_STATUS_INFORMED = informed,closed
# RTRA_FIELD_RQUEST_STATUS_INFORMED = informed

# Smart Suite settings used for conversations
# RTRA_FIELD_SMART_SUITE_CONVERSATION_CONTENT = Request to customer
# RTRA_SMART_SUITE_CONVERSATION_RULE = STATUS_UPDATE_CONVERSATION

pduewserver\pduewserver.py.config

# Use this encoding after sending data from Smart Suite
#
PDUEWS_ENCODING = "latin_1"

The log level can be changed in case of troubleshooting, e.g.

RFRA_LOG_LEVEL           = DEBUG

8 - TPSI Upgrade

Upgrade of TPSI involves the following steps:

  1. Backup the current configuration!
    • SQLite config databases SIS\adm
    • Integration Server\pduewserver\pduewserver.py.config
    • Integration Server\rfraserver\rfraserver.py.config
    • Integration Server\rtraserver\rtraserver.py.config
  2. Start in your TPSI base directory, default C:\Program Files\PROLIN\Integration Server
  3. Stop and uninstall the current services
    • Run (not available in 1.1)
      stop_and_uninstall_services.bat
       In 1.1 do:       
      pduewserver\wsw\pduewserver-service.exe stop
      rfraserver\wsw\rfraserver-service.exe stop
      rtraserver\wsw\rtraserver-service.exe stop
      pduewserver\wsw\pduewserver-service.exe uninstall
      rfraserver\wsw\rfraserver-service.exe uninstall
      rtraserver\wsw\rtraserver-service.exe uninstall
  4. Install the new TPSI software
    • Unzip on a temporary location
    • Copy to the TPSI location (default C:\Program Files\PROLIN\Integration Server)
  5. Make changes to the configuration files according to the CHANGELOG.md
  6. Install and start the new services
    • Run
      install_and_start_services.bat

9 - 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

10 - Troubleshooting

In order to find issues when some functionality is not working you can take the following steps to troubleshoot the RQuest Agent and TPSI software.

10.1 - TPSI

  1. Check TPSI logs, default log location is f:\temp\SIS\log
    • Each of the 3 TPSI services has its own logfile
    • Check for connection errors
  2. The 3 TPSI services should be running all the time. If one of them has stopped normally a message cannot be handled
    • look in the log file for the specific issue
    • zip and remove the message and send it to PROLIN with the log file
    • restart the service
  3. Stop TPSI services in the services.msc panel to see the flow of a message from RQuest to queue to Smart Suite and vice versa
    • queues are location in f:\temp\SIS\TPSI and each message has an directory, msg.props, msg.payload and files subdirectory
    • Stop RFRA Server to see messages from RQuest appearing in the in_queue
    • The RFRA Server handles messages in in_queue, moves them one by one to in_work and then processes
    • Stop RTRA Server to see messages from Smart Suite appear in due_queue\request. These request have a simple json format
    • The RTRA Server handles messages from due_queue\request, moves them one by one to rtra_work and the processed message will appear in out_queue to be picked up by the RQuest Agent
  4. The archive queues in_archive and due_archive can be viewed to see which messages are just processed or result in errors
    • Messages in the archive queues are zipped

10.2 - RQuest Agent

  1. Check the agent log. The log file is located in <agent_home>\logs\agent.log
  2. The agent puts messages from Rquest (a new request or a conversation) in the in_queue for TPSI
  3. The agent reads messages (changes in service call, or a conversation) from the out_queue and transfers these to RQuest