Deploy the Bridge
The examples in this guide use the BMC® Remedy® ARS Bridge. The steps detailed below will be the same for other types of bridges, but the values necessary for configuration may be different from bridge to bridge.
In order to provide consistent access into disparate data systems, we defined a consistent request and response format for how information can be queried. A bridge is a small web application that can interact with a specified data source based on this common format. The first thing that needs to be done on our journey to Bridging Bliss is to deploy a Bridge.
Bridges are available right here on Kinetic Community. You can find a list of published bridges on the Kinetic Bridges Resources page. Each bridge has its own resource page, which includes a download link to the web application .war file. Want to integrate to a data source not included in our published bridges? No problem. Contact us and have our professional services team work with you to build it up, or modify the source code for an existing bridge to meet your needs!
Download the Bridge
Download the kineticArsBridge.war file from the BMC® Remedy® ARS Bridge resource page found here.
Deploy the Bridge
Copy the kineticArsBridge.war file into a running Tomcat server (or other Servelet container).
Wait for Tomcat to extract the .war file.
Configure the Bridge
Once the web application has been deployed, you will be able to access the bridge AdminConsole using a web browser. The URL for the bridge web application console will be something like:
If the bridge web application was deployed successfully, you should see a login page that looks like this:
Log in using the default username and password (admin/admin). You should be redirected to the bridge AdminConsole and see a page similar to:
The UNINITIALIZED status indicates that the bridge has not been configured yet. Configure the bridge by entering the Username, Password, Server, Port, and Prognum values associated to your Remedy Server and click the Update button. If your configuration is valid, you will see a screen like this:
The INITIALIZED status indicates that the bridge was successfully configured. Congradulations, you have deployed your first bridge!
Build Bridge Definitions
For this example, we will walk through how to set up the KS_SAMPLE_People Remedy form. This form is included with the Kinetic Request installation, and represents a very simple way of storing person information.
Now that the bridge has been deployed, it is time to set up the bridge definitions in the Kinetic Bridge Manager. Bridge definitions are used to define abstractions to the bridged data source. There are three types of definitions: bridge references, bridge structures, and bridge mappings.
For more information about the Kinetic Bridge Manager, please see the Kinetic Bridge Manager guide page.
The Bridge Reference record specifies the location of a Bridge application. It represents a link to the bridge web application. Since each bridge web application is configured to connect to a single data source, this reference also indirectly specifies the location of a data source.
Create the Reference
In order to create a bridge reference, we will need to open up the Kinetic Bridge Manager. To do this, log into Mid-Tier and open the Kinetic Request-Service Catalog Console, then click on the Bridge Manager link on the left hand side. Once the Bridge Manager is open, click on the Bridges tab (which is where Bridge Reference records are defined).
From the Bridges tab of the Bridge Manager console, click on the Add button to create a new bridge reference record. Copy the Bridge Name and Bridge Url from the deployed bridge AdminConsole, click the Save button, and your done!
There are four different types of bridge structures: Models, Attributes, Qualifications, and Qualification Parameters. Bridge structure define data source agnostic references and do not include any information about a data source. Regardless of whether data comes from a database, Remedy, Active Directory, or something else, it represents the same thing. Bridge structures define these representations independent of how and where the data exists.
A Model represents an abstract structural grouping of data. For example, a Person, Computer, or Incident.
An Attribute represents an abstract data field. For example, a Person may have a First Name or Email attribute, and a Computer may have a Serial Number attribute.
A Qualification represents a conceptual way of retrieving data. For example, you may be able to find a single computer By Serial Number, or find multiple people By Name.
A Qualification Parameter represents conceptual qualification variables. For example, the By Serial Number qualification would likely take one parameter, the Serial Number value. Similarly, the By Name qualification would likely take two parameters, a First Name and a Last Name value.
Create the Structures
From the Structures tab of the Bridge Manager console, click on the Add button from the Models section to create a new model. We will create the Person model.
Create Model Attributes
Once the model is created, ensure that it is selected, and then click on the Add button from the Model Attributes section. We will be creating the following attributes: Login, First Name, Last Name, Email.
To create a qualification, click the Add button from the Qualifications section. We will be defining the By Login single qualification.
Create Qualification Parameters
To create the qualification parameters, ensure the newly created qualification is selected and click the Add button from the Qualifications section. We will be defining the Login parameter.
There are three different types of bridge mappings: Model Mappings, Attribute Mappings, and Qualification Mappings.
A Model Mapping defines the translation of an abstract Model to a data source equivalent. For example, there may be a Remedy Person model mapping that relates the Person model to the CTM:People form. Similarly, a HR Database Person model mapping may relate the Person model to the db.employees table.
An Attribute Mapping defines the translation of an abstract Model Attribute into the data source equivalent. For example, there may be a model attribute mapping that relates the First Name attribute of a Person model to the GivenName field on the CTM:People form.
A Qualification Mapping defines the translation of an abstract Qualification to a data source appropriate query. For example, there may be a qualification mapping that specifies the Find By Id qualification should be executed using any of the following, depending on whether the data source is Remedy, a Database, or Active Directory:
- 'Employee Id' = "<%=parameters["Id"]%>"
- dbo.eid = "<%=parameters["Id"]%>"
Create the Mappings
Create Model Mapping
From the Mappings tab of the Bridge Manager console, select the Person model and click on the Add button from the Model Mappings section to create a new model mapping.
Create Attribute Mapping
Once the model mapping is created, ensure that it is selected, select a model attribute mapping, and click on the Modify button from the Model Attribute Mappings section. We will be creating the following mappings:
- Email: <%=field["Email"]%>
- First Name: <%=field["First Name"]%>
- Last Name: <%=field["Last Name"]%>
- Login: <%=field["AR Login"]%>
Create Qualification Mapping
To create the qualification mapping, select the unconfigured qualification mapping from the Qualification Mappings section and click the Modify button. We will be configuring the By Login qualification to use the 'AR Login' = "<%=parameter["Login"%>" query.
We now have a sample bridged resource ready to use in Kinetic Request!
Use the Bridge Model
Bridge Models provide extremely simple interfaces from Kinetic Request into your back end data systems. They can be used in dynamic text elements, question dynamic defaults, dynamic list questions, populate menu events, set fields external events, and even custom events within your Kinetic Request form!
Lets create a sample Kinetic Request form to illustrate how our bridge models are used. From the Kinetic Request - Service Catalog Console, create a new service item. I'm naming mine "Bridged Resource Sample".
For this example, we want to retrieve information about the logged in user, so ensure that the Kinetic form is configured to require authentication. Add three questions to the Kinetic form: First Name, Last Name, and Email. On each of these questions, I will add a dynamic default that leverages our newly created bridge model.
For each question, click on the Defaults tab and check the Use Advance Default option. Select the Person model, By Login qualification, and the appropriate model attribute for the Value. Once these are selected, a red Login qualification parameter will be shown in the table below (see blue arrow).
To configure the qualification parameter, select it in the table and click on the Modify button. We will use the username of the currently authenticated user, which can be selected from the Add Fields menu as shown below.
Notice that the Kinetic form developer didn't need to know how to generate an efficient query -- that was done by the person creating the bridge definitions. This becomes a huge benefit when considering integrations to more complicated data sources, such as Active Directory or custom database solutions.
Now, if we open the Kinetic form, and log in as a user that has a corresponding KS_SAMPLE_People record, we will see something like this:
Congratulations! You have just implemented your first bridged resource!