RapidResponse (by Kinaxis) Integration Setup

The following document will walk you through the steps required to integrate with RapidResponse.

 

Note: Versions H2007 and later of RapidResponse should be used for the integration. 

1. Install the RapidResponse Integration Files

Install the RapidResponse integration files using the latest version of the software. The Server Installer link can be found in the footer of the main planettogether.com web page. Click on "Server Installer" and open the downloaded app. The server installer will download the full  PlanetTogether APS software, as well as the required server and instance managers.

A detailed installation guide can be found here. For a video of the installation process, click here. Instructions on how to install the integration files offline can be found here.

There are a few things to note when installing the software for a RapidResponse integration:

First, the latest version of the software should always be used. When selecting the software version to install, you may need to check the "Include PreRelease Versions" checkbox to include versions 11.39 and later.

Second, you must select "RapidResponse" as the Integration to install. Click the downward arrow to open the drop-down menu and select the correct integration.

Once you have completed the installation, you will get an "Installation Complete!" message and a prompt to Launch the Instance Manager. At this point, you have successfully installed the server, instance manager, client, and the RapidResponse integration files. The RapidResponse files will be located in the C:\ProgramData\PlanetTogether APS\IntegrationFiles folder. 

 

Offline Installation Process

To install the integration files offline, you will need a folder containing the PlanetTogether installer and the APSLocalInstallationFiles. These are available on request.

Then, follow the same steps as above, but click the "Install from local files" button instead of entering a serial code in the first step:

Note: Ensure that the PlanetTogether installer is located in the same folder as the Local Installation Files. Otherwise, you will not see the option to "Install from local files". 

2. Launch the Instance Manager to Create a New Instance.

Open the APS Instance Manager.

                                                                       

Click on the "New" button to open the "Create New Instance" dialog:

Fill in the required fields and click the "Create" button.

                                             

Note: If you are unable to start the services after creating the instance, you may need to create a new instance and select "PlanetTogether" as the Integration Code. 

You should now see the newly created instance in the Instance Manager:

3. Create a new Integration Service

Next, you will need to access the Integration Web App Installer found in the RapidResponse integration files. Running this application will create a new integration service. 

Double-click on the application to open and click the "Install" button: 

  1. Type in the name and version number of the instance created in the previous step. Note: There is one Integration Service per instance.
  2. Click on the three dots found at the right edge of the "Browse installation folder" field and select the folder that contains the RapidResponse Integration files.
  3. The Webhooks Port will be automatically populated in the Integration Web App Installer. Each port number must be unique and the installer will attempt to provide a unique port for the integration service starting at 7999. 
  4. The SQL connection string corresponds to the connection string used to connect to the PlanetTogether import database. If using SQL Express, you can copy the example connection string found above the text box and change the "[Import Database Name]" to match the SQL database. Otherwise, configure the connection string to connect to your SQL Server and database. Note: If a database has not yet been created, you must create one before installing the integration service. During the installation, three configuration tables will be created in this database (these will need to be configured in the following steps). 
  5. Enter the Log On credentials of users that will be used to on to the Integration Web App windows service. Note: Users will need to have read and write access to the SQL database. and must be set if the SQL server uses Integrated Security.  
  6. Click on the "Install" button. If successful, a new Integration Service will be created and started. You should now see a new Integration Service for your instance name in the Windows Services.

4. SQL Database Table Configuration

There are three tables in the SQL import database that need to be configured to connect it to the new instance. A description of the fields to be manually configured is listed below:

dbo.IntegrationConfiguration 

KinaxisURL This is the URL linking to the RapidResponse sign-in page. 
CustomerID This is the RapidResponse CustomerID. 
InstanceName This is the name of the instance that was created in the previous steps. This can be found in the Instance Manager.
PTPublishTableName This corresponds to a separate database where the PlanetTogether Publish data will be sent.
RRPublishTableName This corresponds to the location of the RapidResponse database in which the integration pushes the data.
ExtraServicesURL This is the PlanetTogether local Extra Services URL. To get the unique port number, double-click on the instance in the Instance Manager. From the Data Publish tab, copy the "Extra Service Web Host Port" number to replace the [PORT] field of the following URL: http://localhost:[PORT]/APSWebService
TimeZone Specify the name of the time zone here.
PTUserID This corresponds to the credentials of a user in PlanetTogether. This user must be created in PlanetTogether and have the right permissions set. The default is "Admin".
PTPassword This corresponds to the credentials of a user in PlanetTogether. This user must be created in PlanetTogether and have the right permissions set. The default is no password. 
RRUserID This corresponds to the credentials of a user in RapidResponse that has the right permissions.
RRPassword This corresponds to the credentials of a user in RapidResponse that has the right permissions.
PollFrequencyInSeconds Defines how often the integration will pull from RapidResponse and look for changes in scenarios. This value will depend on the size of the data to import and how long it takes to perform an import. If the value is too high, there will be a delay between changes occurring in RR and in PT. If the value is too small, an import may be triggered while another is in progress which results in skipping the second import.
RRTriggerTable This is the name of the RapidResponse Trigger Table.
RRTriggerScenario This is the name of the RapidResponse Trigger Scenario. 
LastSynchronizedTimeUtc If starting with a blank value, set this date/time to something in the past so that new values will be pulled in. Once the service pulls information, it will automatically set this value to the last occurrence. [Example: 2020-07-13 01:01:01.000]

 

dbo.WorkbookConfiguration

ScenarioName This is used to map together scenarios in RapidResponse to scenarios in PlaneTpogether. The name of both scenarios should match exactly and be mapped here.
WorkbookName: This corresponds to the RapidResponse Workbook name.
SiteGroup This corresponds to the RapidResponse site group.
BucketCalendar This corresponds to the RapidResponse bucket calendar.
SchedulingBucket This corresponds to the RapidResponse scheduling bucket.
CreateScenarioIfNew Set this to 'true'.

 

dbo.PlaybookConfiguration

PlaybookName This has to match the RapidResponse playbook name.
Step Index This specifies the order of the steps to be performed. The very first step should be given a value of "0". 
Step This specifies which step is performed (e.g. Import, Optimize, Publish, etc.)
Wait This tells the integration whether you need to wait at this step before running the next step. If set to "0", no wait time is required. If set to "1", the integration will wait until this step is completed before performing the next step.

Note: You need at least one import step to pull in data into PlanetTogether

PlaybookName Import
StepIndex 0
Step Import
Wait 0

 

                                   

5. Configuring the Instance from the Instance Manager

From the Instance Manager, double-click on the instance to open the Instance Settings.

Data Source Tab

Select "SQL Server" as the Import Connection Type, then type in the Server Name and the SQL Import Database Name.

Data Publish Tab

Click the button found at the right edge of the Publish Database Connection String to open the Connection String Builder. Specify the server name and the name of the SQL Publish database and click "Done". Ensure that the "Accept Web Transmissions" is checked. The Extra Service Web Host Port should match the port inserted in the ExtraServices URL configured in SQL Server. 

Web Services Tab

This tab contains webhooks that are used to trigger the import and publish functions.

The pre-import URL is used by PlanetTogether to trigger the integration and import the data. The post-export URL will trigger all data found in the tables to be sent to RapidResponse.

Note: The port should match the Webhooks port that was set up during the Integration Service installation.

Once this is set up, click on "Save and Close" and start the services. Log into the Instance from the APS Client.

Troubleshooting

"An instance matching the values entered for instance name and software version does not exist"

  • This error means that the values entered for "Instance Name" and/or "Software Version" do not match those of the instance created. We recommend that the name of the integration service matches the name of the instance. 

“Error extracting integration files: Error unzipping and copying files: The process cannot access the file [FILE PATH] because it is being used by another process”

  • This error message means that an integration service using the RapidResponse integration files is already set up and currently running. Stop the services using those files to move on.

"An Integration App installation already exists in this folder path..."   

               

  • To fix this issue, click the "Start Over" button found in the upper-right corner of the installer, then select the middle "Update" button. 
  • Alternatively, go to the folder that contains the RapidResponse integration files. The file path should be: C:\ProgramData\PlanetTogether APS\IntegrationFiles\RapidResponse.
  • In the folder, delete everything except the "IntegrationWebApp" zipped folder and the "WebAppInstallationWizard".

"The 'Install' button is greyed out"

                     

  • This can occur when the "Browse installation folder" file path is incorrect. Clicking the "Find" button will populate this "Browse installation folder" field, but it might point to the wrong file path.
  • Try using the following file path: C:\ProgramData\PlanetTogether APS\IntegrationFiles\RapidResponse.

"The scenario names do not match"

It is important that the RapidResponse and PlanetTogether scenario names be identical. If the scenario name must be changed in PlanetTogether, click on the "Current Scenario" button of the ribbon and select "Rename Scenario".