How to configure HP Connect-It for the
Netcool/OMNIbus Gateway for HP Service Manager
Document Version
2
Document Revision Status Draft
Document Date
15/11/2013
1
Table of Contents
Introduction............................................................................................................................3
Components used in the configuration..............................................................................4
Document types consumed and produced by scenario components...............................4
Create the Gateway Reader Connector................................................................................5
Configure the Gateway Reader Connector............................................................................8
Create the Service Manager Connector................................................................................9
Create the Gateway Writer Connector.................................................................................10
Configure the Gateway Writer Connector............................................................................13
Create the Gateway Writer to Service Manager Mapping...................................................14
Configure the Gateway Writer to Service Manager Mapping..............................................15
Configure the Service Manager Connector.........................................................................17
Create the Service Manager to Gateway Writer Mapping...................................................18
Configure the Service Manager to Gateway Writer Mapping..............................................19
2
Introduction
The Gateway for HP Service Manager uses HP Connect-It to interface with Service Manager. This document
describes how to configure Connect-It to enable the Gateway to create and update service requests within
Service Manager and monitor changes to those requests.
We use Connect-It to define a 'scenario' comprising connectors that connect to each other and to external
entities (namely, the gateway and Service Manager), and mappers that define how connectors interact,
including how data is filtered and transformed when passing from one connector to another.
The scenario defines how OMNIbus ObjectServer event data is read from the gateway and sent to Service
Manager. It also defines how data is read from Service Manager and written to the gateway for forwarding
back to OMNIbus as updates to ObjectServer alerts.
Note that a single scenario is used to facilitate all interactions between the gateway and Connect-It. This
applies not just to the direction of information flow (both gateway to Service Manager and Service Manager
to gateway) but also to the type of event processed. The single scenario can accommodate alert inserts,
updates and deletes as well as journal inserts. In order to do this, an event needs to include information
within it defining what type of event it is and rules within Connect-It mappings need to be conditional on the
type of event that is processed at any particular time.
This document describes the scenario definition and configuration by means of a running example. This
example assumes certain relevant configuration steps have been performed in Service Manager itself. In
particular, it is assumed that an 'Event Registration' named 'omnibus' has been defined. It should be noted
that there is some flexibility in the order of carrying out configuration steps and so other examples are
possible. As components are created, Connect-It assigns default names but these are replaced in this
example by more descriptive alternatives.
The distinction between creation and configuration is not always cleanly delineated as some configuration is
inevitably needed as part of an entity's creation process. Configuration is considered here more as
something that can be extended or changed later, independent of the creation process. As connectors are
connected to each other via mappers, one connector will need the other(s) it is mapped to to be created
before configuration can be completed.
HP Connect-It version: this document was written using version 9.40 of HP Connect-It but it is suitable for
use with earlier versions of 9.x
Screenshots: There are 2 versions of this document; one with and one without screenshots. The former is
only available for internal use.
Some configuration operations require the availability of a running Service Manager installation.
3
Components used in the configuration
Component
Name in example
Delimited text
connector
OS-Output
Reads from gateway writer module
Mapping
OS->SMgr
Links OS-Output to SMgr
ServiceManager
connector
SMgr
Connects to Service Manager
Mapping
SMgr->OS
Links SMgr to OS-Input
Delimited text
connector
OS-Input
Writes to gateway reader module
The components within a scenario together make up a chain where the output produced by one becomes the
input consumed by the next. Connect-It uses the term 'document type' for these inputs and outputs. The
following table summarises the names of the document types created within the example scenario.
Document types consumed and produced by scenario components
Component
Consumed document
Produced document type
name
type
Mapping
OS-Output
n/a (data read from
gateway via HTTP GET)
OUTPUT (OUTPUTSrc)
n/a
OS->SMgr
OUTPUT (OUTPUTSrc)
omnibus (omnibusDst)
OUTPUTSrc-omnibusDst
SMgr
omnibus (omnibusDst)
omnibus (omnibus)
n/a
SMgr->OS
omnibus (omnibus)
myTEXT(myTEXTDst)
omnibus-myTEXTDst
OS-Input
myTEXT(myTEXTDst)
n/a (data written to gateway via
HTTP POST)
n/a
The gateway interacts with the Connect-It scenario via its two 'reader-writer module' processes. Each of
these instantiates an HTTP server. The writer module sends alert data to the OS-Output connector in
response to HTTP GET requests. The reader module reads update events generated within Service
Manager, via the OS-Input connector in response to HTTP PUT requests.
The main HP Connect-It application window shows 'HP Connect-It <scenario name>' in the title bar. By
default it contains 3 panes: 'Toolbox' on the left, 'Scenario diagram' at the top on the right and a tabbed pane
on the bottom right with context sensitive details.
[Fig 1]
4
Create the Gateway Reader Connector
Component type
Connector
Function
Reads event inert/update information from
the gateway writer module process
Name
OS-Output
Activity
Creation and initial configuration
Launch the Connect-It Scenario Builder application: From the Toolbox pane, select 'Protocol connectors',
then double-click 'Delimited text' (or drag it to the 'Scenario diagram' pane); nothing appears in the Scenario
diagram pane yet;
This brings up the 'Configure the connector' Wizard
step 1 – dialog box: 'Name and describe the connector'
Change the 'Name' from 'Delimited text'- to OS-Output, then press Next
[Fig 2]
step 2 – dialog box: 'Select a processing mode'
Select 'Read' radio button, press Next
[Fig 3]
step 3 -- dialog box:'Select a connection protocol'
Select 'HTTP Web site' radio button, press Next
[Fig 4]
step 4 – dialog box: 'Connect to the HTTP Web site'
Enter Address and Port
NB – Address must terminate with ':<port>/'
The default port setting is 80, but the value to be entered should correspond with the gateway configuration:
the Port value corresponds to the 'WRITER_PORT' attribute value set in the gateway config file.
Other options are not explored in this minimal setup description,
press Next
[Fig 5]
step 5 – dialog box: 'Choose a description file'
leave 'Code page to use' at the default of '(automatic)'
EITHER
select a dsc file you have already created ... and then press Finish
OR
enter the name of a NEW dsc file to be created, press the magnifying glass icon to create and edit it:
[Fig 6]
this launches the 'Create/Modify a description file' wizard to create the file.
[Fig 7]
To creates the OS-Output.dsc file:
step 6a - dialog box: 'Select a document type'
press the Blue Arrow button/icon, enter a 'Document type' name, like OUTPUT
5
press Next
[Fig 8]
step 6b – dialog box: 'Select a file for the preview'
do nothing; leave 'File to preview' blank and 'Number of lines to preview' at 25
press Next
[Fig 9]
step 6c – dialog box: 'Specify the column delimiters'
select 'Delimiter' radio button then
select 'Others' and enter '^' symbol,
press Next
[Fig 10]
step 6d – dialog box: 'Specify the data-processing options'
tick the 'Do not generate errors...' box,
leave default 'Number of skipped lines' at 0,
leave 'Start of comment line' at '//'
press Next
[Fig 11]
step 6e – dialog box: 'Specify the column names and types'
press the blue arrow button/icon,
[Fig 12]
then add the following data:
Name
00
evtype
evsysseq
evusrseq
01
02
…
…
24
25
Type
Text
Text
Text
Text
Text
Text
Text
Text
[Fig 13]
The list of 'Names' correspond to the '^' separated values that make up an event forwarded by the gateway.
The numbered Names (01-25) correspond to the 25 rows in the gateway configuration file map.
Note that the insert and update maps in G_PEREGRINE.conf both have 25 rows.
The field named 00 corresponds to a leading empty value in the list forwarded by the gateway:
^<value>^<value>^<value> ..... ie no value before the first separator.
We also prefix mapped values with evtype, evsysseq and evusrseq in the code:
evtype: the event type (pmo = open/insert, pmu = update, pmc = close/delete)
evsysseq: not used
evusrseq: “NOGW@<serial>@<serverserial>” a string that identifies the event as originating from the
gateway.
finally, press Finish!
6
This creates the OS-Output.dsc file
At this point the new Connector appears in the Scenario diagram pane of the Connect-It application
Save the scenario! The OS-Output connector will appear in the Scenario diagram pane.
[Fig 14]
7
Configure the Gateway Reader Connector
Component type
Connector
Name
OS-Output
Activity
Further configuration; the 'Produced
document type'
Double-click on the OS-Output (OMNIbus) connector in the Scenario diagram pane to open the 'Select
document type' dialog box.
This contains 2 panes – 'Consumed document types' and 'Produced document types'
In the right hand pane (Produced document types), click on the top right icon that's not greyed out
of a page with corner turned over) to create a new 'Document type'.
(image
[Fig 15]
This opens the 'Define the produced document type' dialog.
[Fig 16]
Select OUTPUT in left hand 'Document types' pane, press the '+' button in the right hand pane (or doubleclick on OUTPUT)
NB in the right hand pane we change the Document type from OUTPUT to OUTPUTSrc – this is not not
necessary but it appears that some automatically generated or named HP entities have suffixes of Src or Dst
to show they are sources or destinations.
This populates the 2 (left and right hand) 'Element' panes with fields from the description file created or used
in the connector creation process.
press OK to save it.
[Fig 17]
Now, when the OS-Output connector is selected in the Scenario diagram pane and the 'Document types' tab
in the pane below that is selected, the 'OUTPUT (OUTPUTSrc)' 'Produced document type' can be seen
[Fig 18]
Similarly, if we double-click on the OS-Output connector in the Scenario diagram pane, the same can be
seen in the 'Produced document types' dialog box that pops up.
[Fig 19]
8
Create the Service Manager Connector
Component type
Connector
Function
Connector for ServiceManager
Name
SMgr
Activity
Creation and initial configuration
From the main application window, from the Toolbox pane,
drag a 'ServiceCenter/Service Manager' connector from 'Hewlett-Packard->Service Management
connectors->ServiceCenter/Service Manager connectors' to the scenario diagram
[Fig 20]
nothing appears in the Scenario diagram pane yet.
The 'Configure the connector' Wizard dialog box launches.
Give the connector a name (SMgr) in the first screen 'Name and describe the connector'
press Next
[Fig 21]
In the next screen; 'Define the connection parameters'
Add the Server Name (eg hpsm1.hursley.ibm.com.13080) – note the hostname or IP address is suffixed with
'.13080'; the default port for Service Manager connections
Provide the default username and password (falcon/<blank>) or actual settings, if different
Tick the 2 check boxes ('Service Manager 9.20 and later versions' and 'Write to a Service Manager
database'); the Service Manager server port box appears, already populated
Enter the 'Server Manager server port' which will be the same port entered as part of the server name above.
[Fig 22]
Press the 'Test' button to check for a result of 'Successful connection test'
The 'Test the connection' dialog box should finish with a 'Successful connection test' message.
[Fig 23]
close the Test the connection box.
EITHER
press Next and keep pressing Next accepting defaults
OR
just press Finish as we don't need to alter anything later in this wizard
Now the SMgr connector appears in the Scenario diagram pane of the application window.
save it!
[Fig 24]
9
Create the Gateway Writer Connector
Component type
Connector
Function
Sends ticket update information to the
gateway reader module process
Name
OS-Input
Activity
Creation and initial configuration
The setup is a similar (but not identical) process to the creation and configuration of the OS-Output
connector.
From the Toolbox pane, select 'Protocol connectors', then double-click 'Delimited text' (or drag it to the
Scenario diagram pane); nothing appears in the Scenario diagram pane yet.
This brings up the 'Configure the connector' Wizard
step 1 – dialog box: 'Name and describe the connector'
change the Name from 'Delimited text'- to OS-Input,
press Next
[Fig 25]
step 2 – dialog box: 'Select a processing mode'
Select 'Write' radio button,
press Next
[Fig 26]
step 3 – dialog box: 'Select a connection protocol'
Select 'HTTP Web site' radio button,
press Next
[Fig 27]
step 4 – dialog box: 'Connect to the HTTP Web site'
Enter Address and Port
NB – Address must terminate with ':<port>/'
The default port setting is 80, but the value to be entered should correspond with the gateway configuration:
the Port value corresponds to the 'READER_PORT' attribute value set in the gateway config file.
Select 'POST for writing to scripts' radio button option (not 'PUT')
Other options are not explored in this minimal setup description,
press Next
[Fig 28]
step 5 - dialog box: 'Choose a description file' box,
EITHER
select a dcs file you have already created ... and then press Finish
OR
enter the name of a NEW dcs file to be created, press the magnifying glass icon to create and edit it
[Fig 29]
10
This launches the 'Create/Modify a description file' wizard to create the file:
To creates the OS-Input.dsc file:
step 6a - 'Select a document type' dialog box
Press the Blue Arrow button/icon, enter a 'Document type' name, like myTEXT
press Next
[Fig 30]
step 6b – 'Select a file for the preview' dialog box
Do nothing; leave 'File to preview' blank and 'Number of lines to preview' at 25
press Next
[Fig 31]
step 6c – 'Specify the column delimiters' dialog box
Select 'Delimiter' radio button then
Select 'Others' and enter '^' symbol
press Next
[Fig 32]
step 6d – 'Specify the data-processing options' dialog box
Tick the 'Do not generate errors...' box
Leave default 'Number of skipped lines' at 0,
Leave 'Start of comment line' at '//'
and add a '\' escape char
press Next
[Fig 33]
step 6e – 'Specify the column names and types' dialog box
[Fig 34]
Press the blue button/icon, then add the following data:
NB this is not quite the same as in the OS-Output connector...
Name
01
02
…
…
24
25
Type
Text
Text
Text
Text
press Finish
[Fig 35]
in next box, make sure you DO NOT check the 'Enable blind mode' box
[Fig 36]
then press Finish
This creates the OS-Input.dsc file
At this point the new OS-Input Connector appears in the Scenario diagram pane of the Connect-It
11
application.
[Fig 37]
12
Configure the Gateway Writer Connector
Component type
Connector
Name
OS-Input
Activity
Further configuration: the 'Consumed
document type'
Note
OMIT THIS STEP IF AN EXISTING dcs
FILE WAS IMPORTED IN THE PREVIOUS
STEP (rather than created)
Double-click on OS-Input (OMNIbus) connector in the Scenario diagram pane to open 'Select document type'
dialog box.
This contains 2 panes – 'Consumed document types' and 'Produced document types'
In the left hand pane (Consumed document types), click on the top right icon that's not greyed out (image of
a page with corner turned over) to create a new 'Document type'.
[Fig 38]
This opens the 'Define the consumed document type' dialog.
Double-click on myTEXT in left hand pane (or press the '+' button in the right hand pane)
[Fig 39]
This populates the 2 (left and right hand) 'Element' panes with fields from the description file created
[Fig 40]
Note that in the right hand pane of the 'Document type' , manually change the name from myTEXT to
myTEXTDst – this is not necessary but it appears that some automatically generated or named HP entities
have suffixes of Src or Dst to show they are sources or destinations. The same applies to the 'Generic name'
Remove (delete) unwanted fields in the right hand pane; ie fields that will not be populated with values in the
output.
press OK
[Fig 41]
Now when the OS-Input connector is double-clicked in the Scenario diagram pane, to display the 'Select
document type' dialog box, 'myTEXT (myTEXTDst)' is listed as the 'Document type' in the 'Consumed
document types' pane.
Save the scenario.
[Fig 42]
13
Create the Gateway Writer to Service Manager Mapping
Component type
Mapping
Function
Transforms output from connector receiving
OMNIbus event data to input for
ServiceManager
Name
OS->SMgr
Activity
Creation
[Fig 43]
Click and hold on the light grey portion of the OS-Output connector and drag the mouse to the SMgr
connector. This creates a Mapping component in the Scenario diagram with an arrow leading in from the OSOutput connector and an arrow leading out to the SMgr connector.
[Fig 44]
Right click on the Mapping component, select 'Configure the connector'.
Change the connector Name in the 'Name and describe the connector' dialog box from the default 'Mapping'
to 'OS->SMgr'.
[Fig 45]
EITHER
press Next, accept the defaults in the next 2 boxes ('Advanced configuration' and 'Define document types'),
and press Finish
OR
Just press Finish
14
Configure the Gateway Writer to Service Manager Mapping
Component type
Mapping
Name
OS->SMgr
Activity
Configuration to define the output for the
SMgr connector
Double-click on OS->SMgr mapping in the Scenario diagram pane to open the 'Select source and
destination' dialog box
Tip - At this stage - don't create a 'Consumed document type' for the SMgr (Service Manager) connector this will get created when you do the mapping; in fact, if you create it now, the mapper won't use it!
[Fig 46]
select OUTPUT (OUTPUTSrc) as the Source 'Document type'
press OK
This opens the 'Edit mapping' dialog
Select 'omnibus' in the right hand pane; Destination – 'SMgr (<hostname>.13080)'. NB it is assumed the
omnibus entity has already been created in or imported into ServiceManager,
[Fig 47]
Double click on a number of *omnibus* fields in the right hand pane to populate the middle (Mapping) pane:
these are fields required to be populated or updated with data received from the ObjectServer, via the
gateway. The fields selected then appear blue coloured in the right hand ('Destination') pane
Having selected a number of fields from the Destination pane, they will appear as 'Elements' in the central
'Mapping' pane.
[Fig 48]
The middle pane determines how fields in the right hand pane get populated – more on that later.
The choice of fields selected also determines which ones get updated.
Note in the middle pane (Mapping), lower section, under the 'General' tab, HP has generated
•
'Mapping name' (OUTPUTSrc-omnibusDst)
•
'Target document type' (omnibusDst)
•
'Source document type' (OUTPUTSrc)
we provided in an earlier step above.
Initially, the General tab might not be visible – it may be necessary to save, close, reopen the edit mapping
dialog box
Now press OK to return to the main application
[Fig 49]
Below the Scenario diagram pane; if the 'Document types' tab is selected
•
'Consumed document types' on the left will show as 'OUTPUT (OUTPUTSrc)'
•
'Produced document types' on the right will show 'omnibus (omnibusDst)'
[Fig 50]
Under the 'Mappings' tab:, details of the mapping will be displayed:
15
[Fig 51]
Having identified (destination) ServiceManager fields to be updated, the next step is to edit the mapping for
all the fields in the middle pane of the 'Edit mapping' dialog box, opened by double-clicking on the OS->SMgr
mapping component in the Scenario dagram.
Fieldnames in square brackets are source fieldnames - ie from the left hand pane (OUTPUTSrc).
Note that as we use a single scenario for all different OMNIbus event types (insert, update and delete) we
have conditional rules eg:
if [evtype] = "pmo" ....
Note 'retval' is the value assigned to the right hand side HP fieldname – in this example elements of the
omnibus entity.
Example mapping:
Element (omnibus)
$ax.field.name
Mapping
'Maps to Description
if [evtype] = "pmo" then
retval = [19]
end if
'Maps to Update.Action
if [evtype] = "pmu" then
if [04] = "" then
retval = [05]
end if
end if
brief.description
if [evtype] = "pmo" then
retval = [19]
end if
category
if [evtype] = "pmo" then
retval = [10]
end if
evsysseq
[evsysseq]
evtype
[evtype]
evusrseq
[evusrseq]
logical.name
if [evtype] = "pmo" then
retval = [04]
end if
number
if [evtype] <> "pmo" then
retval = [03]
end if
severity
if [evtype] <> "pmc" then
if [evtype] = "pmu" and [04] <> "" then
retval = [09]
end if
if [evtype] = "pmo" then
retval = [09]
end if
end if
[Fig 52]
16
Configure the Service Manager Connector
Component type
Connector
Name
SMgr
Activity
Further configuration to create the
'Produced document type'
This defines the SMgr output that will be the input to the SMgr->OS mapper
Begin by selecting the SMgr connector in the Scenario diagram pane.
Notice under the 'Document types' tab of the 'Detail of the connector 'SMgr' (view 'Global')' pane, the
'Consumed document type', 'omnibus (omnibusDst)' is the same as the 'Produced document type' of the
earlier step to configure the OS → SMgr mapping.
[Fig 53]
In the 'Detail of the connector 'SMgr' (view 'Global')' pane, select the 'Document types' tab, then press the
'create new document type' icon (page with corner turned over) in the 'Produced document types' sub-pane
on the right hand side.
This opens the 'Define the produced document type' dialog box:
[Fig 54]
Double-clicked on the 'omnibus' Element in the left hand pane and the 'Document type' box is automatically
filled out.
Note that the field list is different from the list available when dealing with the mapping from OS-Output to
ServiceManager (OS->SMgr)
eg there is no $ax.field.name, brief.description.
Press OK.
[Fig 55]
Note the main application window's 'Detail of the connector 'SMgr' (view 'Global')' pane, 'Document types'
tab, 'Produced document types' pane - contains 'omnibus (omnibus)' .
[Fig 56]
17
Create the Service Manager to Gateway Writer Mapping
Component type
Mapping
Function
Transforms output from the ServiceManager
(SMgr) connector to input for OS-Input
connector that sends data to the gateway
Name
SMgr->OS
Activity
Creation
This mapping is created in the same manner as used for the OS->SMgr mapping, described above.
18
Configure the Service Manager to Gateway Writer Mapping
Component type
Mapping
Name
SMgr->OS
Activity
Further configuration
From the main Scenario diagram pane, double-click on SMgr->OS mapper to open the 'Select source and
destination' dialog box
Select Source 'Document type' of 'omnibus (omnibus)'
press OK
[Fig 57]
This opens the 'Edit mapping' dialog box
[Fig 58]
Double-click on myTEXT in the right hand Destination pane to populate the Elements listed in the middle
pane.
Note the 3 boxes automatically filled in at the bottom of the middle pane when 'General' tab is selected
Mapping name = omnibus-myTEXTDst
Source document type = omnibus
Target document type = myTEXTDst
'myTEXT' is available due to an earlier configuration step : creation/configuration of the OS-Input connector
[Fig 59]
Remove the elements from the middle pane that are not of interest and add rules for the others.
Alternatively, individually select the fields required from the right hand side (instead of double-clicking on
myTEXT)
[Fig 60]
Note that when the General tab at the bottom of the Mapping pane is selected, the 'Mapping name' is set to
'omnibus-myTEXTDst' and 'Target document type' is set to 'myTEXTDst'.
Now select 'Mapping' tab and enter mapping rules as required.
The following are examples:
Element
Mapping
02
[evtype]
03
“”
04
if [evtype] <> "pmo" then
if [EventFormatFields.sysmoduser] = "EXTERNAL" then
retval = [evusrseq]
else
retval = [number]
end if
else
retval = [evusrseq]
end if
19
Element
Mapping
05
if [evtype] <> "pmu" then
retval = " "
else
retval = [severity]
end if
06
[number]
[Fig 61]
press OK and save the scenario
Checking the mapping configuration:
Now when double-clicking on the SMgr->OS map item the mapping 'omnibus-myTEXTDst' is visible from the
'Select a mapping' dialog box
[Fig 62]
… also, when the 'Document types' tab is selected in the 'Detail of the connector 'SMgr->OS'...' pane is
selected, the source (consumed) and destination (produced) document types can be seen:
'omnibus (omnibus)' and 'myTEXT (myTEXTDSst)':
[Fig 63]
and when 'Mappings' tab is selected in the 'Detail of the connector...' pane is selected, the 'omnibumyTEXTDst' mapping can be seen:
[Fig 64]
Configuration complete!
Next the scenario needs to be deployed (not described here)
20