RapidResponse (by Kinaxis) Integration Setup

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

 

Note: Versions H2011 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 PlanetTogether. 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.

Select the latest PlanetTogether version during the installation. 

Then, 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 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.

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

3. SQL Database Tables Configuration

Two databases must be created in SQL: one Import database and one Publish database.

In the RapidResponse Integration Files folder, you will find a SQL script that can be used to create three configuration tables in the Import database. Running the script will create the tables but they will need to be manually configured.

A description of the tables and fields is listed below:

dbo.IntegrationConfiguration 

Column Header Description
KinaxisURL This is the URL linking to the RapidResponse sign-in page. (https://rrbeta.kinaxis.net/)
CustomerID This is the RapidResponse CustomerID. 
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. 
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.
TimeZone  Specify the name of the time zone here.
AppClientID This corresponds to the credentials of a user in RapidResponse that has the right permissions.
AppToken This corresponds to the credentials of a user in RapidResponse that has the right permissions.
InstanceIdentifier Leave this blank. It will get populated by the installer. 
PTCloudAppUrl This is the URL linking to the cloud app.
AuthorizationToken Leave this blank. It will be generated and populated by the interface service installer. Note: The Authorization Token is reusable and an existing token can be copied in the installer. 
PollingSpanInHours 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. The recommended value is 24 hours. 
RRTimeoutOverrideMinutes This is the number of minutes used to override the standard 100-second timeout for HTTP Client timeouts. This field can be left null to keep the default value of 100 seconds. Note: This value should be smaller than the Interface Timeout set in the Instance Manager. Suggested values are 5-10 minutes.

Ensure that the InstanceIndentifier and AuthorizationToken fields are left blank.

 

dbo.WorkbookConfiguration

Column Header Description
ScenarioName This is used to map together scenarios in RapidResponse to scenarios in PlanetTogether. 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.
Instance Name This is the name of the instance that was created in the previous steps. This can be found in the Instance Manager.
PostPublishScriptName This must match the name of the script that runs specific actions in RapidRepsonse after a Publish is performed to synchronize the data tables. 
PartsFilter This is an optional field that allows you to filter the workbook for certain parts and reduce the data set being transmitted. If left null, it will default to "All Parts".

 

dbo.PlaybookConfiguration

Column Header Description
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 StepIndex Step Wait
 Import  0 Import  0

 

                                   

4. 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 click the "Edit Import Database Connection String" button to open the Connection String Builder. Enter the Server Name and the SQL Import Database Name.

Instance Manager Version 12.0.50 and later:

Instance Manager Versions 11.0.46 and earlier:

Data Publish Tab

Click the "Edit Publish Database Connection String" button 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. 

Clients Tab

The Interface Timeout field is used to override the timeout for the HTTP Client used in the Interface Service for the Import nad Publish Webhook API calls. Note: This value should be greater than the RRTimeoutOverrideMinutes configured in the IntegrationConfiguration table. Recommended values are 5-10 minutes (300-600 seconds).

The integration logs warnings for any calls to RapidResponse that take longer than 30 seconds in the Windows Event Viewer.

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: These will be automatically filled out during the integration service installation. 

Once this is set up, click on "Save and Close".

5. Create a new Integration Service

Next, you will need to access the Integration Web App Installer found in the RapidResponse integration files. You can follow the following file path to access the installer:

C:\ProgramData\PlanetTogether APS\IntegrationFiles\RapidResponse

Running this application will create a new integration service. 

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

  1. Select the instance created in the previous step from the drop-down menu. Note: There is one Integration Service per instance.
  2. Ensure that the file path found under "Browse installation folder:" leads to the folder that contains the RapidResponse Integration Files. Note: You can click the ellipsis button to navigate to the folder containing the RapidResponse Integration Files.
  3. You can enter an existing Authorization Token in the text box or click on the "Generate" button to create one. The Authorization Token is stored in the IntegrationConfiguration table of the SQL database and can be copied in this textbox. 
  4. 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 12000. 
  5. The SQL connection string corresponds to the connection string used to connect to the PlanetTogether import database. If using SQL Express, you can keep the example connection string found in 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.
    1. 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). 
  6. 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.  
  7. 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.

In the IntegrationConfiguration SQL table, the "InstanceIdentifier" and "AuthorizationToken" fields should have been automatically filled out by this last step.

Installation Troubleshooting

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

"Polling Status: Stopped" in the Current Integration Status Page

When required values are missing or set incorrectly in the SQL Configuration Tables, the Current Integration Status page will display "Polling Status: Stopped". To resolve this:

  1. Ensure that all required values are set correctly in each Configuration Table.
  2. Restart the "Integration Service" service.
  3. Refresh the Current Integration Status page. It should now display "Polling Status: Started".

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

                                                   

Updating 

When there is a new version of the integration available, you will need to download the new RapidResponse integration files (refer to step 1).

Next, you will need to access the Integration Web App Installer found in the RapidResponse integration files. You can follow the following file path to access the installer:

C:\ProgramData\PlanetTogether APS\IntegrationFiles\RapidResponse

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

Select the PlanetTogether instance to update and check that the connection string is correct then click the "Update" button. 

Uninstall the Integration Service

Access the Integration Web App Installer found in the RapidResponse integration files. You can follow the following file path to access the installer:

C:\ProgramData\PlanetTogether APS\IntegrationFiles\RapidResponse

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

Select which Integration Service to delete from the drop-down menu then click "Uninstall".