© 2011, Kinetic Data, Inc.
Kinetic Data, Inc, a BMC Software® Solutions Partner.
Remedy, a BMC Software Company
Remedy, the Remedy logo and all other Remedy product or service names and registered trademarks are trademarks of BMC Software, Inc.
Chapter 1 Overview
Kinetic CalendarTM is a comprehensive tool to be used for scheduling and organizing all types of information from any BMC Remedy-based application.
To install Kinetic Calendar software, an installer must be a Remedy Administrator and have some knowledge and access to your intended Web server.
This manual is intended for AR System administrators, not users or managers.
The Installer Overview
Kinetic Calendar is typically installed using an executable installer and includes two parts: Installing the Remedy forms, workflow and data, and installing a Tomcat Web Server and Kinetic Calendar Web component. The installer does include an option to choose just the Remedy component, just the web server component or both, so it may be run multiple times to accommodate your environment.
For the Remedy component the installer can be run from any Windows machine. The installer will connect to your Remedy server to import the necessary components and configure the necessary data.
Often an Administrator will choose to install the Tomcat web component in a development environment to get running quickly. Then for a staging/production environment, manually install the web application to an existing web server.
For the web component, the installer must be run on the machine that is to host your web server and again must be a Windows machine. If you prefer to install the web component on another operating system, a different web server, or an existing Tomcat instance, just install the Remedy components and follow the directions later in this manual to manually deploy the web application.
§ BMC AR System Server version 6.0 or higher.
§ If your Remedy server is version 6.x
BMC AR System version 6.x is not receiving upgrades, specifically updates for time zone/daylight savings changes. These changes could cause display issues if you are using these older versions of the AR System
o The machine on which the setup file is run must have the Remedy Administrator application installed.
o The web application must use the 6.0 – 7.0 style Remedy API which utilizes the native C API through a Java JNI iterface. The native C API is only available in 32-bit binaries, which means the web server must use a 32-bit version of Java 1.5 or higher.
§ If your Remedy server is version 7.x or higher
o The machine on which the setup file is run does not need to have either the Remedy Administrator application or the Developer Studio application installed. All data and workflow is installed using the Remedy API.
o The web application may use either a 32-bit or a 64-bit version of Java 1.5 or higher.
Kinetic Calendar is licensed per AR System. Kinetic Calendar comes in two varieties:
§A “Demo” option, where the license will expire on a specific date, and the application will no longer function.
§An “Unrestricted” or “Enterprise” option where an unlimited number of calendars can be used. Phone support and upgrades are included with this option.
NOTE: The “Lite” option has been deprecated, and will not function with Kinetic Calendar version 1.3 or higher. Lite licenses are not eligible for upgrades as specified in the Kinetic Calendar End User License Agreement (EULA).
Each AR System production server, on which Kinetic Calendar is installed, must have its own license.
See Kinetic Data’s website for more specific information on licensing and costs.
BMC AR System licensing
Kinetic Calendar licenses are in addition to any AR System licenses needed for your users, and do not take the place of AR System licenses. See AR System documentation.
For customer service support, go to the support section of our Web site http://www.kineticdata.com or call 651-695-8566.
NOTE: Only customers with the Enterprise license are entitled to phone support.
Chapter 2 Installation
Downloading the Installer
To download the installer, follow the instructions from Kinetic Data when you receive your license key. The installer consists of one file (KineticCalendar_Vx.exe, where x is the version) that will be run from a Windows machine that has network access to the Remedy server.
Running the Installer
The following are instructions for using the installer (KineticCalendar_Vx.exe).
Figure 1: InstallAnywhere timing
2. The InstallAnywhere Introduction screen states the software title and version currently being installed on your system. InstallAnywhere will guide you through the installation.
Figure 2: Introduction
3. Click Next.
4. From the Choose Install Folder screen select where you would like to install the locally installed components. For the Remedy Component, only documentation and web application files are created. If the web component option is chosen, an instance of Apache Tomcat will be installed in this directory, as well.
5. Click the Choose button (see next Figure), if you would like to change the installation directory.
Figure 3: Choose Install Folder
6. Click Next.
7. The Installation option screen appears. From here you can choose to install the ARS Definitions and/or installation options for the web component.
Figure 4. Installation option
8. Uncheck the ARS checkbox if only the web component is to be installed.
9. Choose the web component option that is appropriate:
a. Local Tomcat webserver: A new instance of Tomcat will be installed. Later, you will have the option of choosing a port to run this instance on.
b. Add to an existing Tomcat installation: Tomcat will not be installed with this option. The web application files will be installed inside an existing Tomcat instance. This is most common if you have another Kinetic Data application installed prior to Kinetic Calendar, or possibly AR System Mid-Tier. Later, you will have the option of setting the directory to create the files.
c. Don’t install web component: No web component files or Tomcat instance will be installed.
Installing ARS Definitions and Data
If you choose to install the ARS component, the installer will try to determine the location of your current Remedy Admin Tool or Developer Studio. If it cannot locate the file(s) automatically, it will ask for a location.
1. From the Choose a File screen, pick the directory which your Remedy Administrator tool\Developer Studio is installed (aradmin.exe or devstudio.exe). The version selected should correspond with the version of your AR System Server.
2. Click the Choose button to select the correct directory.
Figure 5: Choose a File
3. Click Next.
4. The ARS Connection Information Screen will appear. Enter your ARS information including server, ports, and authentication.
This information is used to connect to your AR Server if you are installing the ARS components, and for the web server configuration, as well.
Figure 6: ARS Connection information
5. Enter the AR Server name or your Remedy server name.
Note: If you typically connect to your AR Server via a fully qualified name, enter that name here.
This server name must exactly match the server name provided to Kinetic Data when generating your license key.
6. Enter the Login name. If installing the ARS components, this person must have administrator access. It will be through this user that the forms and definitions will be imported into your server. If only the web component is being installed, this user can be an existing Kinetic Calendar “default web user” or an Administrator.
7. Enter a Password.
8. Enter TCP and RPC ports. If you have ports configured for your AR Server, enter them here. If you do not then leave them as “0.”
9. Enter Authentication of use and the authentication string, if applicable. If not, leave blank.
10. Review all lines for accuracy.
11. Click Next.
Note: Please wait while Kinetic Calendar is being configured. The system is retrieving the server version and applying the correct information, as well as verifying that the user is an Administrator and has the correct permissions.
Figure 7: Please Wait - Configuring ARS Connection Information
12. The license key screen appears next. You have a choice of either entering the license key on this screen, or later using the Remedy User tool. If you do enter the license here, it is best to simply copy and paste the key from the email you received from Kinetic Data. Make sure there are no spaces before or after the license key.
Figure 8: Enter License Key
13. Click Next.
14. The Calendar Web User screen appears.
NOTE: Screen does not appear when installing into an existing Tomcat instance.
Kinetic Calendar needs a default user record with the appropriate credentials to handle some interactions with the AR Server. The user entered here will be created with the appropriate groups and a fixed license. If the user account already exists, you will need to add the KS_CAL group to this user record after installation is complete.
Figure 9: Kinetic Calendar Web User
Note: If there are multiple web servers connecting to a single Remedy server, other users will need to be manually created; one for each web server.
15. This login, by default, is called KD_WEBUSER, but you may change it to any value based on your company’s normal protocol.
16. Enter a Password. Use your company’s normal protocol.
17. Click Next.
18. The Web component details screen appears. The information in this screen is used to configure the URL information for the sample data.
Installing a Local Tomcat Web Server
If you selected the option to install al local Tomcat web server without installing the Remedy forms, workflow and data you will be prompted for your AR Server version. If you are installing the Remedy forms, workflow and data you will not see the following screen and you can skip to step 2.
Figure 10: ARS version
1. Select the your AR Server version and click Next.
Figure 11: Web Component Details
2. Enter the Web Server Name to use for your installation. This is typically the name of the web server, but may be an alias or an IP number. This will be used for configuring the sample data. This field is not visible if not installing the ARS component. Example: “mywebserver.mycompany.com” or “18.104.22.168”.
3. Enter the Port Number you want the Tomcat server to listen on. By default, Tomcat listens on port 8080. If the port entered here is already in use by another application (another Tomcat instance for example), you will be alerted and prompted to select a new port number before continuing.
4. Enter the Shutdown Port Number for Tomcat to listen for the shutdown command from the system. By default, Tomcat uses port 8005. If the port entered here is already in use by another application (another Tomcat instance for example), you will be alerted and prompted to select a new port number before continuing.
5. Select the Tomcat Applications that should be installed with the Tomcat server. These applications are useful for administering and managing the Tomcat server from the web, but they are not required.
6. Click Next. A Please Wait screen appears while Kinetic Calendar configures your system.
Figure 12: Please Wait
7. If you have entered a Port number currently in use, the screen below will appear.
Figure 13. Tomcat port number in use warning
8. Click OK for the previous screen to appear and enter a new Port number.
9. If you have entered a Shutdown Port number that is currently in use, a warning dialog will appear. Click OK for the previous screen to appear and enter a new Shutdown Port number.
Figure 14: Tomcat Shutdown Port in use warning
10. If you selected to install either the Tomcat Manager Application or the Tomcat Admin Application, a screen will appear that allows you to create a Tomcat manager/admin user. Please note, this user is not a Remedy user and will not create a record in the Remedy User form. It is simply an account on the Tomcat server to allow access to the Tomcat Manager and Tomcat Admin applications. This screen will be skipped if you did not select to install either application.
Figure 15: Tomcat Manager User Credentials
11. Click Next and a Tomcat optimization screen will appear. Here can choose to install Tomcat with default development mode settings, or performance tuned production mode optimizations.
Figure 16: Tomcat Optimizations
a. Production mode optimizations tell Tomcat to only compile JSP pages when the service starts. This provides better performance because the Tomcat server doesn’t need to check the JSP pages for changes every time a web page is served. If any JSP pages are changed however, the Tomcat service will need to be restared for the changes to become effective.
b. Development mode settings allow the JSP pages to compile on the fly, without requiring a Tomcat service restart. There is a performance penalty with this because the Tomcat server must check the JSP page for changes every time the web page is served.
12. The Min Heap Size is the amount of memory allocated to the Java Virtual Machine when the Tomcat service starts. The maximum value that Microsoft Windows supports in 32 bit mode is 1024 MB.
13. The Max Heap Size is the maximum amount of memory allocated to the Java Virtual Machine. The maximum value that Microsoft Windows supports in 32 bit mode is 1024 MB.
14. Click Next and wait as Kinetic Calendar configures your system.
Figure 17: JDK Directory
15. From the JDK Directory screen (Shown for new Tomcat installations only), locate an existing JDK installation.
16. Click Choose to browse for the location. A JDK 1.5 or greater is required. If your Remedy server is version 6.x, the JDK must be 32-bit.
17. Click Next. Please wait while Kinetic Calendar is being configured for your system.
Installing into an Existing Tomcat Server
1. The first screen shown depends if the ARS component is being installed, or if you are only installing the web component. If you are only installing the web component, you will see a screen asking for the version of the ARS server that the web component will be connecting to.
Figure 18: ARS Version
2. Select the your AR Server version and click Next.
3. The next screen will prompt you to enter the ARS information that your web component will be conecting to. This information is needed to automatically configure the Kinetic Calendar web application properties file.
Figure 19: Remedy Server Connection Info
4. The next screen is the web component details screen. The installer is asking for the web server name and port number because it uses these values to automatically set some configuration properties in the Kinetic Calendar web application properties file.
Figure 20: Web Component Details
5. Enter the Web Server Name to use. This is typically the name of the web server, but may be an alias or an IP number. Example: “mywebserver.mycompany.com” or “22.214.171.124”.
6. Enter the Port Number the Tomcat server is listening on. By default, Tomcat listens on port 8080.
7. Click Next.
8. The Select deployment folder screen appears.
Figure 21: Select the deployment folder
9. Choose the webapps folder for your existing Kinetic Tomcat installation. This is where the “KinCal” web application will be installed.
10. Click Next.
Completing The Installation
1. From the Pre-Installation Summary screen, please review the following for accuracy before continuing.
Figure 22: Pre-Installation Summary
2. Click Next. If you selected to install the ARS portion, the ARS Data and/or definition import screen appears verifying that you have elected to import ARS data and/or definitions.
Figure 23: ARS Data and/or definition import
3. Click Install. This process will take a while as Remedy forms, workflow, and data are imported to the AR System Server.
Note: Please do not interrupt the process until the Install Complete notification has appeared.
Figure 24: Installing Kinetic Calendar
Look for an Importing ARS Data and Definitions screen to appear....
Figure 25: Importing ARS Data and Definitions timing screen
4. After the installation is complete, you may be asked to restart your computer if the Tomcat Web Server was installed.
Figure 26: Install Complete
5. From the Install Complete screen select either: Yes, restart my system, or No, I will restart the system myself.
6. Click Done. The installation of Kinetic Calendar is finished.
Congratulations! Kinetic Calendar is now installed on your server.
Note: If any warnings occurred you can view the log files in the installation directory you chose at the beginning of the installation.
Inside the logs directory, an individual log is created for each component installed and data file imported.
Note: For each set of data imported, see .arx.log. For each set of work flow imported, see .def.log (Remedy forms).
Support: For customer service, please contact the support section of our web site at www.kineticdata.com or call 651-695-8566.
Chapter 3 Other Web Servers
Kinetic Calendar can be installed with a stand-alone Apache Tomcat server for easy deployment. However, in many situations, another Servlet Container may be required.
Kinetic Calendar is created as a standard J2EE web application and can be deployed into almost any standard Web Server/Servlet Container including Tomcat, Websphere or ServletExec AS.
The following sections describe the general process for deploying to other servlet containers. Each container may have other processes for deploying an application. Please refer to your specific documentation for complete instructions.
Note: The terminology for web servers may be confusing. Servlet containers are often called web servers. However, not all web servers are servlet containers and some servlet containers require a separate web server.
Some examples may help:
- IIS: Web Server (not a servlet container)
- ServletExec IS: A lightweight servlet container that requires a web server front end like IIS. This is what Remedy Mid-Tier was bundled with prior to version 7.
- ServletExec AS: The application server version of ServletExec. This can run as a servlet container and web server, or can connect up to IIS or other web servers for front end page serving.
- Apache Tomcat: An open source servlet container that can also be used as a stand-alone web server.
- Apache Web Server: An open-source web server. This is not a servlet container, and is often paired with Tomcat as a back-end servlet container.
Deploying Kinetic Calendar to a web server involves moving the directories included in the installation to your web server as well as configuring some of the web server properties.
Note: If you need a specific WAR file for your environment (Web application archive), contact Kinetic Data support and we can provide one. http://www.kineticdata.com or call 651-695-8566.
1. Locate the installation directory chosen at the beginning of the installation, by default the location is C:\Program Files\Kinetic Apps\Kinetic Calendar. The needed files have been included in the Web directory.
2. Determine what version of the web application you will run for your environment. Kinetic Calendar now comes with support for the 6.0 – 7.0 style API for Remedy 6.x servers, and support for the pure Java style API for Remedy 7.x servers.
a. 6.x servers
1. Use the web application found in the Web/RemedyAPI_6.x directory of the upgrade package.
2. Include the ARS API files specific to your ARS installation. If you are installing Kinetic Calendar on the same instance of a web server running BMC Remedy Mid-tier, please read the next section on Shared Java Resources before doing this step.
3. Place these files in the KinCal/WEB-INF/lib directory. This would minimally include:
3. If no other Remedy applications are installed on your machine (such as Midtier/Flashboards/Email Engine, etc.), you will also need to include the C api files (.dll files on Windows, .so or .a files on Unix/Linux).
b. 7.0+ servers
1. Use the web application found in the Web/RemedyAPI_7.x directory of the upgrade package.
3. Add the KinCal application context to your web server configuration. This is often done from a management/configuration screen for your environment. Typically this involves:
a. Naming the application. Example KineticCalendar
b. Including the URL context. The default is “/KinCal”
c. Including the path to the KinCal directory moved in Step 2
4. Update your KinCal.xml file located in KinCal/WEB-INF/classes/. The following properties should be updated:
a. RemedyServer: This should be the name of your remedy server and must match the server name provided to kinetic data when your key was generated.
b. RemedyUser: This is the Remedy user account Kinetic Calendar will use to login to Remedy.
c. RemedyPassword: This is the password for the user account.
d. RemedyPort: This is the TCP port used to connect to Remedy. If your server is configured to use portmapper, set this value to 0.
e. RemedyRpc: This is the RPC Program Number to use when connecting to Remedy. If you are unsure what to set this to, use 0 for the default.
f. RemedyAuth: This is the Authentication string used to connect to Remedy. If you server does not use an authentication string, leave this field blank.
g. LogLevel: By default this is “DEBUG” for a development environment. However, for a production environment “INFO” is recommended.
h. LogSubLevel: Defines the granularity of detail provided in each level. Values range 1-5, with 5 being the highest level of detail.
i. LogFile: The name of the log file Kinetic Calendar will use. This fill will reside in the web servers default temp directory.
Note: For multiple web servers, a separate web user is needed for each web server unless your web user has Remedy Administrator privileges.
5. Restart your Web Server/Servlet Container. You should be ready to go.
Because the version 6.3 BMC Remedy Java API uses a JNI interface, there are some special requirements if the Servlet Container running Kinetic Calendar is also running BMC Remedy Mid-Tier, or another Remedy-based web application.
A few notes on sharing a servlet container:
§Kinetic Calendar cannot be installed inside your Mid-tier application (inside the Mid-Tier directory).
§ ServletExec ISAPI is not supported if Mid-Tier is already installed inside this container because shared libraries are not available. ServletExec AS is supported, and ServletExec ISAPI is supported if Kinetic Calendar is the only Remedy-based web application running.
§If you are setting up a new environment we suggest installing BMC Remedy Mid-Tier first. Testing your install, then installing the Kinetic Calendar Web component as described earlier.
Shared Jar files
To run the applications together in the same instance, you must move some jar files that both applications need into a directory available to your container for this purpose. To do this:
1. Remove the arapi6x.jar and arutil6x.jar from BOTH the kinetic/WEB-INF/lib AND the Mid-Tier/WEB-INF/lib directories.
2. Place these files in the shared directory for your servlet container:
a. For Tomcat, this is in Tomcat/shared/lib/
b. For ServletExec AS, this is ServletExec AS/<SE instance>/classes/.
c. For SE you must also alter the ServletExec AS/<SE instance>/StartServletExec.bat script to include these three files in the classpath.
i. You will see a –classpath line followed by many paths, each separated by a semi-colon.
ii. Enter the path to each jar after the last item in the path.
For other web servers or more information, please refer to your specific server’s documentation.
3. In a shared environment, you should not include the other DLL’s/libraries you would typically include in your KinCal/WEB-INF/lib directory. These are already included in the Mid-Tier server and added to the PATH environment variable for your server.
Important Note: When you upgrade your Mid-tier server in a shared environment, you will need to, again, remove the jars from your Mid-Tier/WEB-INF/lib directory. Replace the files in the shared directory with these new files.
Congratulations. You have successfully completed the installation of Kinetic Calendar.
If the Enterprise edition was purchased and you need assistance, please call 651-695-8566, or contact us at www.kineticdata.com.
If you are using a Demo or Lite version and you need assistance, please check the forum at support.kineticdata.com.
Chapter 4 Calendar Resources
A calendar resource refers to individual users and their ability to access default events in Kinetic Calendar. The default events are ones that can be entered directly from the calendar web display.
For these events only, you must have individual users entered on the KS_CAL_Resource form. Once the user has a record on that form, they can be associated to a calendar with a role that allows them to either create or view the default event.
Included in the application in an inactive example filter for pushing users to the KS_CAL_Resource form. You can use this as a template for any other form in your system that has the correct information (like CTM:Person).
Private calendars manage access to Remedy data using the built in permission structure of the Remedy system. When the user logs in to access a private calendar, their Remedy permissions are captured and used to restrict access to Remedy data. You do not have to add users as resources in this case.