EMC® Ionix™ ITO Adapter

BMC Remedy
Version 2.4

Installation and Configuration Guide

P/N 300-011-512

REV A01

EMC Corporation
Corporate Headquarters:
Hopkinton, MA 01748-9103
1-508-435-1000
www.EMC.com
Copyright © 2010 EMC Corporation. All rights reserved.
Published June, 2010

EMC believes the information in this publication is accurate as of its publication date. The information is
subject to change without notice.

THE INFORMATION IN THIS PUBLICATION IS PROVIDED “AS IS.” EMC CORPORATION MAKES NO
REPRESENTATIONS OR WARRANTIES OF ANY KIND WITH RESPECT TO THE INFORMATION IN
THIS PUBLICATION, AND SPECIFICALLY DISCLAIMS IMPLIED WARRANTIES OF MERCHANTABIL-
ITY OR FITNESS FOR A PARTICULAR PURPOSE.

Use, copying, and distribution of any EMC software described in this publication requires an applicable
software license.

For the most up-to-date regulatory document for your product line, go to the Technical Documentation
and Advisories section on EMC Powerlink.

For the most up-to-date listing of EMC product names, see EMC Corporation Trademarks on EMC.com.
All other trademarks used herein are the property of their respective owners.

ii VERIONS 2.4 REV A01 300-011-512

Table of Contents 1
Preface  ix
Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
Font conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
Related documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . x

Introduction  12
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Integration Adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Action Adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Adapter Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
ITIL Services Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Supported ITIL Object Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
System Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Persistence Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Database Acquisition Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Buffer Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Web Service Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Notification Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Acquisition Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Acquisition Push . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Acquisition–Event Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Notification Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Custom Parameters for Notification or Acquisition-Event Services . . . . 25
Operations Web Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Process Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
About the BMC Remedy Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Supported Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Attachment Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Supported Services  30
Acquisition Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
WSDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Polling Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Blocking Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE iii
 Terminal Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
General Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Event Notification Service (called from the Remedy filter) . . . . . . . . . . . . 32
Discovery Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
WSDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Operations Web Service Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Shared Service Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Incident Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
ITObject Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Configuration Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Problem Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Change Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

System Configuration  40
Supported Operating Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Recommended . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Minimum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Supported Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Software Installation  42
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Configuring SSL Communications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Installing a License File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Installing the Adapter Software - Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Before You Begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Start the Installer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Installing the URL Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Installing the Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Running the Adapter Windows Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Shortcuts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Executable Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Service Manager Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Installing Adapter Software - UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Before You Begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Installing the Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Running the Adapter UNIX Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Manual Installation Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Before You Begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Install the Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

Framework Properties  83
Properties Editor Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Starting the Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Using the Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Global Framework Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

iv RELEASE 2.4 VERSION: A01 300-011-512

 Acquisition monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Automated Alerts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
BMC Remedy Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Remedy Problem Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

Configuration  92
Create an Adapter User Account . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Create a Remedy Filter to Notify the URL Agent . . . . . . . . . . . . . . . . . . . . . . . . . . 92

Custom Configuration  96
Client Acquisition Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Data Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Object Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
RESTful Client Acquisition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Calling the RESTful Client Acquisition from curl . . . . . . . . . . . . . . . . . . . . . . 97
SOAP Client Acquisition Web Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Running on another port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Adapter High Availability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Operations Services Scaling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Acquisition Services Scaling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Use the External Database for Multiple Adapters . . . . . . . . . . . . . . . . . . . 101
Adapter Failover Infrastructure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Agent Scaling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Java to Adapter Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Persistence Database Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Removing Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Reclaiming Unused Disk Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Connecting to the Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Changing the Database Port Number . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Offloading the Acquisition Queue to an External Database . . . . . . . . . 105

Ionix IT Orchestrator Configuration  106
Using the ITIL Adapter Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Associated Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Installation and Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Using the Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Adapter API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Software Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
API Distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Package Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Key Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Service Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
SSL Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Java Code Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE v
 Using the URL Agent  118
About the Adapter URL Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Python Requirement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
URL Agent Daemon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Shutting Down and Starting the Daemon . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Running the URL Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Example Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
URL Agent Filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Running the Filter Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Filter Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Example Filter Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

Managing the Adapter  126
Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Connecting to the Adapter Java Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Starting the Java Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
Management Beans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
com.iwave:name=Adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
com.iwave:name=AcquisitionQueue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
com.iwave:name=FrameworkAdmin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

Maintenance and Troubleshooting  132
Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Log Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Turning on Adapter Logging (Windows) . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
URL Agent Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Error Types and Meanings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Recoverable Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Permanent Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Global Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
BMC Remedy Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Re-Installing or Uninstalling the Windows Service . . . . . . . . . . . . . . . . . . . . . . 140
Re-installing the Windows Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
Uninstalling the Windows Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
Starting and Stopping the Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
Uninstalling the Adapter Software - Windows . . . . . . . . . . . . . . . . . . . . . . . . . . 141

IT Object Model (ITOM)  144
Incident Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
Configuration Item (CI) Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
Problem Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
RFC Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
Attachments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175

vi RELEASE 2.4 VERSION: A01 300-011-512

 Index  178

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE vii
viii RELEASE 2.4 VERSION: A01 300-011-512
Preface 2
This manual includes instructions on installing, configuring, and
troubleshooting the EMC BMC Remedy Adapter software.

Audience 2
This publication is written for the System Administrator or Engineer responsible
for installing and configuring the EMC BMC Remedy Adapter software.

Organization 2
This publication consists of the following chapters:
• Introduction
• System Configuration
• Software Installation
• Framework Properties
• Using the URL Agent
• Custom Configuration
• Orchestrator Configuration
• Managing the Adapter
• Maintenance and Troubleshooting
• IT Object Model List (ITOM)
• Index

Font conventions 2
• Bold format is used to identify dialog boxes and menu choices. For example:
Start > Programs > IonixITO> adapters-2.4
• Courier fixed-width font is used for code elements (Java, HTML) as well as
filenames and directories. For example:
install_root refers to the directory where the Adapter software is
installed, for example

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE ix
 c:/Program files/install_root/Adapters

• Web addresses are displayed as hyperlinks. For example:

http://www.EMC.com

Related documents 2
For more information on EMC software products, refer to the following manuals:
• EMC Ionix IT Orchestrator Introduction and Planning Guide - This manual
provides an overview of the Orchestrator architecture and associated
applications. It introduces the main components of the IT Orchestrator,
Design Studio, Platform and applications.
• EMC Ionix IT Orchestrator Installation and Configuration Guide - This
manual provides information on installing the EMC Ionix IT Orchestrator,
Design Studio, Platform and associated plugins. Provides an overview on how
to install the Orchestrator Studio on Windows and Linux platforms and
describes the mechanism for installing the Orchestrator Platform in your
managed environment.
• EMC Ionix IT Orchestrator Administration and Operations Guide - This
manual identifies the administration tasks required to configure the Ionix IT
Orchestrator Platform and describes the log files available for detailed analysis
of running solutions.
• EMC Ionix IT Orchestrator Developer Guide -This manual provides an
introduction to the Designer Studio and Lifecycle tools that enable you to
design Services and Tasks in Orchestrator Studio. The manual identifies the
procedures for building Services and Tasks and describes the configuration of
the associated properties.

x VERSION 2.4 REV A01 300-011-512

 Chapter 1
Introduction 1
Topics covered in this chapter:
• Introduction
• Adapter Framework
• ITIL Services Support
• Supported ITIL Object Types
• System Architecture
• Persistence Database
• Web Service Methods

Introduction 1
EMC provides two different types of ITIL Adapters:
• Integration Adapters
• Action Adapters

Integration Adapters
EMC provides a comprehensive library of IT Service Management (ITSM)
integration Adapters. Integration Adapters enable the bi-directional exchange
of Incident, Problem, Configuration, Change and Asset information between
ITSM applications.

The ITSM applications include:

• Service Desk Applications
• Enterprise Management Systems
• CMDB and Asset Management Systems
• Database Management Systems

Figure 1-1 illustrates a high-level view of the end-to-end, bi-directional process.

In this process, the new/modified Incident Record goes from the endpoint
application to the remote vendor application.

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 12
INTRODUCTION

EMC provides for two-way integrations allowing this process flow to move in
either direction. An Adapter is required on each endpoint as each application
has a customized API. Integrations can be performed for multiple applications;
integrations are not limited to two.

Figure 1-1 High-Level Integration Overview

Action Adapters
Action Adapters allow you to quickly create integration Adapters for ITSM
applications without resorting to programming. EMC provides the following
Action Adapters, which can be installed with other Integration Adapters:
• Command Line Adapter
• Reverse Proxy Adapter
• SQL Proxy Adapter

Command Line Adapter
The Command Line Adapter allows remote execution of command line
processes on the machine where the Adapter is installed. Commands can be
executed using the Command Line Web Service.

Reverse Proxy Adapter
The Reverse Proxy Adapter can be used by customers who may need to put
their service desk application on the public internet. The Reverse Proxy
Adapter can be used to provide a layer of indirection between the Ionix IT
Orchestrator and the service desk. The proxy can provide security (HTTPS) and
authentication (HTTP Basic Authentication) without needing to set up these
configurations on the service desk.

SQL Proxy Adapter
The SQL Adapter allows remote execution of SQL queries on the Adapter
system. This allows the Ionix IT Orchestrator to effectively query a database
that is only accessible through the public internet. The Adapter can secure the

13 VERSION 2.4 REV A01 300-011-512

 ADAPTER FRAMEWORK

communication and provide the actual access to the database. To utilize the
SQL Proxy Adapter, you must configure the Adapter to point to the database
you wish to use.

Adapter Framework 1
The EMC Adapter Framework is a Java 6 application. The Adapter Framework
manages communication between the EMC Adapter and consumers (including
EMC Ionix IT Orchestrator). The EMC Adapter interfaces with the ITSM
application’s API and is therefore restricted by the limitations of that API.
• For some ITSM applications, the EMC Adapter must run on the same machine
as the ITSM application itself.
• For other ITSM applications that support remote APIs, the Adapter may run on
a separate machine.

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 14
ITIL SERVICES SUPPORT

ITIL Services Support 1
EMC Adapters support the Information Technology Infrastructure Library (ITIL)
service silos as illustrated in Figure 1-2. The ITIL is a set of best practice standards
for Information Technology Service Management (ITSM) and has become the
worldwide standard in service management.
• Incident Management - needs configuration (CI) dependency information
and determines a correlation of incidents and creates a problem report.
• Problem Management - needs all Incident reports related to a problem.
Determines the root cause and determines if an RFC needs to be created from
specific CIs.
• Asset Management (Financial) - determines the following:
— If a new CI needs to be added to the Configuration Management
system.
— If an RFC is needed for the Change Management system.
— If a Service Desk task needs to be created to provision and model the
new asset in the Configuration Management system.
• Event Management - generates events and alerts.
Figure 1-2 EMC ITIL Service Silos and Objects

15 VERSION 2.4 REV A01 300-011-512

 SUPPORTED ITIL OBJECT TYPES

Supported ITIL Object Types 1
Each transaction record has an associated object type. This may either be a built
in object type (i.e., Incident) or it may be a custom type. When an item is added
into the Acquisition Queue, a specified object type or an object class is used:
• If the object type is specified, then that type is used.
• If no object type is specified, the type of the object class is used.

Note: Not all Adapters support all objects.

The EMC Adapter may include the following built in object types:
• Incident Object - includes the Incident object in the Incident Management
Service silo. The primary difference between an Incident object and an
ITObject object lies in the schema. The Incident has a predetermined schema
allowing all adapters to map information into common predetermined data
elements, whereas the ‘ITObject’ is completely generic and all data is stored as
native data.
• Problem Object - includes the Problem object type for Problem
Management.
• Change Object - includes the Change object type for Change Management.
This object is also known as a Request for Change (RFC).
• CI Object - includes the CI (Configuration Item) object type for Configuration
Management. This provides configuration information from a CMDB.
• Event Object – includes the Event object type for Event Management.
• IT Object – includes the generic objects correlating back to the endpoint
application forms that may not have any relationship to the ITIL processes.
ITObject Services are used in cases where customers have created their own
representation of the Incident via custom forms or have developed custom
forms representing data needed to integrate between applications.

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 16
SYSTEM ARCHITECTURE

System Architecture 1
The EMC Adapter translates information from an Endpoint Application for input
into a remote vendor application (and vice versa). The translation process
includes the following Adapter software components identified in Figure 1-3:
• Persistence Database
• Web Service Methods:
— Operations Service
— Acquisition Service
– Acquisition-Event Service
— Notification Service

Figure 1-3 EMC Adapter System Architecture

EMC Ionix ITO
Adapter

EMC 
Ionix ITO 

17 VERSION 2.4 REV A01 300-011-512

 PERSISTENCE DATABASE

Persistence Database  1
The Persistence Database is an open source, relational Apache Derby database
that holds transactions in the order that they are received. Once data is
received, it is assigned a transaction number and stored in the Acquisition
Queue. This is necessary to ensure that each application in the integration has
proper data synchronization.

The Acquisition Queue consists of two areas:

• Database Acquisition Queue
• Buffer Queue

Database Acquisition Queue
Each time an incident is created, modified, or closed in the Endpoint
Application, the change is captured as a transaction. This transaction data is
stored in the Database Acquisition Queue, which is periodically polled by the
EMC Ionix IT Orchestrator. When polled, the transaction data is packaged into
an XML document and sent to the Ionix IT Orchestrator via HTTP/HTTPS. The
Ionix IT Orchestrator processes the transaction via its workflows and provides
the data to the Operations Service of one or more remote Adapters to
facilitate platform integration.

After the transaction is successfully processed, the Ionix IT Orchestrator

acknowledges the transaction in the queue, so it can be removed. The Ionix IT
Orchestrator can optionally acknowledge the transaction as errors based on
workflow thresholds. Transactions acknowledged as “complete” or “errors” are
no longer available when polled.

Buffer Queue 
The Buffer Queue stores records on disk until there is room in the database for
them. This allows the Adapter to perform more effectively with larger loads.
Instead of records going into the database directly, they are stored to the file
system when the number of database records exceeds the configuration option
acquisition.bufferqueue.limit (default 200).

The Buffer Queue stores records waiting to be put in the database in the data/
queue/buffer directory. When the buffer is active, it starts a background thread
to push data into the database. Order of the records is maintained. The files in the
directory should not be modified while the adapter is running.

This also provides a store-forward like capability for the Adapters similar to the
agents. If the database is down, the Buffer Queue is also engaged

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 18
WEB SERVICE METHODS

Web Service Methods 1
EMC Adapters handle communication with the actual ITSM Endpoint
Application. EMC Adapters provide a common set of Web Services methods:
• Acquisition Service - acquire transaction information from the ITSM
applications.
• Operational Service - create, update, or search and retrieve information
within the ITSM applications.

EMC Adapter Acquisition and Operational Services are consumed by processes

running in the EMC Ionix IT Orchestrator.

Notification Agent
The majority of the EMC Ionix IT Orchestrator Adapters require an Agent to
send notifications to the Adapter from the Endpoint Application.

The BMC Remedy and Atrium adapter uses the URL Agent to send
notifications. For more information on the URL Agent, refer to “Using the URL
Agent” on page 9-118.

Figure 1-4 Adapter Web Service Methods

EMC
Ionix ITO

19 VERSION 2.4 REV A01 300-011-512

 ACQUISITION SERVICE

Acquisition Service 1
The Acquisition Service provides access to objects that have changed in
endpoint applications. All of the data is stored in a Persistence Queue.
Acquisition is the process that allows the Adapter to react to the creation,
modification, or closure of an incident and place that information into the
Persistence Database queue. The EMC Ionix IT Orchestrator polls the
transactions from the Persistence Database queue. Then the Ionix IT
Orchestrator processes and sends the transactions to the target application(s).

The same Acquisition Service is used for all object types and polling can be
restricted to certain object types.

Process Flow 
Figure 1-5 displays a detailed architectural view and Acquisition process flow
for the EMC Adapter. This process allows the EMC Ionix IT Orchestrator to
receive and manage transaction data stored in the Persistence Database
queue.

The process consists of the following steps:

1. The Ionix IT Orchestrator sends a Transaction Management request to the
Acquisition Service.
2. The Acquisition Service queries the Persistence Database queue for
transaction data.
3. The Persistence Database sends the transaction back upstream to the Ionix IT
Orchestrator.
Figure 1-5 Acquisitions Process Flow

EMC Ionix ITO
Adapter

EMC 
Ionix ITO 

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 20
ACQUISITION SERVICE

Acquisition Push
The Acquisition Push mechanism provides lifecycle management of adapter
queue transactions. It allows the workflow developer to write workflows to
handle transactions only. The Acquisition Push mechanism handles the
following functions:
• Performs the polling operations. It polls in groups of 50 at a time, which it can
execute in parallel. Only one thread performs polling.
• Allows a configurable number of threads to be used to process transactions.
• Performs a complete operation when a workflow successfully executes.
• Performs a retry if it cannot connect to Ionix IT Orchestrator or if there is an
error. Has a configurable number of retries (defaults to 60). If the retries count
is exceeded, the transaction is put into a resolvable error state.
• Automatically notifies the Monitoring Server of errors that occur and logs the
errors.
• Allows the workflow creator to optionally use blocking or error functionality
manually. This allows for using this mechanism for simple processes but gives
the full acquisition service capability where required.
• If Ionix IT Orchestrator is detected to be down (planned or otherwise), the
mechanism will wait for Ionix IT Orchestrator service to return rather than
continually generating errors.

Terminology
• Buckets - The acquisition push mechanism uses the concept of 'buckets' to
parallelize processing. A blocking key is the unique combination of 'serviceId',
'objectType' and 'objectId'. This is used as the criteria for blocking on the
acquisition queue. The push mechanism takes results of a poll and breaks it up
into separate groups known as buckets. One bucket is created for each
blocking key in the poll. If all records are for unique IDs in the endpoint
application, then each bucket will have only one record in it. All buckets can
be processed independent of other buckets.
• Side Effects - The acquisition push mechanism analyzes the 'side effects' of
processing. The Acquisition Push will look at a transaction status and blocking
to determine if it is safe to process other transactions in the same bucket. If it
determines that is not safe, then it will not do further processing on the same
bucket. Side effects are determined as follows:
Safe to process in same bucket:
— Complete: Will not be present on the queue. Get will fail.
— Error: Will not show as 'Blocked'.
Not Safe to process in same bucket:
— Retry: Will show with transaction status of 'Poll'.
— Resolvable Error: Will show as 'Blocked'
— Blocked: Will show as 'Blocked'

21 VERSION 2.4 REV A01 300-011-512

 ACQUISITION SERVICE

Performance
This mechanism has been optimized to perform handling of adapter queue data
the best.
• It only uses a single thread for polling. This reduces the idle time load on the
adapters. One problem with Ionix IT Orchestrator polling is having so many
jobs continuously hitting the adapters with poll calls.
• Worker threads are used to perform simultaneous processing. Separate jobs
do not need to fire on a repeat interval. When there is work in the queue to be
done, it can keep all worker threads active.
• All adapter calls are handled internally and do not need to go over the wire
(web services). Transactions are only pushed when they are to be run.

Acquisition–Event Service 
The Acquisition-Event service is used for event mode Acquisition in
conjunction with the Agent. This service receives an HTTP post on a specific
URL.

The content of the post is in the format of the “Data” object. This data is
mapped using a mapping script provided to the ITOM format and then is
added to the acquisition queue.

Acquisition–Event Service Process Flow
Figure 1-6 illustrates the Acquisition–Event process flow for the Adapter. This
process posts all the changed data to the Adapter.

The process consists of the following steps:

1. The Endpoint Application sends record information to the Agent.
2. The Agent sends the record information to the Acquisition-Event Service.
3. The Acquisition-Event Service translates the record information into the IT
Object Model.
4. The Object data is placed into the Persistence Database queue and is available
to the Acquisition Service.

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 22
ACQUISITION SERVICE

Figure 1-6 Acquisition-Event Process Flow

EMC Ionix ITO
Adapter

23 VERSION 2.4 REV A01 300-011-512

 ACQUISITION SERVICE

Notification Service 
The Notification Service is a RESTful service that notifies the Adapter when a
particular object in the Endpoint Application has been added or changed. The
notification happens by performing a POST to a specific URL (configured with
each Adapter) typically by the Adapter Agent. The Notification system uses
the Operational Service's get method to retrieve the object and put it into the
Acquisition Queue. The Notification Service may also pass the object type to
the Acquisition Queue.

The ITObject can support multiple object types from different forms. An
optional parameter may be specified on the URL to the service that can
indicate the object type. This is stored in an extra parameter in the Acquisition
Queue called objectType.

For example, to specify the object type, use a URL in the following format:

http://localhost:9080/services/notification/{adapter}/itobject/{objectType}/{id}

Where:

• {adapter} = Adapter name.

• {objectType} = desired object type for the parameter (i.e., event)
• {id} = the incident record ID

When the Notification Service performs the request to retrieve the data for the
id, it uses the Operations Service. For the ITObjectService, a table parameter is
required that defines the “form”, “table”, “object class” or “object type”. This
{objectType} specified on the URL is mapped to this table parameter in the
service.

Process Flow
Figure 1-7 displays a detailed architectural view and Notification Service
process flow for the EMC Ionix IT Orchestrator Adapter. This process informs
the Adapter when incidents are changed or created on the endpoint
application.

The process consists of the following steps:

1. The Endpoint Application sends a new or modified Incident Record ID to the
Adapter Agent.
2. In response, the Agent sends the ID to the Adapter Notification Service.
3. The Notification Service forwards the ID to the Operations Service.
4. The Operations Service sends the ID and a “get” request to the API Interface.
5. The Endpoint Application sends the ID in a “get” method call on the Endpoint
Application API. The API Interface receives the Endpoint Application response,
which contains all of the Incident Record information.
6. The translated incident transaction data is placed into the Persistence
Database queue.

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 24
ACQUISITION SERVICE

Figure 1-7 Notification Services Process Flow

EMC Ionix ITO
Adapter

Custom Parameters for Notification or Acquisition­
Event Services
The following parameters can be added to the Notification or Acquisition-Event
services to influence how a transaction is placed in the Acquisition Queue. Each
of these can be added using the -a parameter when calling the Agent. These
must be set using the string-field extended field type.
• iwave.request.type - This parameter sets the
TransactionRecord.requestType to the value specified.
• iwave.real.objectId - This parameter sets the
TransactionRecord.objectId to the value specified. This is used to
override the default that uses the actual object's identifier. This is useful when
a staging form is used for the record but blocking is needed based on the real
objectId.
• iwave.overrides.objectType - This parameter sets the
TransactionRecord.objectType to the value specified. This is used to
override the default that uses the actual object's type. This is useful to define
partner's object types.
• iwave.overrides.serviceId - This parameter sets the
TransactionRecord.serviceId to the value specified. This is used to
override the default that uses the actual object's service identifier. This is
useful to set custom partner IDs.
• iwave.create.date - This parameter sets the
TransactionRecord.createDate to the value specified. This must be
in the XML date format as if the date-field is used however this must be a
string-field for agent compatibility. The create date normally is set at the time
the item enters the queue. This allows setting this date from the agent call.

25 VERSION 2.4 REV A01 300-011-512

 OPERATIONS WEB SERVICE

Operations Web Service 1
An operation constitutes the process of pushing, getting, and finding data
from a remote application. For example, when an incident is created, modified
or closed in an application that is integrated with an endpoint application, the
modified information is placed into the endpoint application. This operation
effectively synchronizes an application’s data with its remote counterpart.

Process Flow
The process consists of the following steps:
1. The Ionix IT Orchestrator calls the Operations Service methods to interact with
the Endpoint application’s API.
2. Operations Service translates the record information from the IT Object Model
to the Endpoint application’s native record format. The native record
information is sent to the Endpoint application through the API.
3. The API Interface inserts the data into the Endpoint application.
4. The results from the API are translated back into the IT Object Model and
returned from the web service call.
Figure 1-8 Operations Process Flow

EMC Ionix ITO
Adapter

EMC Ionix ITO 
Adapter

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 26
ABOUT THE BMC REMEDY ADAPTER

About the BMC Remedy Adapter 1
Inbound integration into Remedy (Operations) is done using the Remedy ARS
Java API. Integration into the Atrium CMDB uses the CMDB Java API. These APIs
allow getting data from the system, performing queries, creates and updates.

Outbound integration from Remedy (Acquisition) is done using Remedy filters. A

filter is added against the Remedy forms that need to be monitored. When
changes occur, a notification calls the URL Agent executable to notify the BMC
Remedy Adapter of the event. The BMC Remedy Adapter retrieves any relevant
information for the change using the Java API.

Supported Objects
When a Remedy form has a properly configured filter that calls the EMC URL
Agent, all Incidents created or modified by that form are sent to the EMC
Notification Service. This causes the Adapter to collect the Incident data.

The BMC Remedy Adapter supports two types of objects: Incident and
ITObject. Each is handled differently when transformed into a transaction.

Incident Object
Once collected, the Remedy data is mapped into an EMC transaction data
format called EMC Transaction Object Model (ITOM). Since data on various
vendor applications (such as Remedy) do not match, data from each is
mapped into this standard form for transport and workflow orchestration.
Once received on the other end of the integration, the data is mapped from
ITOM into that application’s native form. This standard mapping allows out-of-
the-box (OOB) workflow integrations between Remedy and other
applications.

ITObject
The ITObject allows for any generic form to be used. It only maps the Incident
Identifier; all other data is mapped as an Extended Field. Extended fields
simply collect the field name into a string and the data value into an
appropriate data type, such as integer. Since there are no standard mappings,
as with the Incident Object, the orchestration workflows must be custom built
in Ionix IT Orchestrator to facilitate integrations.

Attachment Support
Starting with Release 2.1, attachments are supported for BMC Remedy. Generic
forms use the binary-field to create an attachment. The attachment-
reference-field is used to get a reference to the attachments. Attachments
are retrieved through the ITObjectService.getAttachments().

27 VERSION 2.4 REV A01 300-011-512

 ABOUT THE BMC REMEDY ADAPTER

In Remedy ARS, attachments are supported in a special field type. There are actually
two fields related to attachments:
• Attachment Field – This is the basic attachment field. It supports setting the
attachment data and name.
• Attachment Pool – Group or list of attachments. This is a container for multiple
attachment fields. To add an additional attachment here a new attachment
field must be added to the form.
For the ITSM applications, attachments are associated with work logs. Each work
log may have up to three attachments associated with it.

The adapter should be able to retrieve an attachment from Remedy of any size.
The data can be retrieved as a file and streamed back to the web service without
loading it all into memory.

The adapter can only create attachments that can be fit into memory at one time.
This is a limitation on the Remedy API.

ITSM Applications
For the core ITSM Application forms, attachments are supported on IT Operational
Services. Incident, Problem and Change services all support attachments in
Remedy.

Remedy handles attachments related to work logs rather than having them
directly on the Incident, Change or Problem objects. This is due to the limitation in
Remedy where you can only have the number of attachments on a record as you
have attachment fields. This gets around that limitation by allows multiple
worklogs and essentially as many attachments as you want by continuously
adding work logs.

The attachments should be associated with the main object itself such as the
Incident Report. This is how the object model is built since it makes the most sense
from the user perspective. This has a few consequences for the Remedy
implementation.
• Getting Attachments – When you get attachments, it essentially needs to pull
all attachments from all worklogs. The attachments returned for the Incident,
Problem or Change are actually those on the worklogs it relates to.
• Creating Attachments – Creating an attachment requires creating a worklog.
Each attachment that is created will create worklog. This means that if logs are
being integrated bi-directionally, a log may be created in the remote system
that only indicates an attachment was created.

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 28
ABOUT THE BMC REMEDY ADAPTER

29 VERSION 2.4 REV A01 300-011-512

 Chapter 2
Supported Services 2
This section identifies the supported Adapter Services:
• Acquisition Service Methods
• Discovery Service

Acquisition Service 2
The following services are made available to the EMC Ionix IT Orchestrator
through the EMC Adapter’s Acquisition Service:
• Polling Methods
• Blocking Methods
• Terminal Methods
• General Methods

WSDL
The Acquisition Services are used to access the Adapter acquired messages on
a queue. The following is the WSDL URL for the Acquisition Service:
https://localhost:9443/services/AcquisitionService?wsdl

Polling Methods
While in the Acquisition Queue, transactions are assigned a polling status:
• Poll - indicates the transaction has no related transactions that are Blocking
and it is available for polling. Related transactions are defined as those with
the same objectType, serviceId and objectId (see the
getRelated operation).
• Pending - indicates records that have been polled and are currently being
processed.
• Error - indicates records that have been polled, processed and contain errors.

The following are the supported polling methods:

• poll(objectType, maxResults) - Polls the acquisition service for
transactions with the given object type. The maximum number of records

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 30
ACQUISITION SERVICE

returned is specified. This method puts the records into the blocking state and
sets their status as pending. If maxResults is not specified, one record will
be returned.
• pollAny(maxResults) - Polls the acquisition service for transactions. The
maximum number of records returned is specified. This method puts the
records into the blocking state and sets their status as pending. If
maxResults is not specified, one record will be returned.
• pollByService(serviceId, objectType, maxResults) - Polls
the acquisition service for transactions with the given service ID and object
type. The maximum number of records returned is specified. This method
puts the records into the blocking state and sets their status as pending. If
maxResults is not specified, one record will be returned.

Blocking Methods
A blocking transaction is a transaction that is currently being processed by an
instance. A blocking transaction record prevents other related records from
being polled. Blocking Methods are used to identify if the transaction is blocking
(TRUE) or non -blocking (FALSE). If the transaction is blocking, the blockType is
identified as either Pending or Asynchronous.
• block(id, message, blockType) - Sets the transaction as Blocking
and sets the blockType. Since polling automatically sets the blocking flag as
TRUE, most of the time this method will just set the blocking type.
• unblock(id, message) - Sets the transaction as non-blocking. (Blocking
= false)

Terminal Methods
Terminal Methods are called to signal the end of Ionix IT Orchestrator
processing on a record.

• complete(id) - Acknowledges a transaction and deletes it. This used to be

called acknowledgeComplete. acknowledgeList will be removed as
transactions are generally handled sequentially.
• retry(id, message) - Sets the status to Poll and unblocks the
transaction. This can be used to resolve and retry errors or to retry something
that was polled.
• resolvableError(id, message) - Sets the status to Error and
ensures that the transaction is Blocking. This is used instead of
acknowledgeError. The blocking is preserved to prevent data corruption. This
block type is set to Error.
• error(id, message) - Sets the status to error and unblocks. This is used
for final errors that were never retried. By using this method, the user allows
other related transactions to be processed. Use this method with caution.

31 VERSION 2.4 REV A01 300-011-512

 ACQUISITION SERVICE

General Methods
General Methods are called to get and return transaction and blocking results.
• getBlocking(maxResults) - Gets all transactions in the Blocked state.
• getBlockingFor(maxResults, blockType, seconds) - Gets all
transactions in the blocked state for a number of seconds. This can be used for
auditing asynchronous transactions.
• getTransaction(id) - Gets the specified transaction.
• count(id) - Returns the total count of available transactions and error
transactions in the Persistence Queue.
• countErrors(id) - Gets the total number of records that are in the Error
state in the Acquisition Queue. Similar to count() but for errors.
• getErrors(maxResults) - Gets all transactions with the Error Status.
• getRelated(id) - Gets a list of all transactions that are related to this
transaction. Related transactions are defined as ones that have the same
objectType, serviceId and objectId. This is useful to get any
transactions that are related to a transaction that is blocking.

Table 2-1 identifies the formats and descriptions of the method input variables.

Table 2-1 Acquisition Service Method Input Descriptions

Inputs Format Description

blocktype string This field defines the type, category, tag or state associated with
the block.

id Integer Identifies the transaction ID.

maxResults Integer Identifies the maximum number of items to poll. (Default =1)

message String Text string identifying the method message.

objectType String Case sensitive ITIL Object Type (Change, CI, Problem, and
Event, Incident or ITObject).

seconds Integer Identifies the number of seconds.

serviceId String Case sensitive Service ID.

Event Notification Service (called from the Remedy filter) 
The BMC Remedy adapter's acquisition is based on the Agent Notification
mechanism. The following denotes the services that should be used for
notification:
• http://localhost:9080/services/notification/remedy/incident/$Incident Number$

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 32
DISCOVERY SERVICE

• http://localhost:9080/services/notification/remedy/configuration/
$ClassId$~$InstanceId$
• http://localhost:9080/services/notification/remedy/problem/$Problem
Investigation ID$
• http://localhost:9080/services/notification/remedy/change/$Infrastructure Change
ID$
• http://localhost:9080/services/notification/remedy/itobject/FORMNAME/
$IncidentNumber$

Note: For configuration items, a synthesized identifier is used. This is

composed of the class ID and the instance ID. These fields are
separated by a tilde (~) character in the URL.

Discovery Service 2
The discovery service allows you to see what web services are deployed on the
adapters framework. This will list all adapter web services, Monitoring Server
services and any RESTful HTTP services. The Discovery Service information can
be accessed in two different ways:
• through a SOAP Web Service
• through a standard HTTP GET

WSDL
The following are the WSDL locations for the Discovery Service:
• For SOAP:
https://localhost:9443/services/DiscoveryService?wsdl
• For HTTP GET:
https://localhost:9443/services/discovery

33 VERSION 2.4 REV A01 300-011-512

 OPERATIONS WEB SERVICE METHODS

Operations Web Service Methods 2
The BMC Remedy and Atrium Adapter utilizes the following Operations Web
Services:
• Shared Service Operations
• Incident Service
• ITObject Service
• Configuration Service
• Problem Service

Shared Service Operations
Core Methods
These are the core methods available on most of the services.

Table 2-2 Shared Services - Core Methods

Event Description/Notes

get(identifier) Gets the object with the identifier provided.

find(query (IncidentID)) Finds the object with the endpoint application query specified.

create(Object) Creates the object in the endpoint application.

update(Object) Updates the object in the endpoint application.

Relationship Methods
These methods manage relationships between the object defined and other
objects in the endpoint application.

Table 2-3 Relationship Methods

Event Description/Notes

relate(identifier, reference) Relates the object reference specified to the identifier of the
object to refer to it.

unrelate(identifier, reference) Removes the relationship between the object represented by the
identifier and the reference.

Log Methods
These methods provided access to modifying logs. Logs are returned as
references and should be retrieved and modified by these operations. Log

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 34
OPERATIONS WEB SERVICE METHODS

identifiers are retrieved through the object models for the various object
types as object references.

Table 2-4 Log Methods

Event Description/Notes

createLog(identifier, log) Creates a new log object associated with the identifier of the
object specified.

getLogs(ids<List>) Retrieves a list of log objects given a list of their IDs.

Attachment Methods
These methods provide access to get or create attachments. On some systems,
creating an attachment with an existing ID may update an existing
attachment. This functionallity is not covered by the Adapter framework.

Table 2-5 Attachment Methods

Event Description/Notes

createAttachment(identifier, Creates a new attachment associated with the identifier specified.

attachment) The attachment object contains all of the data that corresponds to
the attachment to create.

getAttachments(ids<List>) Retrieves a list of Attachment objects given a list of their IDs.

Incident Service 
The following is the WSDL location for the Operations Incident Service:

https://localhost:9443/services/remedy/IncidentService?wsdl

Table 2-6 Incident Service Details

Incident Description/Notes

get(identifier) Gets the Event with the identifier provided.

find(query) Finds the Event with the endpoint application query specified.

create(object) Creates the Event in the endpoint application.

update(object) Updates the Event in the endpoint application.

close(object) Closes the Event in the endpoint application.

reOpen(object) Event in the endpoint application.

35 VERSION 2.4 REV A01 300-011-512

 OPERATIONS WEB SERVICE METHODS

Also, includes these methods:

• Relationship Methods
• Log Methods
• Attachment Methods

ITObject Service
The following is the WSDL location for the Operations ITObject Service:

https://localhost:9443/services/remedy/ITObjectService?wsdl

Table 2-7 ITObject Service Details

ITObject Description/Notes

get(table, identifier) Gets the object from the table/form specified with the
identifier provided.

find(table, query) Finds the object from the table/form specified with the
endpoint application query specified.

create(table, object) Creates the object in the table/form specified.

update(table, object) Updates the object in the table/form specified.

remove(table, object) Removes the object from the table/form specified.

getAttachments(ids<List>) Retrieves a list of Attachment objects given a list of their

IDs.

For attachments on generic objects, attachments are

retrieved from generic forms just like any other field. These
can be seed in the attachment-reference field. To
get the actual attachment data, the getAttachments()
operation on ITObjectService should be used. To update
an attachment field on a generic form the binary-field
extended field can be used.

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 36
OPERATIONS WEB SERVICE METHODS

Configuration Service
The following is the WSDL location for the Operations Configuration Service:

https://localhost:9443/services/remedy/ConfigurationService?wsdl

Table 2-8 Configuration Service Methods

Configuration Description/Notes

get(identifier) Gets the CI with the identifier provided.

find(query) Finds the CI with the endpoint application query specified.

Problem Service
The following is the WSDL location for the Operations Problem Service:

https://localhost:9443/services/remedy/ProblemService?wsdl

Table 2-9 Problem Service Methods

Configuration Description/Notes

get(identifier) Gets the Problem with the identifier provided.

find(query) Finds the Problem with the endpoint application query specified.

create(object) Creates the Problem in the endpoint application.

update(object) Updates the Problem in the endpoint application.

Also, includes these methods:

• Relationship Methods
• Log Methods
• Attachment Methods

37 VERSION 2.4 REV A01 300-011-512

 OPERATIONS WEB SERVICE METHODS

Change Service
The following is the WSDL location for the Operations Change Service:

https://localhost:9443/services/remedy/ChangeService?wsdl

Table 2-10 Change Service Methods

Change Description/Notes

find(query) Finds the Change with the endpoint application query specified.

create(object) Creates the Change in the endpoint application.

Also, includes these methods:

• Relationship Methods
• Log Methods
• Attachment Methods

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 38
OPERATIONS WEB SERVICE METHODS

39 VERSION 2.4 REV A01 300-011-512

 Chapter 3
System Configuration 1
This chapter identifies the requirements for configuring the EMC Adapter
solution and discusses the following topics:
• Supported Operating Systems
• System Requirements
• Supported Databases

Supported Operating Systems 1
The Adapter software can be installed on the following operating systems:
• Windows - NT4, 2000, XP, 2003 Server, 2008 Server
• UNIX- Solaris 10 (Sparc), HP-UX 11 (Itanium), AIX
• Linux - x86, x64, Kernel 2.6 (or higher)

System Requirements 1
Before you install the Adapter software, your Adapter server must meet the
following system requirements.

Recommended
The following are the recommended system requirements for installing the EMC
Adapter software:
• CPU: Dual Core Processor running 2GHz or higher
• RAM: 2 GB
• Disk Space: 5 GB free disk space
• Java Runtime Environment: JRE 6.0 Update 16 (or above) is recommended.
This is bundled with the Windows installer.

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 40
SUPPORTED DATABASES

Minimum
The following are the minimum system requirements for installing the EMC
Adapter software:
• CPU: Pentium Class or Equivalent Processor or higher
• RAM: 512 MB Free
• Disk Space: 2 GB free disk space
• Java Runtime Environment: JRE 6.0 Update 16 (or above) is recommended.
This is bundled with the Windows installer.

Supported Databases 1
The EMC Adapter uses a relational Apache Derby database for the Persistence
Queue. In addition to the Apache Derby database, the EMC Adapter supports
the following external databases:
• Oracle
• DB2
• Microsoft SQL Server

41 VERSION 2.4 REV A01 300-011-512

 Chapter 4
Software Installation 4
Topics covered in this section:
• Overview
• Configuring SSL Communications
• Installing a License File
• Installing the Adapter Software - Windows
• Running the Adapter Windows Service
• Installing Adapter Software - UNIX
• Running the Adapter UNIX Service
• Manual Installation Procedures

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 42
OVERVIEW

Overview 4
Based on your EMC configuration, the following components may be installed
(see Figure 4-1):
• EMC ITIL Adapters – includes the Adapter software and license file.
• EMC ITIL Adapter Agent (Optional) – includes the Adapter URL Agent
software or custom Agent.The Agent may be installed with the Adapter on
the same server or on a separate server.
• License files – are provided by EMC Customer Support and must be installed
in the appropriate directory.
• EMC Ionix IT Orchestrator (Optional) – includes the Ionix IT Orchestrator
software and license file.
Figure 4-1 Installation Components

EMC
Ionix ITO

43 VERSION 2.4 REV A01 300-011-512

 CONFIGURING SSL COMMUNICATIONS

Configuring SSL Communications 4
To configure SSL communications between the Ionix IT Orchestrator and
Adapter, complete the following steps.
1. From the Adapter server, obtain a copy of the Adapter SSL Certificate.
2. Verify that there is not an existing or incorrect certificate already installed in
the Ionix IT Orchestrator keystore.
3. Copy the hostname.cer file to the Ionix IT Orchestrator server.
4. Confirm that the JAVA_HOME is set to Java 6. Once the JAVA_HOME is verified,
execute the following command to delete the existing certificate:
"%JAVA_HOME%\bin\keytool" -delete -alias iwave -storepass
changeit -keystore "%JAVA_HOME%\lib\security\cacerts"

5. Install the certificate into the Ionix IT Orchestrator keystore.

6. Confirm that the JAVA_HOME is set to Java 6. Once the JAVA_HOME is verified,
execute the following command to store the certificate:
"%JAVA_HOME%\bin\keytool" -import -alias iwave -v -file
iwave.cer -keypass iwave -storepass changeit -keystore
"%JAVA_HOME%\lib\security\cacerts"

Figure 4-2 SSL Configuration

EMC Ionix ITO EMC
Adapter Ionix IT Orchestrator

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 44
INSTALLING A LICENSE FILE

Installing a License File 4
When the Adapter software is purchased, a software license file (in XML format)
is provided by EMC Customer Support. The license file identifies the following
information for each Adapter server included in the EMC software configuration:
• the types of Adapters that can be installed on the server
• the Adapter software version
• the expiry date for the Adapter software
• the license key

During Adapter software installation, the user identifies the location of the
license file. The installer then copies the license file from the original location
to the following EMC Adapter installation directory:

install_root/adapters-2.4/conf

45 VERSION 2.4 REV A01 300-011-512

 INSTALLING THE ADAPTER SOFTWARE - WINDOWS

Installing the Adapter Software ­ Windows 4
This section identifies the steps required for installing the EMC Adapter
software.

Before You Begin
Before you install the EMC Adapter software, complete the following tasks:
• Identify the location of the Adapter license file.
• Close all Windows applications.
• Determine the type of Agent you are installing (if any).
• Determine which Adapter will be installed.
• Determine on which server the Adapter and Agent software will be installed. .

Start the Installer
To install the EMC URL Agent and/or Adapter software, complete the following
the steps:
1. Access the location of the Adapter installer executable. Double-click the
setup-Adapter-winxx_2.4.exe file.
2. The Open File - Security Warning window displays. Click Run.
3. The InstallAnywhere progress screen displays.
Figure 4-3 Installer Progress Screen

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 46
INSTALLING THE ADAPTER SOFTWARE - WINDOWS

4. The progress screen displays.

Figure 4-4 Progress Screen

5. After the InstallAnywhere Wizard finishes loading, the EMC Adapters Installer
Introduction screen displays. From this screen, select the Next button to
continue.
Figure 4-5 Introduction Screen

47 VERSION 2.4 REV A01 300-011-512

 INSTALLING THE ADAPTER SOFTWARE - WINDOWS

6. The Choose Install Set screen displays. From this screen, select the
appropriate installation option.
— For instructions on installing the URL Agent, refer to “Installing the
URL Agent”.
— For instructions on installing your Adapter, refer to “Installing the
Adapter”.
Figure 4-6 Choose Install Set

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 48
 Installing the URL Agent
To install the URL Agent software, complete the following steps:
1. From the Choose Install Set screen, select the URL Agent and corresponding
Python 2.6.1 for Windows install Set. Click Next.
Figure 4-7 Install Set - URL Agent

49 VERSION 2.4 REV A01 300-011-512

 2. The Choose Install Folder screen displays. To change the install folder, click
the Choose button and navigate to the appropriate installation directory.
Click Next.
Figure 4-8 Choose Install Folder Screen

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 50
 3. The Choose Shortcut Folder screen displays. From this screen, specify the
areas where the software shortcut icons will be created. Click the Next button
to continue.
— In a new Program Group – creates a new program group with the
specified name and includes a shortcut in the Windows All Programs
list.
— In an existing Program Group – includes a shortcut in an existing
program group.
— In the Start Menu – includes the Adapter shortcut in the Start menu.
— On the Desktop – creates an Adapter shortcut on the desktop.
— In the Quick Launch Bar – includes the Adapter shortcut in the Quick
Launch menu bar.
— Other – specify a custom directory location by selecting the Choose
button.
— Don’t create icons – Select this option if you do not want to create an
Adapter shortcut.
— Create Icons for All Users – Select this option to create shortcuts for
all users configured on the server. The shortcuts are only added to the
Start Menu and Desktop.

51 VERSION 2.4 REV A01 300-011-512

Figure 4-9 Choose Shortcut Folder Screen

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 52
 4. The Preparing to Install screen displays. Click Install.
Figure 4-10 Preparing to Install

53 VERSION 2.4 REV A01 300-011-512

 5. The Installing Adapters screen displays. This screen displays the progress of
the URL Agent installation.
Figure 4-11 Installing the Adapter

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 54
 6. If you selected to have Python installed, the Python 2.6.1 Setup screen
displays. Select one of the following options and click Next.
— Install for users
— Install just for me (not available for Windows Vista)
Figure 4-12 Python Setup

55 VERSION 2.4 REV A01 300-011-512

 7. The Select Destination Directory screen displays. Click the Up and New
buttons to select a directory for the Python 2.6.1 files.The default directory is
Python26. Click Next.
Figure 4-13 Select a Destination Directory

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 56
 8. The Customize Python 2.6.1 screen displays. Click Next.
Figure 4-14 Customize Python 2.6.1

57 VERSION 2.4 REV A01 300-011-512

 9. The Install Python 2.6.1 screen displays. When the installation completes, click
Next.
Figure 4-15 Install Python 2.6.1

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 58
 10. The Completing Python Installer screen displays. Click Finish button to
complete the Python installation.
Figure 4-16 Completing Python Installer

59 VERSION 2.4 REV A01 300-011-512

 11. The Install Complete screen displays. Click Done to exit the installer.
Figure 4-17 Install Complete

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 60
 Installing the Adapter
1. From the Choose Install Set screen, select the BMC Remedy and Atrium
Adapter option. Click Next.
Figure 4-18 Choose Install Set Screen

61 VERSION 2.4 REV A01 300-011-512

 2. The Choose Install Folder screen displays with the default installation
folder. To change the install folder, click the Choose button and navigate to
the appropriate installation directory. Click Next.
Figure 4-19 Choose Install Folder Screen

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 62
 3. The Choose Shortcut Folder screen displays. From this screen, specify the
areas where the software shortcut icons will be created. Click the Next button
to continue.
— In a new Program Group – creates a new program group with the
specified name and includes a shortcut in the Windows All Programs
list.
— In an existing Program Group – includes a shortcut in an existing
program group.
— In the Start Menu – includes the Adapter shortcut in the Start menu.
— On the Desktop – creates an Adapter shortcut on the desktop.
— In the Quick Launch Bar – includes the Adapter shortcut in the Quick
Launch menu bar.
— Other – specify a custom directory location by selecting the Choose
button.
— Don’t create icons – Select this option if you do not want to create an
Adapter shortcut.
— Create Icons for All Users – Select this option to create shortcuts for
all users configured on the server. The shortcuts are only added to the
Start Menu and Desktop.
Figure 4-20 Choose Shortcut Folder Screen

63 VERSION 2.4 REV A01 300-011-512

 Note: If you choose not to create a menu shortcut, you can start the Adapter
framework using the startAdapters.bat file. This file is located in the
install_root\bin directory.

4. The Choose License File screen displays. From this screen, verify that the
license file location identified in the Please Choose License File field, is
correct. To change the license file location, select the Choose button and
select the appropriate directory. Click Next.
Figure 4-21 Choose License File Screen

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 64
 5. The Enable Security screen displays. On this screen, the Use HTTPS (port
9443) check box is selected by default. This option uses SSL for secure Web-
based communications. To use standard unsecured HTTP Web-based
communications, un-check this box. Click Next.
Figure 4-22 Enable Security screen

65 VERSION 2.4 REV A01 300-011-512

 6. The Web Service Authentication screen displays. From this screen, enter the
Username and Password you want to use for authentication. You must enter
the password twice for confirmation purposes. Click Next.
Figure 4-23 Web Services Authentication

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 66
 7. The Monitoring Server Configuration screen displays. Based on your Adapter
configuration, determine the appropriate step to complete:
— If you are monitoring the Adapter with the Monitoring Server and the
Monitoring Server is on a different host from the Adapter, select the
Specify host for Monitoring Server checkbox. Identify the following
information and click Next:
– URL - identifies the URL location of the Monitoring Server.
– Username - identifies the username for the Monitoring Server.
– Password - identifies the password associated with the username.
— If you are not using a Monitoring Server or your Monitoring Server is
running on the same server as the Adapter, leave the checkbox
unchecked. Click Next.
Figure 4-24 Monitoring Server Configuration

67 VERSION 2.4 REV A01 300-011-512

 8. The Pre-Installation Summary screen displays. Using the scroll bar, review the
information before continuing the installation process.
— If the information is correct, click Next.
— If the information is incorrect, click Previous and change the
configurations on the previous screen. Click Next when done.
Figure 4-25 Pre-Installation Summary

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 68
 9. The Adapters Configuration screen displays. Click Next.
Figure 4-26 Adapters Configuration

69 VERSION 2.4 REV A01 300-011-512

 10. The Get Remedy Connection Settings screen displays.From this screen,
provide the following information and click Next.
— Host - Enter the host name of the computer running the BMC AR
Server (Remedy).
— Port - If Remedy is in its standard configuration utilizing a port mapper
to select its communications port, use the default Port number (0).
Otherwise, provide the port number Remedy has been configured to
use.
— Private Queue - Identify the private queue number.
Figure 4-27 Get Remedy Connection Settings

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 70
 11. The Get Remedy Account Settings screen displays. Enter the Username and
Password you want to use. Click Install to begin the installation process.
Figure 4-28 Get Remedy Account Settings

71 VERSION 2.4 REV A01 300-011-512

 12. The Preparing to Install screen displays. Click Install.
Figure 4-29 Preparing to Install

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 72
 13. The Installing Adapters screen displays. This screen displays the progress of
the installation process. During this step, the Windows Service is installed and
a keystore file is generated for SSL.
Figure 4-30 Installing the Adapter

73 VERSION 2.4 REV A01 300-011-512

 14. The Start Service screen displays. From this screen, select the Start the
Adapter Service checkbox if you want to start the Adapter service during the
installation process.

If you do not start the Adapter Service during installation, the Adapter service
can be started manually. For more information on starting and stopping the
Windows Service, refer to "Running the Adapter Windows Service" on page
78. Click Next.
Figure 4-31 Start Service

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 74
 15. If you selected the Start the Adapter Service option, the following screen
displays.
Figure 4-32 Starting the Adapters Service

75 VERSION 2.4 REV A01 300-011-512

 16. The Install Complete screen displays. Click Done to exit the installer.
Figure 4-33 Install Complete

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 76
77 VERSION 2.4 REV A01 300-011-512
 RUNNING THE ADAPTER WINDOWS SERVICE

Running the Adapter Windows Service 4
The Adapters Windows Service is automatically installed during the installation
process and if selected, is automatically started, as well.

Shortcuts
Based on which option was selected during installation, shortcuts may be
provided from the Windows Start menu for starting and stopping the Windows
Service.
• To start the Adapters Service, select Start>All
Programs>install_root>adapters-2.4>Start Adapters Service.
• To stop the Adapters Service, select Start>All
Programs>install_root>adapters-2.4>Stop Adapters Service.

Executable Location
Two executable files are provided for interacting with the Windows Service:
• adapters.exe: The main executable that launches the service.
• adaptersw.exe: The executable for starting the Service Manager application.

These files are located in the installation bin directory:

install_root/bin

Service Manager Application
The Service Manager application is an application that allows you to configure
options of the service such as turning on debugging. The service can also be
started and stopped from this console.

To start the Manager application, double-click on the adaptersw.exe file. The

Adapters Properties screen displays (see Figure 4-34).

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 78
RUNNING THE ADAPTER WINDOWS SERVICE

Figure 4-34 Adapters Properties - Services Manager Console

79 VERSION 2.4 REV A01 300-011-512

 INSTALLING ADAPTER SOFTWARE - UNIX

Installing Adapter Software ­ UNIX  4
Before You Begin
Before installing the Adapters on the UNIX platform, you must complete the
following tasks:
• For UNIX platform:
— Install the Java Runtime Environment (JRE) 6 Update 11.
— Java 6 must be installed and run on the local computer. If multiple Java
platforms are present on the local computer, make sure that
%JAVA_HOME% points to Java 6 when running the Adapter.
• For both UNIX and Linux (optional):
— Create an “admin” user for running the framework.

Installing the Software
To install the Adapter software on a UNIX platform, run the appropriate setup
application from the Linux or UNIX prompt.
• Linux Installer: setup-Adapter-linux_2.4.bin
• Other UNIX Platforms: setup-Adapter-unix_2.4.bin

Running the Adapter UNIX Service 4
The bin/service.sh script starts and stops the framework as a service. A
special file service.PID is created when the service is started. This is used to
find the PID of the running service. Do not delete this file manually.

• Starting the service: ./service.sh start

• Stopping the service: ./service.sh stop
• Restarting the service: ./service.sh restart
• Service Status:./service.sh status

If you wish the service to start automatically at boot time, the following is a
sample init.d script you can use to call the service.sh script:

#!/bin/sh
IWAVE_USER=admin
IWAVE_SERVICE=/usr/IonixITO/adapters-2.4/bin/service.sh
su - ${IWAVE_USER} -c "$IWAVE_SERVICE" $1

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 80
MANUAL INSTALLATION PROCEDURES

Manual Installation Procedures 4
If an installation is being performed on an unsupported operating system, the
EMC Adapter can be installed manually without the installer.

Before You Begin
Before manually installing the Adapter software, you must complete the
following tasks:
• Ensure that you are installing on either a Windows or UNIX platform.
• Java 6 must be installed and run on the local computer. If multiple Java
platforms are present on the local computer, make sure that %JAVA_HOME%
points to Java 6 when running the EMC Adapter.
• An Adapter license file (license.xml) must be copied to the
install_root\conf directory. If you do not have a license file for your
Adapter, contact your EMC Sales Representative.

Install the Files
To install the files manually on a Windows or UNIX platform, complete the
appropriate steps.

For Windows:
1. Contact EMC Customer Support and request a zipped copy of the Adapter
installer to be placed on the EMC FTP site.
2. From the Adapter server, download the zipped file.
3. Unzip the file and place the extracted file(s) in any directory on any machine
with network access to the computer running the endpoint application.

Note: For Windows installations, there are no registry keys to edit. The
location of these files is referred to as %IonixITO_HOME%.

For UNIX and Linux:
1. Contact EMC Customer Support and request a tarred/zipped copy of the
Adapter installer to be placed on the EMC FTP site.
2. From the Adapter server, download the tarred/zipped file in binary format.
Place the .zip file in the directory where you want the software installed. For
example: /opt/EMC
3. Extract the files included in the zip file. This will create an adapters
directory with several sub directories.
jar xfv adapter-2.4.zip

81 VERSION 2.4 REV A01 300-011-512

 MANUAL INSTALLATION PROCEDURES

4. Change to the adapters/conf directory.

5. Copy your license file to the conf directory. Ensure that the license file is
named license.xml.
6. Change to the adapters/endpoints directory. Access the directory for
your endpoint adapter.
7. Copy the endpoint-spring.xml file to the adapters/conf directory.
8. Using the propertiesEditor.bat utility, modify the following
parameters in the framework.properties file.
— framework.username
— framework.password - use the -h option when setting the
password.
— endpoint.datasource.jdbc.url
— endpoint.datasource.jdbc.username
— endpoint.datasource.jdbc.password
—
9. Change to the adapters/bin directory
10. Run the setup.bat script.
./setup.bat

11. Install the Adapter as a service.

./service.bat install

12. Start the adapters service.

13. After a few seconds, change to the adapters/log directory and view the
framework.log file. At the bottom of the file, the log should indicate that
the adapter framework has started.

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 82
 Chapter 5
Framework Properties 1
During installation, the framework.properties file is installed in the conf
directory. The framework.properties file includes configuration
parameters for the Adapter Framework. Any parameters specified in this file
are automatically recognized by the external (framework.xml) and internal
(inside the framework jars) spring configurations. These parameters allow the
base configuration to be used and only a few parameters should be changed.

The framework.properties file is in the standard Java Properties format.

The file can be edited using a text editor or the properties in the file can be
edited using the PropertiesEditor command.

The properties in the framework.properties file that are encrypted are shown
in the format: "ENC;XXXXX" where XXXXX is the encrypted data.

Note: The Properties Editor tool is only capable of creating these properties
and not reading them.

Properties Editor Tool 1
The Properties Editor is a tool used to edit configuration properties in the
framework.properties file. This command allows encrypted parameters
to be specified.

Starting the Tool
To start the Properties Editor tool, execute the following batch file or shell script
from the command line:
• For Windows: bin/propertiesEditor.bat
• For Unix: bin/propertiesEditor.sh

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 83
 PARAMETERS

Using the Command
When entering the PropertiesEditor command, multiple options can be
specified in a single invocation of the command.

Usage
PropertiesEditor [options] <target-file>

Options
 -p <key>=<value> Sets a property with the key and value specified in plain
text.
 -e <key>=<value> Sets a property with the key and value specified in
encrypted data.
 -h <key>=<value> Sets a property with the key and value specified in SHA-1
Hashed format. This is used for framework passwords.
 -m <file> Merges multiple properties from the file specified to the
target file.

Examples
The following are examples of using the Properties Editor tool:
• To set the framework username and password for authentication, enter the
following command:
bin/propertiesEditor.bat -p framework.username=admin -h
framework.password="Hashed String" conf/
framework.properties

• To set the Adapter hostname, username and password, enter the following
command:
bin/propertiesEditor.bat -p adapter.host=hostname -p
adapter.username=Demo -e adapter.password=password conf/
framework.properties

Parameters 1
The framework.properties file includes two types of properties:
• global framework properties
• Adapter-specific properties

Global Framework Properties
These global framework properties are automatically configured for all
Adapters.

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 84
PARAMETERS

Framework Authentication 
The following properties are used for the Web Services HTTP authentication:
• framework.username - Username to log into the provided web services.
• framework.password - Password to log into the provided web services.
• framework.admin.password - Administrator password to restart the
adapters over JMX.
• framework.auth.enabled - If this is set to true, authentication will be
required. (Default: true)

Default base URLs to Exposed Services
The following properties configure the base URLs for the Adapter services:
• services.url - Base URL for all adapter operations services (https://
${hostname}:9443/services).
• client.url - Base URL for client acquisition service (https://
${hostname}:9443/services).
• notification.url - Base URL for notifications (http://
${hostname}:9080/services/notification).
• acquisitionevent.url - Base URL for acquisition events (http://
${hostname}:9080/services/acquisition-event).

DataSource Properties
The following properties can be modified to enable support for another
database instead of the default (Derby) Persistence database:
• datasource.jdbc.driver – identifies the database driver (i.e.,
com.microsoft.sqlserver.jdbc.SQLServerDriver).
• datasource.jdbc.url – identifies URL to the database (i.e.,
jdbc:sqlserver://hostname:1433;DatabaseName=testdb).
• datasource.jdbc.username - identifies the username to log into the
database.
• datasource.jdbc.password – identifies the password associated with
the database username. If required, the password can be encrypted.

Database Monitoring 
The following properties can be modified to enable monitoring tasks on the
database. Only one Adapter per database can have this enabled.
• datasource.monitor.enabled - identifies if database monitoring is
enabled. (Default: true)

85 VERSION 2.4 REV A01 300-011-512

 PARAMETERS

Acquisition monitoring
The Adapters automatically send the adapter.acquisition.queuesize
and adapter.acquisition.queuewait events to the Monitoring Server
based on the health of the Adapter queue. The following parameters are used
to configure Acquisition monitoring.
• acquisition.monitor.enabled - identifies if Acquisition monitoring is
enabled. (Default: true)
• acquisition.monitor.queue-threshold - identifies the number of
items allowed in the queue before the queuesize event is sent. (Default:
500)
• acquisition.monitor.queue-wait-hours- identifies the number of
hours an item must be on the queue before the queuewait event is sent
(Default: 24)
• acquisition.bufferqueue.limit - identifies the maximum number
of items that are allowed in the buffer queue. (Default: 500)

Automated Alerts
If the Monitoring Server is on a different host from the Adapter, the following
configuration are updated to include the connection settings for the Monitoring
Server. These parameters identify the location to send automated alerts. If you
are using a Monitoring Server and it is installed on the same server as your
Adapter, leave these parameters blank.
• framework.events.url - identifies the Monitoring Server URL location
to send events.
• framework.events.username - identifies the Monitoring Server
username for basic authentication.
• framework.events.password - identifies the password associated with
the Monitoring Server username. The password can be encrypted.

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 86
PARAMETERS

87 VERSION 2.4 REV A01 300-011-512

 BMC Remedy Parameters
The framework.properties file includes the following BMC Remedy
Adapter parameters.

Authentication Parameters
• remedy.host - The host name of the Remedy server. (Default: localhost)
• remedy.username- The username to use when logging in to the Remedy
server. (Default: Demo)
• remedy.password - The password associated with the supplied username.
(No Default )
• remedy.port - The port of the Remedy server. This should be 0 to use the
default RPC mechanism. (Default: 0)
• remedy.privateQueueNumber - The privateQueueNumber that can be
used if the customer desires to use a private queue. The default is 0 and
indicates to not use a private queue. (Default: 0)
• remedy.acquisition.delay - Delay between receiving an event from
Remedy and submitting it to our queue. (Default: 500)

Adapter Parameters
• remedy.serviceId - The Service Identifier to be used for acquisition on
the remedy adapter. (Default: Remedy)
• remedy.itobject.defaultForm- The default form to use for the
itobject acquisition. This is only used when no form is specified. (Default:
HPD:Help Desk)

Incident Management Parameters
• remedy.incident.defaultForm- The default form which stores the
incident objects. (Default: HPD:Help Desk)
• remedy.incident.createForm - The form to use for performing the
'create' operation. (Default: HPD:IncidentInterface_Create)
• remedy.incident.identifierField- The Remedy field identifier (an
integer) that specifies the field storing the incident's unique identifier.
(Default: Incident Number)
• remedy.incident.worklog.form - The form to use for storing/
retrieving work logs. (Default: HPD:WorkLog)
• remedy.incident.worklog.incidentIdentifierField-The
Remedy field name that specifies the field storing the unique identifier for the
incident to which a work log belongs. (Default: Incident Number)
• remedy.incident.associations - Default: HPD:Associations

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 88
 • remedy.incident.closeStatus - The value to set the status field to
when closing an incident. (Default: 5)

Change Management Parameters
The following parameters should only be changed by Customer Support
personnel.
• remedy.change.defaultForm- Default: CHG:Infrastructure Change
• remedy.change.createForm - Default: CHG:ChangeInterface_Create
• remedy.change.identifierField - Default: Infrastructure Change ID
• remedy.change.worklog.form- Default: CHG:WorkLog
• remedy.change.worklog.changeIdentifierField - Default:
Infrastructure Change ID
• remedy.change.associations - Default: CHG:Associations

Remedy Problem Management
The following parameters should only be changed by Customer Support
personnel.
• remedy.problem.defaultForm - Default: PBM:Problem Investigation
• remedy.problem.createForm- Default: PBM:ProblemInterface_Create
• remedy.problem.identifierField - Default: Problem Investigation
ID
• remedy.problem.worklog.form - Default: PBM:Investigation WorkLog
• remedy.problem.worklog.problemIdentifierField - Default:
Problem Investigation ID
• remedy.problem.associations - Default: PBM:Investigation
Associations

89 VERSION 2.4 REV A01 300-011-512

Figure 5-1 Example Framework Properties file - BMC Remedy
## Remedy Adapter

# Remedy Adapter authentication properties

remedy.host = localhost
remedy.username = Demo
remedy.password =
remedy.port = 0
remedy.privateQueueNumber = 0
remedy.acquisition.delay = 500

# Remedy Adapter Properties

remedy.serviceId = Remedy
remedy.itobject.defaultForm = HPD:Help Desk
# Remedy Incident Management
remedy.incident.defaultForm = HPD:Help Desk
remedy.incident.createForm = HPD:IncidentInterface_Create
remedy.incident.identifierField = Incident Number
remedy.incident.worklog.form = HPD:WorkLog
remedy.incident.worklog.incidentIdentifierField = Incident Number
remedy.incident.associations = HPD:Associations
remedy.incident.closeStatus = 5

# Remedy Change Management

remedy.change.defaultForm = CHG:Infrastructure Change
remedy.change.createForm = CHG:ChangeInterface_Create
remedy.change.identifierField = Infrastructure Change ID
remedy.change.worklog.form = CHG:WorkLog
remedy.change.worklog.changeIdentifierField = Infrastructure Change ID
remedy.change.associations = CHG:Associations

# Remedy Problem Management

remedy.problem.defaultForm = PBM:Problem Investigation
remedy.problem.createForm = PBM:ProblemInterface_Create
remedy.problem.identifierField = Problem Investigation ID
remedy.problem.worklog.form = PBM:Investigation WorkLog
remedy.problem.worklog.problemIdentifierField = Problem Investigation ID
remedy.problem.associations = PBM:Investigation Associations

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 90
91 VERSION 2.4 REV A01 300-011-512
 Chapter 6
Configuration 6
After installing the adapter, you must configure the Remedy application to
interact with the IonixITO Remedy Adapter. The process consists of the following
tasks:
• Create an Adapter User Account
• Create a Remedy Filter to Notify the URL Agent

Create an Adapter User Account 6
The IonixITO Adapter interfaces with Remedy as a user and is only capable of
performing tasks at the privilege level of its user account. Any existing
account including the administrator account may be used for this. However,
we recommended your Remedy Administration create an Adapter user
account with appropriate privileges to perform the actions required for the
integration.

Create a Remedy Filter to Notify the URL Agent 6
A filter is used to notify the URL Agent when an incident is created, changed, or
closed in Remedy. To create a Remedy filter, take the following steps.
1. In the BMC Remedy Administrator tool, right-click Filter, and then click New
Filter to display the Create Filter screen with the Basic tab active (see Figure
6-1).

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 92
CREATE A REMEDY FILTER TO NOTIFY THE URL AGENT

Figure 6-1 Create Filter

Adapter Agent

2. In the Filter section, enter a name for the filter in the Name field (i.e., Adapter
Agent).
3. Click the Enable check box.
4. In the Execution Order field, enter 1000. This high value ensures the filter
trigger executes last, allowing Remedy’s workflows to be completed before
invoking the Adapter.
5. In the Form Name scrolling list, click the check boxes next to the forms you
want to apply this filter to.
6. In the Execute On section, click the Submit and Modify check boxes.
7. In the Run If section, enter the following qualifier in the text entry field:
$USER$ != “admin”.

Note: The username should be the name of the Remedy IonixITO User
account created earlier to prevent updates made by IonixITO from
looping back.

93 VERSION 2.4 REV A01 300-011-512

 CREATE A REMEDY FILTER TO NOTIFY THE URL AGENT

8. Click the If Action tab.

Figure 6-2 Create Filter - If Action

9. From the New Action drop down list, select Run Process.
10. In the Run Process area’s Command Line field, enter a command in the
following format to run a script that calls the IonixITO URL Agent. Typically the
filter calls the agent directly providing the full command line call.
"python c:\IonixITO\adapters\agent\agent.py -v
event_service_URL

Where:

— event_service_URL = the Event Notification Service URL

It’s also possible to call a batch file in the event the command line input is
to long for the command line field. Enter a command for each Event
Notification Service URL:

— http://localhost:8080/services/notification/remedy/incident/$Incident
Number$
— http://localhost:8080/services/notification/remedy/configuration/
$ClassId$~$InstanceId$
— http://localhost:8080/services/notification/remedy/problem/
$Problem Investigation ID$
— http://localhost:8080/services/notification/remedy/change/
$Infrastructure Change ID$
— http://localhost:8080/services/notification/remedy/itobject/
FORMNAME/$IncidentNumber$

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 94
CREATE A REMEDY FILTER TO NOTIFY THE URL AGENT

Note: For configuration items, a synthesized identifier is used. This is

composed of the class ID and the instance ID. These fields are
separated by a tilde (~) character.

Figure 6-3 shows an example of a batch file call and how to send the
proper parameter. This is basically the same call as the direct call with the
exception that the $Incident Number$ is passed into the batch file as a
parameter and is replaced with %1.

Figure 6-3 Agent.bat file

11. Click Add Action.

12. Click the Save icon in Remedy.

95 VERSION 2.4 REV A01 300-011-512

 Chapter 7
Custom Configuration 1
Topics covered in this section:
• Client Acquisition Service
• Adapter High Availability
• Java to Adapter Integration
• Persistence Database Management

Client Acquisition Service 1
The Client Acquisition service allows customers to leverage the EMC
Acquisition Services with their data. Customer data can be added to the
existing EMC Acquisition system. Processes in Ionix IT Orchestrator can be
configured to feed off of their data similar to the existing Adapter workflows.
Two services are provided for getting data into the Acquisition Queue. Both
provide the exact same features, but allow customers to choose the easiest
integration point.

Data Format
The data must be provided in the following XML format:

<?xml version="1.0“ encoding=”UTF-8”?>

<client-object>
<!-- Any client XML can go in here -->
</client-object>

Object Format
Schema for the client object (client-object.xsd):

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<xs:schema version="1.0" xmlns:xs="http://www.w3.org/2001/
XMLSchema">

<xs:element name="client-object" type="clientDefinedObject"/

>

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 96
CLIENT ACQUISITION SERVICE

<xs:complexType name="clientDefinedObject" mixed="true">

<xs:sequence>
<xs:any processContents="skip" namespace="##other"
minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
</xs:schema>

To provide data to the acquisition queue, customers must always specify the
serviceId and objectType along with the object data.
• serviceId - Unique identifier of the service that placed this data here.
This is used to differentiate between different applications that push data into
the queue.
• objectType - Unique type of the object. This should not be one of the built
in types (Incident, Event, CI, Change, Problem, ITObject). It can be any unique
name to identify the customer's data.
The return for the service provides the ID of the transaction back to the client.
This can be used to correlate the call with the transaction that appears in the
queue.

RESTful Client Acquisition
For the Client Acquisition endpoint, HTTP POST to the following address:

https://localhost:9443/services/client-acquisition/{serviceId}/{objectType}:

Replace {serviceId} and {objectType} with the desired values.

• HTTP Basic Authentication is expected to authenticate the user.

• If a problem occurs, and HTTP 500 (Internal Error) response code is returned,
the content of the response contains the error message. A HTTP 200 code
indicates the request was processed normally. Any HTTP 4xx codes indicate
some sort of client error.

Note: If you have a form with a ":" colon in it, use the ASCII Hex decimal with a
"%" sign prefix to escape it in the Restful service URL.

Calling the RESTful Client Acquisition from curl
In order to call the RESTful Client Acquisition from curl, the URL Agent must be
installed. Once the URL Agent is installed, complete the following tasks:
1. Create an XML file with the root node of the client-object.
<?xml version="1.0" encoding="UTF-8"?>
<client-object>
<!-- Any client XML can go in here -->
</client-object>

2. From the command line, call the following command:

97 VERSION 2.4 REV A01 300-011-512

 CLIENT ACQUISITION SERVICE

python agent.py -l -v -x {filename} https://

iwave:password@localhost:9443/services/client-acquisition/
{serviceId}/{objectType}

3. An HTTP/1.1 200 OK response is sent and the data should be in the Acquisition
Queue.

SOAP Client Acquisition Web Service
The following is the location of the SOAP Client Acquisition Service WSDL:
https://localhost:9443/services/ClientAcquisitionService?wsdl

If an error occurs, a web service fault is thrown matching the framework

exception
com.iwave.acquisition.client.AcquisitionException.
This exception contains a message with the details of the problem. HTTP Basic
Authentication is expected to authenticate the user.

Running on another port
To run the Client Acquisition service from another port, you must modify the
client-acquisition-spring.xml file. Figure 7-1 identifies the spring
configuration file for the client acquisition service. In this file, perform the
following modifications:
1. Replace the ${services.url} with the required URL and port number
(i.e., 9080).

Note: If you specify port 9443, you must use HTTPS in the URL.

2. If you need to disable authentication, delete the following three lines in the
two places they occur.
<jaxws:inInterceptors>
<ref bean="securityInterceptor"/>
</jaxws:inInterceptors>

3. To start a second copy of the Acquisition Service, copy the modified file to the
conf directory.

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 98
CLIENT ACQUISITION SERVICE

Figure 7-1 Spring Configuration

<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance
xmlns:jaxws="http://cxf.apache.org/jaxws"
xmlns:jaxrs="http://cxf.apache.org/jaxrs"
xmlns:lang="http://www.springframework.org/schema/lang"
xsi:schemaLocation="
http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-
beans.xsd
http://cxf.apache.org/jaxws
http://cxf.apache.org/schemas/jaxws.xsd
http://cxf.apache.org/jaxrs
http://cxf.apache.org/schemas/jaxrs.xsd
http://www.springframework.org/schema/lang
http://www.springframework.org/schema/lang/spring-lang-
2.0.xsd">

<bean id="clientAcquisitionService2"
class="com.iwave.acquisition.client.ClientAcquisitionService"
>
<property name="queue" ref="acquisitionQueue"/>
</bean>

<!-- Restful exception handler -->

<bean id="acquisitionExceptionProvider2"
class="com.iwave.acquisition.client.AcquisitionExceptionMappe
r"/>

<!-- Endpoints -->

<jaxws:endpoint
id="clientAcquisitionServiceEndpoint2"
implementor="#clientAcquisitionService2"
implementorClass="com.iwave.acquisition.client.
ClientAcquisitionService"
address="${services.url}/ClientAcquisitionService2">
<jaxws:inInterceptors>
<ref bean="securityInterceptor"/>
</jaxws:inInterceptors>
</jaxws:endpoint>

<jaxrs:server id="clientAcquisitionServiceRest2"
address="${services.url}/client-acquisition2">
<jaxrs:inInterceptors>
<ref bean="securityInterceptor"/>
</jaxrs:inInterceptors>
<jaxrs:serviceBeans>
<ref bean="clientAcquisitionService2"/>
</jaxrs:serviceBeans>
<jaxrs:providers>
<ref bean="acquisitionExceptionProvider2" />
</jaxrs:providers>
</jaxrs:server>
</beans>

99 VERSION 2.4 REV A01 300-011-512

 ADAPTER HIGH AVAILABILITY

Adapter High Availability 7
The EMC Ionix IT Orchestrator Adapter solution may be scaled to allow more
Adapters in the network configuration. Adapter scaling may be performed for
the following reasons:
• to increase the number of transactions being processed
• to provide high-availability (i.e., redundancy)
• to handle additional simultaneous requests
Figure 7-2 provides an illustration of a network configuration with multiple
Adapters utilizing an external Acquisition database.

Figure 7-2 Adapter Scaled Network Configuration

Operations Services Scaling
The Operations Web Services can be scaled easily. The operations are
essentially stateless, allowing a second adapter to be installed on another
system that can handle the operations. If the primary Adapter fails, workflows
can be updated to switch to use a secondary Adapter’s operations services.

Acquisition Services Scaling
The Acquisition Services component of the Adapter architecture can be scaled
by completing the following steps:
1. Offload the Acquisition Queue to an external database.
2. Use the external database with multiple Adapters.

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE
ADAPTER HIGH AVAILABILITY

Use the External Database for Multiple Adapters
Each Acquisition Service is pulling from the same shared queue. A second
adapter install can be used to handle additional acquisitions. Workflows can
be updated to switch to the second adapter if the acquisition queue
operations fail on the primary server.

Adapter Failover Infrastructure
Since it is difficult to add logic for Adapter failover within workflows, specific
infrastructure must be implemented to handle Adapter failover. The following
are options for implementing high-availability for the EMC Adapters:
• Round-Robin DNS Server - A Round-Robin DNS can be used to allow a single
hostname to provide access to multiple IP addresses representing the
multiple Adapter environments installed. With this configuration, if the
primary Adapter server goes out-of-service, the DNS server can point users to
the secondary Adapter server that is in-service.
• Highly Available HTTP Proxy Server - A highly available HTTP Proxy server
can be used to forward requests between Adapters. When the primary
Adapter server goes out-of-service, the HTTP proxy server should be able to
forward requests to a secondary Adapter server that is in-service.

Agent Scaling
It is assumed that if the endpoint application is up and running, it should be
able to invoke the Agent script running within that environment. The agent
needs to only notify one acquisition adapter that is running. The reason is that
the message only needs to be added to the queue once.

There are two options for this:

• If the customer has a Round-Robin DNS or proxy set up that allows access to
any of the installed adapters that are running, this can be used from the agent.
The agent would point to the single hostname. One of the adapters receives
the request and add it only once to the queue.
• If multiple URLs are present on the agent command line, it makes the request
to only one of them, the first available one. Store-forwarding is still provided
but is only used if none of the services can be reached.

101 VERSION 2.4 REV A01 300-011-512

 JAVA TO ADAPTER INTEGRATION

Java to Adapter Integration 7
If a Java application must be used to push information into any of the Adapter
RESTful web services, specific Java code must be used. Figure 7-3 includes a
Java code sample used to perform an HTTP POST or GET with the EMC
Adapter.

Prerequisites
In order to use this code, you need to download the Apache Commons HTTP
Client version 3.1. The Commons HTTP Client can be downloaded from the
following location:

http://hc.apache.org/downloads.cgi
From the Apache Http Components Downloads page, scroll down and select to
download the Commons HttpClient 3.1. To use this client, you also need the
following jar files:
• commons-httpclient-3.1.jar
• commons-codec-1.3.jar
• commons-logging-1.1.1.jar

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE
JAVA TO ADAPTER INTEGRATION

Figure 7-3 Sample Java code

package com.iwave.net;
import java.io.IOException;
import org.apache.commons.httpclient.HttpClient;
import org.apache.commons.httpclient.HttpException;
import org.apache.commons.httpclient.HttpStatus;
import org.apache.commons.httpclient.methods.GetMethod;
import org.apache.commons.httpclient.methods.PostMethod;
import org.apache.commons.httpclient.methods.StringRequestEntity;
/**
* Example of making an HTTP GET or POST in Java.
*
*
*/
public class SimpleHTTPClient {

public String post(String url, String xml) throws HttpException,

IOException {
HttpClient client = new HttpClient();
PostMethod method = new PostMethod(url);
try {
if (xml != null) {
method.setRequestEntity(new StringRequestEntity(xml,
"text/xml" , "UTF-8"));
}

// Execute the method.

int statusCode = client.executeMethod(method);
if (statusCode != HttpStatus.SC_OK) {
throw new IOException("HTTP POST method failed: " +
method.getStatusLine());
}
return method.getResponseBodyAsString();
}
finally {
method.releaseConnection();
}
}

public String get(String url) throws HttpException, IOException {

HttpClient client = new HttpClient();
GetMethod method = new GetMethod(url);
try {
// Execute the method.
int statusCode = client.executeMethod(method);
if (statusCode != HttpStatus.SC_OK) {
throw new IOException("HTTP GET method failed: " +
method.getStatusLine());
}
return method.getResponseBodyAsString();
}

103 VERSION 2.4 REV A01 300-011-512

 PERSISTENCE DATABASE MANAGEMENT

Persistence Database Management 7
This section discusses the following maintenance tasks that can be performed
on the Persistence database.
• Removing Transactions
• Reclaiming Unused Disk Space
• Connecting to the Database
• Changing the Database Port Number
• Offloading the Acquisition Queue to an External Database

Removing Transactions 
The pruning service removes all transactions that are older than 7 days and are
in the “Error” state from the Persistence database. The service runs every night
at 3:00 a.m.

Reclaiming Unused Disk Space
After large amounts of data have been deleted or updated on the Derby
database, a Derby table or index can contain unused space. By default, Derby
does not return unused space to the operating system. However, Derby does
provide a way to reclaim unused space in tables and associated indexes.

If you determine that a table and its indexes have a significant amount of unused
space, use one of the following procedures to reclaim the space:
• SYSCS_UTIL.SYSCS_COMPRESS_TABLE - is guaranteed to recover the
maximum amount of free space, at the cost of temporarily creating new tables
and indexes before the statement in committed.
• SYSCS_UTIL.SYSCS_INPLACE_COMPRESS_TABLE - attempts to reclaim space
within the same table, but cannot guarantee it will recover all available space.
This procedure uses no temporary files and moves rows around within the
same table or index.
For more information, refer to the Apache Derby Administration Guide.

To reclaim space in the table and recreate the indexes, execute the following
script from adapters/bin directory:

runScript.bat derbyMaint

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE
PERSISTENCE DATABASE MANAGEMENT

Connecting to the Database
To connect to the Adapter Derby database over the network, use the Java
driver derbyclient-10.4.2.0.jar. The following URL will connect to the Derby
database running in the Adapter.

jdbc:derby://HOST:1528/persistence-db

Changing the Database Port Number
To change the port number of the database, modify the
derby.drpa.portNumber in the system.properties file located in the
conf directory.

Offloading the Acquisition Queue to an External Database
In addition to the Apache Derby database, the Acquisition Queue can be
offloaded to an external database. To enable support for another database,
complete the following steps:
1. Download the JDBC driver for the required platform and place the file in the
lib/adapters directory in the adapter install directory.
2. Modify the following properties in the Adapter framework.properties
file:
— datasource.jdbc.driver: identifies the database driver name
(i.e., com.microsoft.sqlserver.jdbc.SQLServerDriver).
— datasource.jdbc.url: identifies the URL to the database
(i.e., jdbc:sqlserver://hostname:1433;DatabaseName=testdb).
— datasource.jdbc.username: Username
— datasource.jdbc.password: Password. This can be encrypted if
desired.
3. Restart the Adapter.

For the database to be highly available, database clustering technologies

should be used. Refer to the appropriate database documentation for more
information.

105 VERSION 2.4 REV A01 300-011-512

 Chapter 8
Ionix IT Orchestrator Configuration 1
Topics covered in this chapter:
• Using the ITIL Adapter Plugin
• Adapter API

Using the ITIL Adapter Plugin 1
The ITIL Adapters plugin for Orchestrator enables the ITIL Adapters to be easily
used from EMC Ionix IT Orchestrator and leverages the Adapter API.

Associated Files
The following files are utilized by the Adapters plugin:
• com.iwave.ext.adapters_x.x.zip – This is the core of the Adapters plugin for
Orchestrator. This plugin provides the ‘TransactionProcessor’ for acquisition
and the Tasks for operation services. It also contains the full Adapter API jar
files so that they can be used within workflows.
• com.iwave.ext.adapters.httpdispatcher_x.x.zip - This archive contains the
AdaptersDispatcher.war. This needs to be loaded with the container
and provides an endpoint that communicates with the adapters push
mechanism. Extract this zip to the root of the container and it should be
unpacked in the correct directory.
• com.iwave.ext.adapters.examples_x.x.zip – (Optional) This is an
Orchestrator project that should be imported into Studio. It contains some
tests and examples on how to use the push mechanism. This project is not
required to use this plugin but is helpful as a starting point and example.

Installation and Configuration
HTTP Dispatcher 
(com.iwave.ext.adapters.httpdispatcher_2.3.1)
This component is a web application that provides a Web API used by the
Adapter to push to the Ionix IT Orchestrator. This is required for the

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 106
USING THE ITIL ADAPTER PLUGIN

Acquisition Push feature. The web application is packaged as a single file

called AdaptersDispatcher.war.

To install this component:

1. Copy the AdaptersDispatcher.war file to the conf/webapps/
directory of the container.
2. Extract the zip file to the root container directory and it will be placed in the
correct location.
3. If you do not wish to use a standalone container install, there is a container
install bundled with studio. This container install is located in directory
plugins/com.enigmatec.ems.platform_4.0.0.
4. Ensure that a JAAS login module is set up for the container. The default
container install sets up JAAS to use conf/JaasAuth-windows.conf.
This enables Windows based authentication, which will always succeed if the
user is logged in.

Adapters Plugin (com.iwave.ext.adapters_2.3.1)
The com.iwave.ext.adapters plugin needs to be installed in both Studio
and the container. This is installed like any other Ionix IT Orchestrator plugin. A
new version of this plugin will be required for a new release of the adapters as
it contains the API for a specific adapters version.

To install this plugin:

1. Extract the com.iwave.ext.adapters_2.3.1.zip to the base studio
directory. This will install the plugin into the plugins directory of studio. If a
previous version of the plugin exists, remove it by removing the
plugins\com.iwave.ext.adapters* from the studio installation.
2. A sample container startup script called adapters-container.bat is
provided with the examples project. After extracting the examples project,
you can find this file in the resources directory. The following jar files from the
plugin need to be on the classpath for the container. The adapters-
container.bat script takes care of this for you.
— plugins\com.iwave.ext.adapters_2.3.1\adapters.jar
— plugins\com.iwave.ext.adapters_2.3.1\lib\api-
2.3.jar
— plugins\com.iwave.ext.adapters_2.3.1\lib\ejb3-
persistence-1.0.2.GA.jar
adapters-container.bat:

set ORCH_HOME=c:\iWaveSoftware\orchestrator-
studio\plugins\com.enigmatec.ems.platform_4.0.0

set
CONTAINER_CLASSPATH=%ORCH_HOME%\..\com.iwave.ext.adapters_2.3.1\adapte
rs.jar;%CONTAINER_CLASSPATH%

107 VERSION 2.4 REV A01 300-011-512

 USING THE ITIL ADAPTER PLUGIN

set
CONTAINER_CLASSPATH=%ORCH_HOME%\..\com.iwave.ext.adapters_2.3.1\lib\ap
i-2.3.jar;%CONTAINER_CLASSPATH%

set
CONTAINER_CLASSPATH=%ORCH_HOME%\..\com.iwave.ext.adapters_2.3.1\lib\ej
b3-persistence-1.0.2.GA.jar;%CONTAINER_CLASSPATH%

%ORCH_HOME%\bin\container -r c:\iWaveSoftware\orchestrator-repository-
adapters

Adapters Push Configuration
The com.iwave.ext.adapters.examples project contains samples of
implementing a push handler. The sample sets up two push clients that can be
accessed via the URLs https://localhost:8444/TransactionDispatcher/ClientA
and https://localhost:8444/TransactionDispatcher/ClientB. These need to be
specified in the adapters configuration.
• Adapters - To enable the push mechanism on the adapters, the
acquisition-push-spring.xml file needs to be placed in the conf
directory of the adapters. This should contain the content below. Note that
multiple QueueProcessors can be included to perform pushes from multiple
different objectType/serviceIds.
acquisition-push-spring.xml

<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd">
<bean>
<property name="threads" value="3"/>
<property name="objectType" value="*"/>
<property name="serviceId" value="*"/>
<property name="pusher">
<bean>
<property name="url" value="https://prime:8444/
AdaptersDispatcher/ClientA"/>
<property name="username" value="admin"/>
<property name="password" value="admin"/>
</bean>
</property>
</bean>
</beans>

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE
USING THE ITIL ADAPTER PLUGIN

Using the Plugin
This section describes how to use the adapters plugin.

Acquisition
The adapters plugin provides a special ME type to handle TransactionRecords
pushed from the adapters. A service can be created to implement this ME type
by creating a new Service and adding the super type TransactionProcessor.

Figure 8-1 Creating a New Service

The TransactionProcessor type requires an effector to be implemented named

processTransaction. This effector provides a TransactionRecord as a parameter
that has to be processed by the workflow. When the workflow successfully
completes, the record will be marked as complete in the adapters.

The effector has two return fields:

• transactionResponse - This field indicates if the processing of the record was
successful or not. There are three possible values for this return:

109 VERSION 2.4 REV A01 300-011-512

 USING THE ITIL ADAPTER PLUGIN

— com.iwave.ext.adapters.acquisition.TransactionResponse.OK -
Indicates that the processing was successful. This responds to the
adapters with a success code and the transaction will be completed
(unless it was manually changed through the workflow.
— com.iwave.ext.adapters.acquisition.TransactionResponse.ERROR_R
ETRY - Indicates that there was an error processing the record. The
adapters will retry this again after the usual interval. This is the default
handling for errors.
— com.iwave.ext.adapters.acquisition.TransactionResponse.ERROR_
NO_RETRY - Indicates that there was an error processing the record
that will always fail and it should not be retried again.
• errorMessage - If an error occurred, this contains the text that is passed to the
Adapters. This is useful for logging the error back into the adapters logs and to
Monitoring Server.

Operations
The adapters plugin provides Services for each of the common services
available in the adapters API. Theses services are available from the palette
under the com.iwave.ext.adapters heading. They can be dropped onto
any workflow.

Figure 8-2 Workflow

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE
USING THE ITIL ADAPTER PLUGIN

Configuration of the adapter services is done from the service organization. You
need to specify the following configuration parameters to connect to the
adapters web services.
• wsdl - URL to the WSDL for the web service. This may be a URL to a resource or
the local file system and does not necessarily need to be the remote endpoint.
• endpointUrl - The URL to the endpoint to use for the web service. If this is null
then the endpoint URL contained in the WSDL file is used.
• username - The HTTP Basic Authentication username to use for
authentication to the adapters.
• password - The HTTP Basic Authentication password to use for authentication
to the adapters.
Figure 8-3 Client Service Organization

111 VERSION 2.4 REV A01 300-011-512

 ADAPTER API

Adapter API 8
The Adapter API is a subset of the Adapter Framework that contains the
common object model and services that are used for all of the ITIL adapters.
All Adapter services are exposed as Web Services. This API provides a
mechanism for integrating Java-based tools with the adapters. The
functionality of this API is exactly the same as what can be used from the Web
Services.

Note: This API cannot be used if you need to integrate a non Java-based
system with the adapters.

The Adapter API uses JAX-WS to connect to the API using the standard Web
Services.

Software Requirements
When using this ITIL Adapter API with Ionix IT Orchestrator, the following
software is required:
• Java version 6
• Adapters version 2.3 (or later)

API Distribution
The API distribution zip file (i.e., api-2.4.zip) contains the following files and
directories:
• javadocs - JavaDoc documentation for the API. This should be used as a full
reference for the API operations.
• lib/api-2.3.jar - This is the main API archive.
• lib/ejb3-persistence-1.0.2.GA.jar - The API depends on the JPA
('javax.persistence') APIs. This is part of JEE but is provided as a standalone jar
file.
• lib/log4j-1.2.14.jar - The API does limited logging in certain situations. The
log4j logger jar file is required for this.

Package Descriptions
The following are the descriptions of the packages included in the API:
• com.iwave.acquisition - Object model and services for the adapter
acquisition services.
• com.iwave.adapters - Adapters Client API entry point.
• com.iwave.batch - Object model and services for the adapter batch services.

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE
ADAPTER API

• com.iwave.ims - Object model and services for the Monitoring Server

services.
• com.iwave.itom - The IT Object Model and supporting helper classes.
• com.iwave.operations - The Adapters operational services (IT endpoint
operations).
• com.iwave.util - Various internal utilities required by the API.

Key Classes
This following are the descriptions of the key classes in the API. For complete
information on the API and methods available, consult the Javadocs.
• com.iwave.adapters.AdapterClient - This is a utility class for getting client
proxies to the acquisition, Monitoring Server, batch and operation services.
• com.iwave.itom.support.XmlSerialization - This is a utility for serializing
and deserializing adapter object models to/from XML.
• com.iwave.itom.extended.ExtendedFieldFactory - This is a utility class for
creating extended fields from k-v Map constructs or getting Maps from
extended fields. This is the easiest way of working with extended fields from
Java.

Service Classes
The following are the Service Classes included in the API:
• Acquisition Services:
— IAcquisitionService - Acquisition Services for interacting with the
adapters queue.
— IAcquisitionManagementService - Management information about the
adapter queue.
• Batch Services:
— IBatchService - Batch services.
• iWave Monitoring Server Services:
— IIWaveEventService - Monitoring Server Service for publishing events.
• IT Operational Services:
— IITObjectService - ITObject Operations service.
— IITObjectAttachmentService - ITObject Operations service. This also
supports attachments and must be used for operations for adapters
that support attachments.
— IIncidentService - Incident Operations service.
— IIncidentAttachmentService - Incident Operations service. This also
supports attachments and must be used for operations for adapters
that support attachments.
— IChangeService - Change Operations service.

113 VERSION 2.4 REV A01 300-011-512

 ADAPTER API

— IChangeAttachmentService - Change Operations service. This also

supports attachments and must be used for operations for adapters
that support attachments.
— IProblemService - Problem Operations service.
— IProblemAttachmentService - Problem Operations service. This also
supports attachments and must be used for operations for adapters
that support attachments.
— IConfigurationService - Configuration Item Operations service.
— IDeviceService - Device Operations service.
— IDomainDeviceService - Device Operations service that accepts the
domain/network as an extra parameter to each call. This is required for
adapters such as ITOI that has this capability.
— IEventService - Event Operations service.
— IEventServiceDestination - Event Operations Service that requires the
destination/domain to be specified on each call. This is required for
adapters such as SCOM that has this capability.

SSL Certificates
If the Adapter service is using a self signed certificate, JAX-WS may fail to
establish an SSL connection. There are two options for dealing with this
potential failure:
• Install the SSL Certificate from the adapters into the trust keystore for the Java
application using the API.
• Disable trust verification for SSL. This can be dangerous on the public internet
allowing for man-in-the-middle attacks but is generally not a problem where
customers have a secure pipe to begin with. This is almost always the case for
our customers. The 'com.iwave.ext.adapters.examples' orchestrator project
contains an example of installing a trust-all security manager.

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE
ADAPTER API

Java Code Examples
This section includes Java code examples of the Acquisition Services and
Incident Services. For complete examples on how to use this API from Ionix IT
Orchestrator, see the 'com.iwave.ext.adapters.examples' orchestrator project
that is available with the API.
Figure 8-4 Acquisition Example

// Example using the acquisition services

IAcquisitionService acquisition = AdapterClient.get(IAcquisitionService.class,
"https://hostname:9443/services/AcquisitionService?wsdl", "iwave", "password");

// Example creating a service with no authentication:

//IAcquisitionService acquisition = AdapterClient.newClient(IAcquisitionService.class,

// "https://hostname:9443/services/AcquisitionService?wsdl");

// Example creating a service with an alternate endpoint URL:

//IAcquisitionService acquisition = AdapterClient.newClient(IAcquisitionService.class,

// "https://hostname:9443/services/AcquisitionService?wsdl",
// "https://alternatehost:9443/services/AcquisitionService",
// "iwave", "password");

// Calling count
System.out.println("Adapter queue count: " + acquisition.count());

115 VERSION 2.4 REV A01 300-011-512

 ADAPTER API

Figure 8-5 Incident Operations Example

// Example using the incident service. After this service is created,

// this proxy should be cached. Creating this every time is expensive.
IIncidentAttachmentService inc = AdapterClient.get(IIncidentAttachmentService.class,
"https://hostname:9443/services/ionix-sm/IncidentService?wsdl", "iwave",
"password");

// Retrieving an incident
Incident incident = inc.get("2");
System.out.println("Incident Found: " + incident.getIdentifier());
System.out.println(" Desc: " + incident.getDescription());

// Print the entire incident content as XML

System.out.println(incident);

// Example accessing extended fields.

// This can be used to access a single field but it is not efficient

System.out.println("Field 'MODE': " + incident.getExtendedField("MODE",
StringField.class).getValue());

// This should be used for easiest access to bulk fields.

// This creates a map for accessing fields by key/value pairs
Map<String,Object> fields =
ExtendedFieldFactory.fieldsToMap(incident.getExtendedFields());
System.out.println("Field 'MODE': " + fields.get("MODE"));

// Updating an Incident
Incident updateIncident = new Incident();
// ID is required for updates
updateIncident.setIdentifier("2");
updateIncident.setDescription("Updated the description");

// Creating extended fields on update (Single mode)

//updateIncident.addExtendedField("MODE", "REVIEW");

// Creating many extended fields. (This will probably change to Map<String,Object>)

Map<Object,Object> updateFields = new HashMap<Object,Object>();
updateFields.put("MODE", "REVIEW");
updateIncident.addExtendedFields(updateFields);
// or
//
updateIncident.setExtendedFields(ExtendedFieldFactory.newExtendedFields(updateFields));

// Perform the update

System.out.println(updateIncident);
System.out.println(inc.update(updateIncident));

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE
ADAPTER API

117 VERSION 2.4 REV A01 300-011-512

 Chapter 9
Using the URL Agent 1
The chapter discusses the following topics:
• About the Adapter URL Agent
• Python Requirement
• URL Agent Daemon
• Logging
• Running the URL Agent
• URL Agent Filtering

About the Adapter URL Agent 1
If an Adapter does not require a specialized Agent, an EMC Ionix IT
Orchestrator Adapter URL Agent can be installed. The main function of the
URL agent is to perform an HTTP GET or POST operations against the adapter.
An external application could be used to perform these functions, but the URL
Agent provides some capabilities that may not be readily available from
another client.

The URL Agent includes the following capabilities:

• Store-Forward Capability - This means that if the Adapter is not running or
there is a network outage, the transactions are stored in a local data file. These
transactions are forwarded when the Adapter is available again.
• HTTPS and HTTP Basic Authentication - for secured communications and
authentication.
• Retrying on Retryable Error Codes - The Adapter Framework will return an
HTTP Status Code for different types of errors. The URL Agent provides
retrying on retryable error codes from the Adapter.

Python Requirement 1
Python 2.6 is required for the URL Agent. During installation, if the URL Agent
is selected, the Python software is automatically installed.

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 118
URL AGENT DAEMON

URL Agent Daemon 1
The Adapter URL Agent consists of two components: the agent and the agent
daemon.

The URL Agent daemon is a lightweight process that runs in the background and
makes requests to the Adapter(s). The URL Agent makes use of the Agent
daemon background service. When started, the agent daemon provides
ordered access to the adapter and to the store-forward data file. This daemon
will remain running after the GET or POST operation is complete. It consumes
minimal resources and allows future transactions to be executed much faster.
Only one instance of the daemon is running at a time.

The agent uses TCP/IP port 50011 (by default) to communicate with the URL
Agent daemon.

Shutting Down and Starting the Daemon
The Agent daemon is automatically started when the URL Agent is installed. If
the daemon needs to be shutdown and restarted, enter the following
commands:
• To shutdown the agent daemon, enter the command:
agent.py –s
• To start the Agent daemon, enter the command:
agent.py –d

Logging 1
All logging is performed by the Agent daemon. A single log file is used for all
requests going out. Error messages are logged to the file in ../log/
agent.log. By default, the logging is minimal. This is recommended for
production usage. If there is a problem, verbose logging can be enabled by
adding the -v flag on the command when the Agent daemon is started.

When enabling verbose logging, it is recommended to first shutdown the

daemon and then start the daemon with verbose logging. To enable verbose
logging, enter the following commands:
• agent.py -s
• agent.py -d –v

If a request is made without using the agent daemon, the local option can be
used. The agent daemon is not used or started when this option is used and
store-forward is disabled. The following is a sample of using this option with
verbose logging on.

agent.py -v -l http://localhost:9080/services/adapter

119 VERSION 2.4 REV A01 300-011-512

 RUNNING THE URL AGENT

Running the URL Agent 1
The URL Agent execution parameters are as follows:

Usage:
agent.py [options] url1 [alternate-urls ...]

Options:
 -h, --help Shows this help message and exits.
 -a key=value Specifies an attribute in key=value format.
 -x XML_FILE, --xml-file=XML_FILE
Specifies the XML File that contains data to POST to the
url.
 -f ATTRS_FILE, --attrs-file=ATTRS_FILE
Specifies the file that contains a list of key=value@$
attributes.
 -e, --environment-variables
Each environment variable is taken as a key/value pair to
pass as data.
 -u USERNAME, --username=USERNAME
Username for HTTP Basic Authentication.
 -p PASSWORD, --password=PASSWORD
Password for HTTP Basic Authentication.
 -r, --resubmit Resubmit all items from the dead queue back to the store
(not
available with the -l option).
 -c, --clear Clears all items in the dead queue. (Not available with the
-l option).
 -v, --verbose Enables verbose logging for the agent daemon.
 -l, --local Do not attempt to use the agent daemon. The log file is
not created and store-forward is disabled.
 -d, --daemon Starts the agent daemon in the foreground. This
command does not return.
 -s, --shutdownShuts down the background agent daemon. Exits
immediately after shutdown.

Example Commands
The following are example commands for using the URL Agent:
• To perform an HTTP GET to the URL, use the following command:
agent.py http://localhost:9080/services/adapter

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE
URL Agent Filtering

• To perform an HTTP GET to the adapter in a fail-over environment, enter the

command with two URLs:
— If the first URL is not reachable, the second is tried.
— If none are reachable, the store-forward mechanism is engaged. Only
one URL is notified.
agent.py http://host1:9080/services/adapter http://
host2:9080/services/adapter
• To perform an HTTP POST to the URL specified with an XML payload that has
the key/value pair specified, enter the following command. The XML schema
is the format understood by the adapters.
agent.py -a key=value http://localhost:9080/services/
adapter

The XML Format used by the adapters will look like this:

<?xml version="1.0" encoding="UTF-8"?>

<data>
<string-field name="key">value</string-field>
</data>

• To perform an HTTP POST to the URL specified with an XML payload with the
key/value pairs retrieved from a text file, enter the following command. The
XML schema is the format understood by the adapters. The text file lines must
be terminated in @$ to denote the end of a line (they can span multiple lines).
agent.py -f /path/to/file http://localhost:9080/
services/adapter

• To perform an HTTP POST to the URL specified with an XML payload using the
file specified, enter the following command with the –x option:
agent.py -x /path/to/file http://localhost:9080/
services/adapter

URL Agent Filtering 1
Sometimes it is beneficial or necessary to filter out changes coming out of an
endpoint application before they get to the workflow. By filtering early, it reduces
the load on the Adapter system. Also, some things like the request type can only
be determined at the endpoints. Often the endpoint can provide access to
previous values of data as well as the current. This allows status changes to be
detected and can allow a request type to be sent for the record.

The Adapter supports URL Agent filtering. The URL Agent filter identifies the
changes that need to be performed before reaching the endpoint application.
The filter is essentially a wrapper around the URL agent that provides the filtering
mechanism.

121 VERSION 2.4 REV A01 300-011-512

 URL Agent Filtering

Using a filter script allows you to define configuration settings like the URL to use,
basic auth parameters and logging options right within the script. This means that
the command line call to the script will be very simple. This also makes it easier to
run tests.

Running the Filter Script
An example URL Agent filter script (agent-filter.py) is installed with the
URL Agent. The agent-filter.py file can be copied and customized for your
solution. The script contains examples of options that can be changed. Modifying
the filter requires minimal coding and some knowledge of Python.

To run the script, enter the following command:

c:\install_root\adapters-2.2\agent\agent-filter.py

On Windows systems, you may need to use the command from an endpoint
application. For example:
c:\Python26\python c:\IonixITO\adapters-2.2\agent\agent-filter.py

Filter Parameters
All parameters for the URL Agent function (i.e.,. -v, -l, -s) can be used in the URL
Agent filter. Attributes are included in the script to perform the specific filtering.
The attributes available to the filter script are defined by the -a, -f or -e parameters
to the script.

The following parameters can be added to the Notification or Acquisition-Event

services to influence how this transaction is placed in the queue. Each of these can
be added using the -a parameter when calling the Agent. These must be set using
the string-field extended field type.

Example Filter Script
Figure 9-1 identifies the example URL Agent Filter.

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE
URL Agent Filtering

Figure 9-1 Example URL Agent Filter Script (page 1 of 3)

#!/usr/bin/env python
#
# Example Usage:
# agent-filter.py -a REMOVE_ME=abc -a Status=InProgress -a
OldStatus=Updated -a MUST_HAVE=true -a SEND=true -a Partner=abc -a ID=123

from multiprocessing import freeze_support

import agent

class FilteredAgent(agent.FilteredAgentMixin):
# Pre-configured URLs to send the requests to.
# This can be comma separated in the brackets urls = [
'http://localhost:9080/services/notification/remedy/%s/%s']

def init(self):
### Examples of setting URL Agent options (Overrides)

# Override Basic Authentication username and password.

# Uncomment these to enable
#self.options.username = 'user'
#self.options.password = 'pass'

# Override verbose logging

self.options.verbose = True

# Override local/background agent. True means local,

# False means background and uses store-forward
self.options.local = True

# If no code is in this method you need this line

#pass

def filter_attributes(self, attributes):

"""should_filter_out(self)

This method call is used to filter out calls to the agent. If this
method returns True, then the call will not be sent on. This useful
to filter out calls that do not need to be processed even though the
agent is fired.
"""

123 VERSION 2.4 REV A01 300-011-512

 URL Agent Filtering

Figure 9-2 Example URL Agent Filter Script (page 2 of 3)

### Examples of modifying attributes

# Example: Removing an attribute from being sent

if 'REMOVE_ME' in attributes:

del attributes['REMOVE_ME']
# Example: Setting override object type
attributes['iwave.overrides.objectType'] = 'CustomIncident'

# Example: Setting override service ID based on Partner field

(static)
if 'Partner' in attributes:
if attributes['Partner'] == 'ABC':
attributes['iwave.overrides.serviceId'] = 'RemedyABC'
# Example: Setting override service ID based on Partner field
#(dynamic) This will produce a serviceId of 'Remedy{P}' when the
#'Partner' field is '{P}'
else:
attributes['iwave.overrides.serviceId'] = 'Remedy%s' %
attributes['Partner']

# Example: Setting the request Type based on a status change

if attributes['Status'] != attributes['OldStatus']:
if attributes['Status'] == 'InProgress':
attributes['iwave.request.type'] = 'ChangeApproved'
elif attributes['Status'] == 'Cancelled':
attributes['iwave.request.type'] = 'ChangeRejected'
else:
attributes['iwave.request.type'] = 'Unknown'

# Example: Sets the create date based on the 'date' attribute

# specified using the format specified. Formatting options are
# available
# here: http://docs.python.org/library/time.html#time.strftime
self.create_date_from_attr('date', "%Y-%m-%d %H:%M:%S")

# Example: Sets the create date from the current time on this
# system. The time is always sent as UTC.
#self.create_date_from_now()

### Logging

# This piece of code will print out each attribute to the log file
self.agent.log_debug('Agent Filter Called with Attributes: %s' %
attributes)

# Logging can also be done to info using:

#self.agent.log_info('Some informational message')

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE
URL Agent Filtering

Figure 9-3 Example URL Agent Filter Script (page 3 of 3)

### Replacing URL placeholders

# This replaces any %s placeholders in the URLs with the values

# specified
self.replace_url_placeholders(('incident', attributes["ID"]))

### Examples of filtering out calls

### Returning True indicates not to send the call to the adapter
### Returning False indicates to send the call to the adapter

# Example: Filters out everything that does not have the

attribute "MUST_HAVE"
if 'MUST_HAVE' not in attributes:
self.agent.log_debug('MUST_HAVE attribute not present.
Filtering out')
return True

# Example: Filters out anything that does not have the "SEND"
attribute
# or it is not "true"
if 'SEND' not in attributes or attributes['SEND'] != 'true':
self.agent.log_debug('SEND attribute not present. Filtering
out')
return True

# Example: Filters out anything that does not have a change

between the
# two attributes 'Status' and 'OldStatus'.
if attributes['Status'] == attributes['OldStatus']:
self.agent.log_debug('Status not changed. Filtering out')
return True
return False

if __name__ == '__main__':
freeze_support()
FilteredAgent().run()

125 VERSION 2.4 REV A01 300-011-512

 Chapter 10
Managing the Adapter 10
In order to manage the EMC Adapters, the Java Console application may be
installed on your workstation. The Java Console graphical user interface is a
management tool that complies to the Java Management Extensions (JMX)
specification. Java Console uses the Java Virtual Machine (Java VM) to provide
information about the performance and resource consumption of the
Adapters installed in your network.

This application allows you to perform the following functions:

• list the names of the Adapters that are licensed and loaded
• provide the status of the endpoint applications
• restart all Adapters
• provide a status of items in the Acquisition Queue

Note: For information on monitoring Events that are generated on the EMC
Adapter and Ionix IT Orchestrator, refer to the “EMC Monitoring Server
Installation and Configuration Guide”.

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 126
PREREQUISITES

Figure 10-1 Jconsole – List Adapters

Prerequisites 10
In order to use the Java console to manage the Adapter services, the following
tasks must be completed:
• The Adapter software must be installed on your computer.
• The following Java Development Kit (JDK) package must be installed on your
computer:
Java JDK1.6.0

Connecting to the Adapter Java Process 10
There are two ways you can connect to the Adapter Java process:
• Connect to the local JMX instance. By default, JMX is not available for remote
connection. Java allows you to connect to a Java process running as the same
user using the jconsole.
• JMX can be enabled in the process itself for remote access. Remote access can
make use of SSL and authentication. setEnv – Enable JMX monitoring in

127 VERSION 2.4 REV A01 300-011-512

 STARTING THE JAVA CONSOLE

setEnv20 identifies the Java properties that can be set to enable JMX without
any security or authentication. These properties are included in the
setEnv.bat/.sh file, which is located in the
install_root\adapters-2.4\bin directory. The JMX monitoring
properties are disabled by default. To enable JMX monitoring, delete the rem
comment from the setEnv file. PORT can be replaced with any port name that
is desired.
— -Dcom.sun.management.jmxremote.port=PORT
-Dcom.sun.management.jmxremote.authenticate=false
-Dcom.sun.management.jmxremote.ssl=false
Figure 10-2 setEnv – Enable JMX monitoring in setEnv

Starting the Java Console 10
The Java Console is started by the jconsole executable. This executable can be
found in the JDK_HOME/bin directory, where JDK_HOME is the directory in
which the JDK software is installed. If this directory is in your system path, you
can start the Java Console by typing jconsole in a command (shell)
prompt. Otherwise, you have to type the full path to the executable file.

Management Beans  10
The following Adapter management beans can be used through JMX to manage
the Adapter:
• com.iwave:name=Adapters
• com.iwave:name=AcquisitionQueue
• com.iwave:name=FrameworkAdmin

com.iwave:name=Adapters
The Adapters Management bean allows the user to see which Adapters are
loaded and the status of the endpoint applications.

Methods
The following Methods are supported for the Adapter Management bean:
• listAdapterNames() - Gives a list of the names of the adapters that are
licensed and loaded.

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE
MANAGEMENT BEANS

• getEndpointStatus(endpointName) - Gives the status of an adapter.

The supplied parameter endpointName should be one of the values
returned from listAdapterNames(). Possible values for endpoint status
are:
— Unknown - Indicates that this adapter does not support the status
check. Currently the only adapters that support this operation are BMC
Remedy and CA-USD.
— Available - Indicates that the endpoint application is running and
responds to a simple command.
• NotAvailable - Indicates that the endpoint application cannot be reached
or fails to respond to a simple command.

com.iwave:name=AcquisitionQueue
The Acquisition Management bean allows the user to see the status of the
Acquisition Queue without directly querying the database.

Methods 
The following Methods are supported for the Acquisition Queue bean:
• countErrors(serviceId, objectType) - Gives a count of the items
on the queue in the Error state. This is the same as the acquisition service
countErrors() method.
• countPoll(serviceId, objectType) - Gives a count of the items on
the queue in the Poll state. This is the same as the acquisition service count()
method.
• countBlocked(serviceId, objectType) - Gives a count of the
items on the queue in the Blocked state.
• countTotal(serviceId, objectType) - Gives a count of all of the
items on the queue regardless of state.
• queueWaitingTime() - Gets the queue waiting time for the top item on
the persistence queue. The date of the first transaction is returned. This can
give an idea of when the last transaction was processed and if the queue
processor is stalled.
Each of the count methods take parameters of the serviceId and objectType.
These must be valid serviceId and objectType or part of a word. % is a valid
wildcard. If no objectType and serviceId are specified, the default will be to
query all.

Note: The Acquisition Management Service is also exposed as a web service.

The following is the WSDL for the Acquisition Management Service:

https://localhost:9443/services/AcquisitionManagementService?wsdl

129 VERSION 2.4 REV A01 300-011-512

 MANAGEMENT BEANS

com.iwave:name=FrameworkAdmin
The Framework Administration bean allows administration tasks to be
performed on the Adapters.

Methods
The following Methods are supported for the Adapter Management bean:
• restart(password) - Restarts the adapters. All services are shutdown,
configuration files reloaded and the services restarted. A parameter of the
admin password is required.
• framework.admin.password - This is the new setting in
framework.properties that contains the admin password hash. The default
value for this password is adminpw. If the JMX service will be enabled, this
password should be changed from the default.

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE
MANAGEMENT BEANS

131 VERSION 2.4 REV A01 300-011-512

 Chapter 11
Maintenance and Troubleshooting 11
This chapter covers the following topics pertaining to the maintenance and
troubleshooting of the EMC Adapter software.
• Logging
• Error Types and Meanings
• Re-Installing or Uninstalling the Windows Service
• Starting and Stopping the Adapter
• Uninstalling the Adapter Software - Windows

Logging 11
Logging is provided for both the Adapter Framework and the URL Agent.
Before logs can be generated, logging must be turned on and the amount of
details specified.

Log Location
Based on the operating system, the EMC Adapter stores logs in following
directories:
• For Windows: C:\install_root\adapters\log
• For UNIX: /opt/install_root/adapters/log

Turning on Adapter Logging (Windows)
To turn on Adapter Windows logging, you must edit the log4j.properties
file.
1. From Windows Explorer, navigate to the conf directory:
C:\install_root\Adapters\conf
2. Right-click log4j.properties file and click Open on the pop-up menu. If
this is the first time you have opened the properties file, Windows displays the
following dialog:

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 132
LOGGING

Figure 11-1 Windows Unknown File Type

3. Click Select the program from a list option and click OK.
4. From the Open With List, select Notepad. Select Always use the selected
program to open this kind of file and click OK to open Notepad.
5. In the log4jproperties file, find the Production Environment
Configuration section and the line:
log4j.rootLogger=INFO,File,ErrorAppender
6. Replace the word INFO with DEBUG.
7. Find the line: log4j.logger.com.iwave=INFO
8. Replace the word INFO with DEBUG. The log4j.properties file should look
like the file identified in Figure 11-2.
9. From the menu, select File > Save to save the changes.
10. From the menu, select File > Exit to close the file.

133 VERSION 2.4 REV A01 300-011-512

 LOGGING

Figure 11-2 log4j.properties File

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE
ERROR TYPES AND MEANINGS

URL Agent Logging
When specifying logging configurations for the URL Agent, use the -v
parameter with the agent.py command. This parameter specifies how much
detail will be included in the log. When operating in a normal production
environment, the log level will normally be set low to save processor time and
disk space.
• If the log level is too low, it may not provide enough information.
• If an issue is suspected with URL Agent connection to the notification service,
increase the log level.

Error Types and Meanings 11
The URL Agent and EMC Adapter generate their own errors. Several types of
errors can occur when several complex software applications interact. This
complexity is expanded when considering that the applications may be
communicating over vast distances (via the Internet) and that they are
typically asynchronous.

The following types of errors that may occur when using the EMC Adapter:
• Recoverable
• Permanent
• Global Errors

Recoverable Errors
Recoverable errors go away in time without involving any particular change to
the EMC configuration or the endpoint application. For instance, if the EMC
URL Agent attempts to send an event notification to the EMC Adapter and the
connection is down, the Agent continues sending the notification until the
connection is restored. In this case, there is an error message in the log, but no
action needs to be performed to return the Adapter to service. The Adapter is
returned to service automatically.

Permanent Errors
Permanent errors cannot be recovered automatically and require some form
or corrective interaction. For example, if the EMC user for the endpoint
application does not have a high enough privilege to open a new incident, the
attempt fails. No matter how many times the EMC user attempts to open a
new Incident, the action continues to fail until the user account is modified to
allow the action.

135 VERSION 2.4 REV A01 300-011-512

 ERROR TYPES AND MEANINGS

Global Errors
An error can thrown from either the Adapter, Ionix IT Orchestrator or
Integration workflow. Some of these errors are results of errant configurations
such as an incorrect workflow assumption, incorrect URL, or a bad SSL
configuration. Other errors could result from an error in the software itself.

Adapter Errors
The table below indicates errors that can occur in the EMC Adapter. These
errors can be generated by either the Acquisition or Operations Services.

Table 11-1 Adapter errors

Error Cause

AcquisitionException A problem occurred while trying to retrieve a transaction from

the adapter.

ObjectNotFoundException Occurs when the object requested on a get, update, or remove

operation is not found

UnsupportedOperationException The method used on the adapter is not supported by the

adapter.

OperationsException Typically a recoverable error such as connectivity issues

NonRecoverableOperationsExcept Permanent error condition.

ion

URL Agent/Notification Service Errors
The table below indicates errors that can appear in the URL Agent logs.

Table 11-2 URL Agent / Notification Service Errors

Error Cause

HTTP-503: Service Unavailable Most likely either the Form name or Incident ID are invalid on the
command line call to the URL Agent.

HTTP-50x: Internal Server Error An unexpected error occurred. Consult the log files.

HTTP-404: Not found An incorrect URL was entered or the host name is incorrect.

BMC Remedy Errors
If there is an interaction with Remedy from the Adapter and Remedy is having
trouble or does not like what was sent to it, Remedy returns an error that

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE
ERROR TYPES AND MEANINGS

attempts to provide enough information to debug the problem. Being able to

determine the difference between errors in the vendor application, such as
Remedy, and an EMC Ionix IT Orchestrator Adapter component sharply
reduces the time it takes to debug a problem.

Configuration Errors
The following table describes common errors associated with the configuration
of the adapter.

Table 11-3 Adapter Configuration Errors

Error Cause Solution

NativeLinkError The Remedy 7.1 API .DLL Make sure API .dll files in /install_root/
files are not present. Adapters/bin

ClassNotFoundExcept Required Remedy 7.1 API API .jar files should be located /
ion .jar files are not present install_root/Adapters/bin

NumberFormatExcepti Remedy port was not If using the remedy port mapper make sure
on supplied in the following parameter is set
framework.properties file. remedy71.port=0. If not using the port
mapper replace the 0 with the correct port
number.

Common Errors
The following table describes errors that are commonly reported from
Remedy. These errors provide information that could lead to changes in
workflow data, Remedy login information, Remedy user privileges, and
connectivity.

Table 11-4 Common Errors

Error Cause Solution

Login failed Remedy login credentials are Make sure that framework.properties
incorrect preventing the parameters remedy71.username and
adapter from connecting to remedy71.password have valid values
the Remedy API.

—sheet 1 of 3—

137 VERSION 2.4 REV A01 300-011-512

 ERROR TYPES AND MEANINGS

Table 11-4 Common Errors (continued)

Error Cause Solution

Cannot access An invalid Remedy form name Validate that the proper form name is
[formName: formId] was provided to one of the present in your Automator workflow logic
Adapter’s Operations when calling the operations methods.
methods.

The Remedy user account Change the Adapter user account to one
provided in the with greater privilege or upgrade the
framework.properties files permissions for the Adapter account in
does not have enough Remedy
privilege to access or perform
the requested operation on
the form.

The form has changed since Restart the adapter

the adapter has been started

Cannot get field: The field name supplied by Validate that the field name exists and that
[formName: fieldId] the Automator workflow to the there is no typo in the field name in the
adapter’s operations service appropriate workflow. If using the Incident
is incorrect. Object Model check the ITOM to make sure
the field is named correctly.

The field names are right but Validate that the workflow is paring up the
for a different form. right fields with the right form.

The EMC Ionix IT Change the Adapter user account to one

Orchestrator Adapter Remedy with greater privilege or upgrade the
account does not have permissions for the account in Remedy
enough privilege to perform
the requested operation on
this field.

The form has changed since Restart the adapter

the adapter has been started

Unable to update: An error occurred while Make sure the form name and Incident ID
entryID attempting to update the entry are correct and that Remedy’s user
[formName : entry] with entry identifier entryID. privilege can perform this action

Unable to create An error occurred while Make sure the form name is correct and
entryID attempting to create an entry that Remedy’s user privilege can perform
[formName : entry] in the Remedy system this action

—sheet 2 of 3—

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE
ERROR TYPES AND MEANINGS

Table 11-4 Common Errors (continued)

Error Cause Solution

Unable to delete An error occurred while Make sure the form name and Incident ID
entry: attempting to delete an entry are correct and that Remedy’s user
in the Remedy system privilege can perform this action
[formName:identifier]

Unable to get an Find query is incorrect Provide a valid query

entry using
qualification string:
[formName:
qualification]

—sheet 3 of 3—

139 VERSION 2.4 REV A01 300-011-512

 RE-INSTALLING OR UNINSTALLING THE WINDOWS SERVICE

Re­Installing or Uninstalling the Windows Service 11
If the Windows Service needs to be re-installed or un-installed, complete the
following steps:

Re­installing the Windows Service
To re-install the Windows Service:

1. Access the bin directory:

install_root/adapters-2.4/bin

2. Run the installation script.

service.bat install

Uninstalling the Windows Service
To uninstall the Windows Service:

1. Access the bin directory:

install_root/adapters-2.4/bin

2. Run the un-install script.

service.bat uninstall

Starting and Stopping the Adapter  11
If the Windows Service has been uninstalled and the Adapter needs to be
started, the startAdapters.bat file is included in the following directory:

install_root/adapters-2.4/bin/startAdapters.bat

This command starts the Adapter framework with a command window. To

stop the Adapter framework, close the command window.

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE
UNINSTALLING THE ADAPTER SOFTWARE - WINDOWS

Uninstalling the Adapter Software ­ Windows 11
To uninstall the EMC Adapter software, complete the following tasks:
1. From the Start menu, select the Uninstall Adapters option.
2. The Uninstall EMC Adapters Introduction screen displays. From this screen,
click Uninstall.
Figure 11-3 Uninstall Introduction

141 VERSION 2.4 REV A01 300-011-512

 UNINSTALLING THE ADAPTER SOFTWARE - WINDOWS

3. The Uninstaller begins to remove features associated with the installed

Adapter. It then uninstalls the EMC Adapter files, shortcut, LaunchAnywhere
features, folders, and registry.
Figure 11-4 Uninstall In Progress

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE
UNINSTALLING THE ADAPTER SOFTWARE - WINDOWS

4. The Uninstallation Complete screen displays. The files that were not installed
may be displayed on the screen. These files must be removed manually. Click
Done.
Figure 11-5 Uninstallation complete

143 VERSION 2.4 REV A01 300-011-512

 Chapter 12
IT Object Model (ITOM) 1
This chapter identifies the following IT Object Model (ITOM) mappings for BMC
Remedy:
• Incident Mapping
• Configuration Item (CI) Mapping
• Problem Mapping
• RFC Mapping
• Attachments

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 144
INCIDENT MAPPING

Incident Mapping 1
Table 12-1 identifies the Incident mappings for the BMC Remedy Adapter.

Table 12-1 Remedy Incident Management Request form V7.1 - Form HPD:Help Desk

Name Description Type Name (Label) Type Create Close Reopen Default

Base.Identifier The unique identifier for xs:string Incident Number Char(15) Required Required Not
an Incident Report (Incident ID) Supported
(Incident ID)

Base.Summary Summary of the Incident xs:string Summary Char(100) Required

(Summary)

Description Detailed description of xs:string Detailed Char(0) Option al

the Incident Description
(Notes)

Status The status of the xs:string Status Selection Required 5 0

incident 0=New,
1=Assigne
d, 2=In
Progress,
3=Pending
,
4=Resolve
d,
5=Closed,
6=Cancell
ed

—sheet 1 of 15—

145 VERSION 2.4 REV A01 300-011-512

 INCIDENT MAPPING

Table 12-1 Remedy Incident Management Request form V7.1 - Form HPD:Help Desk

Name Description Type Name (Label) Type Create Close Reopen Default

Impact Assessment of Impact xs:string Impact (Impact) Selection Required None

1000=Exte
nsive,
2000
Significant,
3000-
Moderate,
4000-
Minor

Severity The severity of the xs:string

incident

Urgency The urgency (severity) xs:string Urgency Selection Required None

of the incident (Urgency) 1000=1-
Critical,
2000=2-
High,
3000=3-
Medium,
4000=4-
Low

Priority Priority of Incident xs:string Priority (Priority) Selection Required None

0=Critical,
1=High,
2=Medium,
3=Low

Weight Weight assigned to the xs:integer Priority Weight Integer (0 - Optional

incident (Weight) 2147483647
)

—sheet 2 of 15—

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 146
INCIDENT MAPPING

Table 12-1 Remedy Incident Management Request form V7.1 - Form HPD:Help Desk

Name Description Type Name (Label) Type Create Close Reopen Default

Classification Incident Classification Classificati

Information on

Classification.Compan Incident Company xs:string Company Char(254) Required

y (Company)

Classification.ServiceT Incident Service Type xs:string Service Type Selection Required None
ype (Service Type) 0=User
Service
Restoration,
1=User
Service
Request,
2=Infrastruc
ture
Restoration,
3=Infrastruc
ture Event

—sheet 3 of 15—

147 VERSION 2.4 REV A01 300-011-512

 INCIDENT MAPPING

Table 12-1 Remedy Incident Management Request form V7.1 - Form HPD:Help Desk

Name Description Type Name (Label) Type Create Close Reopen Default

Classification.Reporte Reported Source xs:string Reported Source Selection optional

dSource (Reported Source) 1000=Direct
Input,
2000=E-
mail,
3000=Exter
nal
Escalation,
4000=Fax,
5000=Syste
ms
Managemen
t,
6000=Phone
,
7000=Voice
Mail,
8000=Walk
in,
9000=Web,
10000=Othe
r

Classification.Reporte Date Incident was Reported xs:datetim Reported Date Date/Time optional
dDate e (Reported Date)

Classification.Operati Operational Categorization Operationa

onal l

Classification.Operati Operation Categorization xs:string Categorizaation Tier Char(60) optional

onal.Tier1 for Tier 1 1 (Tier 1)

—sheet 4 of 15—

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 148
INCIDENT MAPPING

Table 12-1 Remedy Incident Management Request form V7.1 - Form HPD:Help Desk

Name Description Type Name (Label) Type Create Close Reopen Default

Classification.Operati Operation Categorization xs:string Categorization Tier 2 Char(60) optional

onal.Tier2 for Tier 2 (Tier 2)

Classification.Operati Operation Categorizaiton xs:string Categorization Tier 3 Char(60) optional

onal.Tier3 for Tier 3 (Tier 3)

Classification.Product Product Categorization Product

Classification.Product. The product classification xs:string Product Char(60) optional

Category1 category for Tier 1 Categorization Tier 1

Classification.Product. The product classification xs:string Product Char(60) optional

Category2 category for Tier 2 Categorization Tier 2

Classification.Product. The product classification xs:string Product Char(60) optional

Category3 category for Tier 3 Categorization Tier 3

Classification.Product. The name of the classified xs:string Product Name Char(254) optional
Name product (Product Name)

Classification.Product. The model and version of xs:string Product Model/ Char(254) optional
ModelVersion the classified product Version (Model/
Version)

Classification.Product. The Manufacturer of the xs:string Manufacturer Char(254) optional

Manufacturer classified product (Manufacturer)

Customer Customer Contact Contact

Information

Customer.Company Company xs:string Contact Company Char(254) Required

(Company)

—sheet 5 of 15—

149 VERSION 2.4 REV A01 300-011-512

 INCIDENT MAPPING

Table 12-1 Remedy Incident Management Request form V7.1 - Form HPD:Help Desk

Name Description Type Name (Label) Type Create Close Reopen Default

Customer.FirstName First Name xs:string First Name (First Char(30) Required

Name)

Customer.LastName Last Name xs:string Last Name (Last Char(30) Required

Name)

Customer.MiddleNam Middle Name xs:string Middle Name Char(30) Optional

e (Middle Name)

Customer.PhoneNum Phone Number xs:string Phone Number Char(50) Required

ber (Phone Number)

Customer.Organizatio Organization xs:string Organization Char(60) Optional

n (Organization)

Customer.Departmen Department xs:string Department Char(60) Optional

t (Department)

Customer.Site Site xs:string Site (Site+) Char(60) Optional

Customer.EmailAddre Email Address xs:string

ss

Direct Direct Contact Information Contact

Direct.Company Company xs:string Direct Contact Char(254) Optional

Company
(Company)

Direct.FirstName First Name xs:string Direct Contact First Char(30) Optional

Name (First Name)

—sheet 6 of 15—

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 150
INCIDENT MAPPING

Table 12-1 Remedy Incident Management Request form V7.1 - Form HPD:Help Desk

Name Description Type Name (Label) Type Create Close Reopen Default

Direct.LastName Last Name xs:string Direct Contact Last Char(30) Optional

Name (Last Name)

Direct.MiddleName Middle Name xs:string Direct Contact Char(30) Optional

Middle Initial

Direct.PhoneNumber Phone Number xs:string Direct Contact Char(50) Optional

Phone Number
(Phone Number)

Direct.Organization Organization xs:string Direct Contact Char(60) Optional

Orgainization
(Organization)

Direct.Department Department xs:string Direct Contact Char(60) Optional

Department
(Department)

Direct.Site Site xs:string Direct Contact Site Char(60) Optional

(Site+)

Direct.EmailAddress Email Address xs:string Direct Contact Char(255) Optional

Internet E-mail
(Internet E-Mail)

Assignee Incident Assignee Assignmen

Information t

Assignee.Company Assignee Support Company xs:string Assigned Support Char(255) required

Company (Support
Company)

—sheet 7 of 15—

151 VERSION 2.4 REV A01 300-011-512

 INCIDENT MAPPING

Table 12-1 Remedy Incident Management Request form V7.1 - Form HPD:Help Desk

Name Description Type Name (Label) Type Create Close Reopen Default

Assignee.Organizatio Assignee Support xs:string Assigned Support Char(60) required

n Organization Organization
(Support
Organization)

Assignee.PrimaryGrou Assigned Group xs:string Assigned Group Char(60) required

p (Assigned Group)

Assignee.SecondaryG Assigned Secondary Group xs:string

roup

Assignee.Assignee Assignee to the incident xs:string Assignee (Assignee) Char(69) optional required

Owner Incident Owner Information Assignmen

t

Owner.Company Owner Support Company xs:string Owner Support Char(254) optional

Company (Owner
Support Company)

Owner.Organization Owner Support xs:string Owner Support Char(60) optional

Organization Organization (Owner
Support
Organization)

Owner.Group Owner Group xs:string Owner Group Char(60) optional

(Owner Group)

Owner.Owner Owner xs:string Owner (Owner) Char(69) optional

Vendor Vendor Information

—sheet 8 of 15—

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 152
INCIDENT MAPPING

Table 12-1 Remedy Incident Management Request form V7.1 - Form HPD:Help Desk

Name Description Type Name (Label) Type Create Close Reopen Default

Vendor.AssignmentSt The status of the vendor xs:string Vendor Assignment Selection optional
atus assignment of the incident Status (Vendor 0=Assigned,
Assignment Status) 1=In-
Progress,
2=Complete
d

Vendor.Identifier The unique identifer of the xs:string Vendor Ticket Char(50) optional
incident id of the vendor Number (Vendor
system reported to Ticket Number)

Vendor.ReportedToVe The date the incident was xs:datetim Reported to Vendor Date/Time optional
ndorDate reported to Vendor e (Reported to Vendor
Date)

Vendor.RespondedTo The date the vendor last xs:datatim Vendor Responded Date/Time optional
VendorDate responded to the Incident e On (Vendor
Responed Date)

Vendor.ResolvedDate The date the vendor xs:datetim Vendor Resolved Date/Time optional
resolved the incident e Date (Vendor
Resolved Date)

Vendor.Contact Vendor Contact Information Contact

Vendor.Contact.Comp Company xs:string Vendor Company Char(254) optional

any (Vendor Company)

Vendor.Contact.FirstN First Name xs:string Vendor First Name Char(30)

ame (Vendor First Name)

—sheet 9 of 15—

153 VERSION 2.4 REV A01 300-011-512

 INCIDENT MAPPING

Table 12-1 Remedy Incident Management Request form V7.1 - Form HPD:Help Desk

Name Description Type Name (Label) Type Create Close Reopen Default

Vendor.Contact.LastN Last Name xs:string Vendor First Name

ame

Vendor.Contact.Middl Middle Name xs:string

eName

Vendor.Contact.Phon Phone Number xs:string

eNumber

Vendor.Contact.Orga Organization xs:string Vendor Organization Char(254) optional

nization (Vendor
Organization)

Vendor.Contact.Depa Department xs:string Vendor Group Char(60) optional

rment (Vendor Group)

Vendor.Contact.Site Site xs:string

Vendor.Contact.Email Email Address xs:string Vendor Email

Resolution Resolution Information Resolution

Resolution.Detail Resolution Detail xs:string Resolution Char(0) optional

Information (Resolution Details)

Resolution.Method The method of resolution xs:string Resolution Method Char(30) optional

(Resolution Method)

Resolution.Cause The determined cause of xs:string Generic Char(60) optional

the incident Categorization Tier 1
(Cause)

—sheet 10 of 15—

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 154
INCIDENT MAPPING

Table 12-1 Remedy Incident Management Request form V7.1 - Form HPD:Help Desk

Name Description Type Name (Label) Type Create Close Reopen Default

Resolution.ClosureSo The source of who closed xs:string Closure_Source(Clos selection optional

urce the incident ure Source) 1000=Custo
mer,
2000=Syste
m,
3000=Suppo
rt Agent

Resolution.Tier1 The resolution category for xs:string Resolution Category Char(60) optional required
Tier 1 (Tier 1)

Resolution.Tier2 The resolution category for xs:string Resolution Category Char(60) optional
Tier 2 Tier 2 (Tier 2)

Resolution.Tier3 The resolution category for xs:string Resolution Category Char(60) optional
Tier 3 Tier 3 (Tier 3)

Resolution.Satifaction The resolution satifaction xs:string Satisfaction Rating Char(30) optional

Rating rating (Satisfaction Rating)

Resolution.RequiredD The date the resolution is xs:datetim Required Resolution Date/Time optional
ate required e DateTime(Required
Resolution Date)

Resolution.ForecastR The forecasted Resolution xs:datetim Estimated Date/Time optional

esolutionDate Date e Resolution Date
(Estimated
Resolution Date)

Resolution.Resolution The actual date and time of xs:datetim

Date the resoluton e

—sheet 11 of 15—

155 VERSION 2.4 REV A01 300-011-512

 INCIDENT MAPPING

Table 12-1 Remedy Incident Management Request form V7.1 - Form HPD:Help Desk

Name Description Type Name (Label) Type Create Close Reopen Default

Resolution.Product The resoluton product Product

categorization

Resolution.Product.Ca The product closure xs:string Closure Product Char(60) optional

tegory resolution category for Tier Category Tier1 (Tier
1 1)

Resolution.Product.Ca The product closure xs:string Closure Product Char(60) optional

tegory2 resolution category for Tier Category Tier2 (Tier
2 2)

Resolution.Product.Ca The product closure xs:string Closure Product Char(60) optional

tegory3 resolution category for Tier Category Tier3 (Tier
3 3)

Resolution.Product.N The name of the closure xs:string Closure Product Char(254) optional
ame product Name (Product
Name (R))

Resolution.Product.M The model and version of xs:string Closure Product Char(254) optional
odelVersion the closure product model/Version
(Model/Version (R))

Resolution.Product.M The Manufacturer of the xs:string Closure Char(254) optional

anufacturer closure product Manufacturer
(Manufacturer (R))

Log Logging Activity Log Form: HPD_WorkLog

Log.Identifier unique identifier for the log xs:string Entry ID Char(15)

item

—sheet 12 of 15—

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 156
INCIDENT MAPPING

Table 12-1 Remedy Incident Management Request form V7.1 - Form HPD:Help Desk

Name Description Type Name (Label) Type Create Close Reopen Default

Log.Type Type of Log activity xs:string Work Log Type required

Log.Summary Log Summary xs:string Description Char(100) required

(Summary)

Log.Source Log Source xs:string Communication Selection optional

Source (Source) 1000=Email,
2000=fax,
3000=Phone
,
4000=Voice
Mail,
5000=Walki
n,
6000=Pager
,
7000=Syste
m
Assignment,
8000=web,
9000=other

Log.Description Log Description xs:string Detailed Description Char(0) optional

(Notes)

Log.Submitter User who submtted the log xs:string Work Log Submitter Char(254) required
entry (Submitter)

Log.SubmitDate The date and time the log xs:datetim Work Log Submit Data/Time required
entry was submitted e Date (Submit Date)

—sheet 13 of 15—

157 VERSION 2.4 REV A01 300-011-512

 INCIDENT MAPPING

Table 12-1 Remedy Incident Management Request form V7.1 - Form HPD:Help Desk

Name Description Type Name (Label) Type Create Close Reopen Default

Incident Number Char(15) Required Required

(Incident ID)

CI Configuration Item or Items CIRef

related to Incident

CI.Identifier CI Identifier xs:string

CI.Name CI Name xs:string

CI.Type CI Type xs:string

CI.Description CI Description xs:string

CI.Status CI Status xs:string

CI.ExtendedFields Supports all extended all

attributes. Allows vendor extended
specific apps to add
additional data to the
specific CI

logs Logging Activity ObjectRefe

rence(0..n)

log.Identifier CI Identifier xs:string

log.Name CI Name xs:string

log.Type CI Type xs:string

—sheet 14 of 15—

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 158
INCIDENT MAPPING

Table 12-1 Remedy Incident Management Request form V7.1 - Form HPD:Help Desk

Name Description Type Name (Label) Type Create Close Reopen Default

relationships Object related to this object ObjectRefe From form

rence(0..n) HPD:Associations

relationship.Identifier Identiifer of the object xs:string Request ID01

relationship.Name Name of the object xs:string Request

Description01

relationship.Type Object type xs:string Request Type01

relationship.Role Role of the relationship xs:string Association Type01

—sheet 15 of 15—

159 VERSION 2.4 REV A01 300-011-512

 CONFIGURATION ITEM (CI) MAPPING

Configuration Item (CI) Mapping 12
Table 12-2 identifies the Configuration Item mappings for the BMC Remedy Adapter.

Table 12-2 ITOM Configuration Item Mapping for BMC Remedy

Field Name Description Type Name (Label) Type Default Notes

Identifier Identifier of this xs:string ClassId;InstanceId For Remedy the

configuration item in identifier is a
the application. This complex key
may be a complex consisting of the
key if the class is InstanceId,
required to look up ClassName and
the CI ClassNamespace

Summary Short description of xs:string ShortDescription

the object

Name Name of this item xs:string Name

ClassName Name of the class xs:string ClassName

this CI belongs to

ClassNamespace Namespace of the xs:string ClassNamespace BMC.CORE

classname (optional)

DatasetId Dataset Identifier xs:string DatasetId

Status Status xs:string

CreateDate Date the CI was xs:datetime CreateDate

reported or created

LastModified Date the CI was xs:datetime ModifiedDate

updated

—sheet 1 of 4—

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 160
CONFIGURATION ITEM (CI) MAPPING

Table 12-2 ITOM Configuration Item Mapping for BMC Remedy (continued)

Field Name Description Type Name (Label) Type Default Notes

LastModifiedBy The person who last xs:string LastModifiedBy

updated the CI

Submitter The person to xs:string Submitter

created the CI

Description Description xs:string Description

SerialNumber Serial Number of the xs:string SerialNumber

CI

Category Category of the item xs:string Category

Type Type of the item xs:string Type

Item The item type xs:string Item

Model Model of this item xs:string Model

Manufacturer Manufacturer of this xs:string ManufacturerName

item

Version Version of this item xs:string VersionNumber

Assignee User who this item is xs:string AssignedTo

assigned to

HostName The hostname of this xs:string HostName

CI if applicable

compliance Compliance Compliance (1)

Information of this CI
(Optional)

—sheet 2 of 4—

161 VERSION 2.4 REV A01 300-011-512

 CONFIGURATION ITEM (CI) MAPPING

Table 12-2 ITOM Configuration Item Mapping for BMC Remedy (continued)

Field Name Description Type Name (Label) Type Default Notes

Status Status of the xs:string

compliance of this
device

PolicyIdentifier Identifier of the policy xs:string

that is in compliance
or not

PolicyName Name of the policy xs:string

that is in compliance
or not

relationships Related CIRelationship Of relationship class

Configuration Items (0..n)

Identifier Identifier of the xs:string ClassId;InstanceId

relationship
(optional)

Name Name of the xs:string

relationship

ClassName Class name of this xs:string ClassName required for create

relationship (or type)

ClassNamespace Optional namespace xs:string ClassNamespace required for create

for this relationship

SourceRole Parent's role in the xs:string Roles field

relationship (ie.
Source)

—sheet 3 of 4—

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 162
CONFIGURATION ITEM (CI) MAPPING

Table 12-2 ITOM Configuration Item Mapping for BMC Remedy (continued)

Field Name Description Type Name (Label) Type Default Notes

relationship.targets Configuration Items ObjectReference

associated with this (0..n)
relationship

target.Identifier CI Identifier xs:string ClassId;InstanceId

target.Name CI Name xs:string

target.Type CI Type xs:string

target.role Role of the target target role field

relationship

—sheet 4 of 4—

163 VERSION 2.4 REV A01 300-011-512

 PROBLEM MAPPING

Problem Mapping 12
Table 12-3 identifies the Problem mapping for the BMC Remedy Adapter. These are used for the following forms:
• PBM:ProblemInterface_Create
• PBM:ProblemInterface
• PBM:Problem Investigation

Table 12-3 ITOM Problem Mapping for BMC Remedy

Field Name Description Type Field Name Optional/ Notes

(Create) Required

Identifier Identifier of this configuration item xs:string Problem Required

in the application Investigation ID

Summary Short description of the object xs:string Description Required

(Problem Resolution)

Description Detailed description of the Problem xs:string Detailed Optional *Note that this field name
Decription* is spelled wrong. This is
how it is defined in
Remedy.

Status The status xs:string Investigation Optional

Status

Impact Assessment of Impact xs:string Impact Optional

Severity The severity xs:string Severity Optional

Urgency The urgency xs:string Urgency Optional

Priority Priority xs:string Priority Optional

Weight Weight assigned xs:string Priority Weight Optional

—sheet 1 of 5—

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 164
PROBLEM MAPPING

Table 12-3 ITOM Problem Mapping for BMC Remedy (continued)

Field Name Description Type Field Name Optional/ Notes

(Create) Required

ExternalProblemId Third Party Ticket Reference xs:string Vendor Ticket

entifier Number

CreateDate Date the problem was reported or xs:datetime First Reported On

created

LastModified Date the problem was updated xs:datetime Last Modified Date

LastModifiedBy The person who last updated the xs:string Last Modified By
problem

Company The company of the problem xs:string Company

location

InvestigationDriver xs:string Investigation Driver

TargetResolution xs:datetime Target Resolution

Date

Workaround xs:string Temporary

Workaround

RootCause xs:string Generic

Categorization Tier
1

Requester Requester Contact Information Contact

Requester.Compan Company xs:string Contact Company

y

Requester.FirstNa First Name xs:string First Name

me

—sheet 2 of 5—

165 VERSION 2.4 REV A01 300-011-512

 PROBLEM MAPPING

Table 12-3 ITOM Problem Mapping for BMC Remedy (continued)

Field Name Description Type Field Name Optional/ Notes

(Create) Required

Requester.LastNa Last Name xs:string Last Name

me

Requester.MiddleN Middle Name xs:string Middle Initial

ame

Requester.PhoneN Phone Number xs:string Phone Number

umber Business

Requester.Organiz Organization xs:string Support

ation Organization
Requestor

Requester.Depart Department xs:string Support Group

ment Name Requester

Requester.Site Site xs:string

Requester.EmailAd Email Address xs:string

dress

Categorization Operational Categorization Categorization

Categorization.Tier Operation Categorization for Tier 1 xs:string Categorization Tier

1 1

Categorization.Tier Operation Categorization for Tier 2 xs:string Categorization Tier

2 2

Categorization.Tier Operation Categorizaiton for Tier 3 xs:string Categorization Tier

3 3

Product Product Categorization Product

—sheet 3 of 5—

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 166
PROBLEM MAPPING

Table 12-3 ITOM Problem Mapping for BMC Remedy (continued)

Field Name Description Type Field Name Optional/ Notes

(Create) Required

Product.Category1 The product classification category xs:string Product

for Tier 1 Categorization Tier
1

Product.Category2 The product classification category xs:string Product

for Tier 2 Categorization Tier
2

Product.Category3 The product classification category xs:string Product

for Tier 3 Categorization Tier
3

Product.Name The name of the classified product xs:string Product Name

Product.ModelVers The model and version of the xs:string Product Model/

ion classified product Version

Product.Manufactu The Manufacturer of the classified xs:string Manufacturer

rer product

logs Logging Activity ObjectReference

(0..n)

log.Identifier CI Identifier xs:string AR_CORE_ID

log.Name CI Name xs:string

log.Type CI Type xs:string

relationships Object related to this object ObjectReference From form PBM:Associations

(0..n)

—sheet 4 of 5—

167 VERSION 2.4 REV A01 300-011-512

 PROBLEM MAPPING

Table 12-3 ITOM Problem Mapping for BMC Remedy (continued)

Field Name Description Type Field Name Optional/ Notes

(Create) Required

relationship.Identifi Identiifer of the object xs:string Request ID01

er

relationship.Name Name of the object xs:string Request

Description01

relationship.Type Object type xs:string Request Type01

relationship.Role Role of the relationship xs:string Association

Type01

Log Logging Activity From form: PBM:Investigation WorkLog

Log.Identifier unique identifier for the log item xs:string Char(15)

Log.Type Type of Log activity xs:string Required

Log.Summary Log Summary xs:string Char(100) Required

Log.Source Log Source xs:string

Log.Description Log Description xs:string Char(0) optional

Log.Submitter User who submtted the log entry xs:string Char(254) required

Log.SubmitDate The date and time the log entry was xs:datetime Data/Time required
submitted

Log.Identifier unique identifier for the log item xs:string Char(15)

Log.Type Type of Log activity xs:string required

—sheet 5 of 5—

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 168
RFC MAPPING

RFC Mapping 12
Table 12-4 identifies the Request for Change (RFC) mappings for the BMC Remedy Adapter. These are used in the
following forms:
• CHG:ChangeInterface
• CHG:Infrastructure Change

Table 12-4 ITOM RFC Mapping for BMC Remedy

Field Name Description Type Field Name Type Optional/ Default Notes
Required

Identifier Identifier of this xs:string Infrastructure

configuration item in the Change ID
application

Summary Short description of the xs:string Description

object (Change
Resolution)

Description Description of this object xs:string Detailed

Description

Status Status xs:string Change

Request
Status

Type Type of the Change xs:string Change Type

Impact Assessment of Impact xs:string Impact

RiskLevel The Risk Level of the xs:string Risk Level

change

Urgency The urgency xs:string Urgency

—sheet 1 of 6—

169 VERSION 2.4 REV A01 300-011-512

 RFC MAPPING

Table 12-4 ITOM RFC Mapping for BMC Remedy (continued)

Field Name Description Type Field Name Type Optional/ Default Notes
Required

Priority Priority of Incident xs:string Priority

CreateDate xs:datetime Submit Date

LastModified Date the problem was xs:datetime Last Modified

updated Date

LastModifiedBy The person who last xs:string Last Modified

updated the problem By

ScheduledStart xs:datetime Scheduled

Start Date

ScheduledEnd xs:datetime Scheduled

End Date

ActualStart xs:datetime Actual Start

Date

ActualEnd xs:datetime Actual End

Date

Company The company of the xs:string Location

change location Company

Timing The Change Timing xs:string Change

Timing

Reason The Reason for Change xs:string Reason For

Change

BusinessJustification The Business xs:string Business

Justification Justification

—sheet 2 of 6—

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 170
RFC MAPPING

Table 12-4 ITOM RFC Mapping for BMC Remedy (continued)

Field Name Description Type Field Name Type Optional/ Default Notes
Required

Requester Requester Contact Contact

Information

Requester.Company Company xs:string Company

Requester.FirstName First Name xs:string First Name

Requester.LastName Last Name xs:string Middle Initial

Requester.MiddleNam Middle Name xs:string Last Name

e

Requester.PhoneNum Phone Number xs:string Phone

ber Number

Requester.Organizatio Organization xs:string Organization

n

Requester.Department Department xs:string Department

Requester.Site Site xs:string

Requester.EmailAddre Email Address xs:string

ss

Categorization Operational Categorization

Categorization

Categorization.Tier1 Operation Categorization xs:string Categorizaatio

for Tier 1 n Tier 1

Categorization.Tier2 Operation Categorization xs:string Categorization

for Tier 2 Tier 2

—sheet 3 of 6—

171 VERSION 2.4 REV A01 300-011-512

 RFC MAPPING

Table 12-4 ITOM RFC Mapping for BMC Remedy (continued)

Field Name Description Type Field Name Type Optional/ Default Notes
Required

Categorization.Tier3 Operation Categorizaiton xs:string Categorization

for Tier 3 Tier 3

Product Product Categorization Product

Product.Category1 The product classification xs:string Product

category for Tier 1 Categorization
Tier 1

Product.Category2 The product classification xs:string Product

category for Tier 2 Categorization
Tier 2

Product.Category3 The product classification xs:string Product

category for Tier 3 Categorization
Tier 3

Product.Name The name of the xs:string Product Name

classified product

Product.ModelVersion The model and version of xs:string Product

the classified product Model/Version

Product.Manufacturer The Manufacturer of the xs:string Manufacturer

classified product

logs Logging Activity ObjectReferen

ce(0..n)

log.Identifier Log Identifier xs:string AR_CORE_ID

log.Name Log Name xs:string

—sheet 4 of 6—

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 172
RFC MAPPING

Table 12-4 ITOM RFC Mapping for BMC Remedy (continued)

Field Name Description Type Field Name Type Optional/ Default Notes
Required

log.Type Log Type xs:string

relationships Object related to this ObjectReferen From form

object ce(0..n) CHG:Associati
ons

relationship.Identifier Identiifer of the object xs:string Request ID01

relationship.Name Name of the object xs:string Request

Description01

relationship.Type Object type xs:string Request

Type01

relationship.Role Role of the relationship xs:string Association

Type01

Log object retrieved through getLogs()

Log Logging Activity Log Form:

CHG:WorkLog

Log.Identifier unique identifier for the xs:string Char(15)

log item Entry ID

Log.Type Type of Log activity xs:string Work Log Required

Type

Log.Summary Log Summary xs:string Description Char(100) Required

(Summary)

Log.Source Log Source xs:string

—sheet 5 of 6—

173 VERSION 2.4 REV A01 300-011-512

 RFC MAPPING

Table 12-4 ITOM RFC Mapping for BMC Remedy (continued)

Field Name Description Type Field Name Type Optional/ Default Notes
Required

Log.Description Log Description xs:string Detailed Char(0) Op tional

Description
(Notes)

Log.Submitter User who submtted the xs:string Work Log Char(254) Required
log entry Submitter
(Submitter)

Log.SubmitDate The date and time the log xs:datetime Work Log Data/Time Required
entry was submitted Submit Date
(Submit Date)

—sheet 6 of 6—

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 174
ATTACHMENTS

Attachments 12
Table 12-5 identifies the Attachment mappings for the BMC Remedy Adapter.

Table 12-5 Attachment Support for BMC Remedy

Remedy Incident Management

Request Form V7.1

Name Description Type Name Notes

(Label)

identifier identifier xs:string Identifier of the attachment

name name of the attachment xs:string name Filename of the attachment

description summary or description xs:string log.summary Summary of the worklog

of the attachment

175 VERSION 2.4 REV A01 300-011-512

 ATTACHMENTS

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 176
ATTACHMENTS

177 VERSION 2.4 REV A01 300-011-512

Index 1
A databases
enabling support for another database 85
acquisition
external
monitoring 86
user for multiple adapters 101
WSDL URL location 30
supported 41
acquisition service 20
datasource properties 85
polling methods 30
discovery service 33
process flow 20
scaling 100
adapter E
failover infrastructure 101 error messages
management 126 configuration 137
Adapter Framework 14 for BMC Remedy 136
running as a Windows service 78 notification service 136
starting 140 types 135
stopping 140 URL Agent 136
Adapter user account error types
creating for Remedy 92 permanent 135
agent recoverable 135
scaling 101 errors 136
alerts Adapter 136
automated 86 event notification service URLs
Apache Derby 41 for calling the URL Agent 94

B F
base URLs 85 filter
blocking methods 31 creating for the URL Agent 92
framework HTTP authentication 85
C framework properties 83
for the global framework 84
change service 38
client acquisition service
running on another port 98 G
configuration service 37 global framework properties 84
core methods 34
H
D high availability 100
database
monitoring 85

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE
I configuration service 37
incident 35
incident service 35
ITObject service 36
Information Technology Service Management 15
problem service 37
install folder 62
process flow 26
install set 48, 61
scaling 100
installer
Linux 80
starting 46 P
Unix 80 password
ITIL services 15 iMS 67
supported object types 16 web service authentication 66
ITObject service 36 permanent errors 135
ITSM 15 persistence database 104
applications 12 changing the port number 105
connecting to 105
J removing transactions 104
polling methods 30
Java console
problem service 37
starting 128
properties editor 83
Java Management Extensions 126
command 84
Java to Adapter integration 102
starting 83
JMX 126
Python
management beans 128
required for the URL Agent 118

L R
license file 64
recoverable errors 135
directory location 45
relationship methods 34
installing 45
RESTful Client Acquisition 97
log
location
for UNIX  132 S
for Windows  132 security 65
methods 34, 35 shared service operations 34
log4j.properties file 132 shortcut folder 63
logging 132 SOAP client acquisition service 98
turning on software
for Windows  132 uninstall
URL Agent daemon 119 Windows  141
software installation 42
N for Windows 46
manual 81
notification agent 19 UNIX  81
notification service 24
Windows  81
error messages 136
system configuration 40
system requirements 40
O
operating systems
supported 40
T
terminal methods 31
operations service 26
troubleshooting 132
change service 38
error types and meanings 135

179 VERSION 2.4 REV A01 300-011-512

U
URL
iMS 67
URL Agent 118
command options 120
daemon 119
logging  119
shutting down 119
starting  119
error messages 136
logging 135
notifying from Remedy 92
running 120
using 118
user account
creating for the Adapter 92
username
iMS 67
web service authentication 66

W
web service authentication 66
Windows service
exectuable location 78
manager application 78
manual install or uninstall 140
re-installing 140
running 78
uninstalling 140

EMC IONIX IT ORCHESTRATOR ADAPTER BMC REMEDY AND ATRIUM INSTALLATION AND CONFIGURATION GUIDE 180
181 VERSION 2.4 REV A01 300-011-512
B
B

EMC Corporation
Corporate Headquarters,
Hopkinton, MA 01748-9103
U.S.A.

Tel.:1-508-435-1000

http://www.EMC.com

EMC Ionix IT Orchestrator Adapter

BMC Remedy and Atrium
Installation and Configuration Guide

Document number: 300-011-512

Product release: 2.4
Document version: A01
Date: September 2010

Printed in the United States of America.

Copyright © 2010, EMC Corporation
All Rights Reserved