pi WS _ 3 . x - Preliminarumentation _ 2 x - Dashboard

spinabundantInternet και Εφαρμογές Web

30 Ιουλ 2012 (πριν από 5 χρόνια και 2 μήνες)

208 εμφανίσεις

BES 3.5 piWS
v3.X
SOAP/XML and RESTful Web Services Integration


Interlink Software Services Integration for Web Services (hereinafter referred to as piWS) enables communi
cation by way of HTTP between an

application and the Business
Enterprise Server that is not platform dependent. Any application that can communicate by way of HTTP can create, assign, clo
se, and add notes to an alert in the Business
Enterprise Server environment via SOAP/XML or RESTful c
alls.


This component is
also
used in conjunction with
other integrations to provide a return path for updates to BES alerts.


Overview:




Pre
-
requisites :



BES >=3.5.0



METRO and Jersey libraries (<=BES 3.5.2)



BES Apache/Tomcat user with the ‘manager’ role
defined

Installation (pre
-
requisites):


Event
Daemon

Business Enterprise Server (BES) 3.5

Business
Service
Dashboard

Alert
Server

Integration
Work
F
iles



piWS

Key

BES
Apache/Tomcat



Web Application


Third Party
Application


Log File

File Listener
Message
Channel

METRO and Jersey:


If BES version is <= 3.5.2

then METRO and Jersey libraries need to be added to the system. To do this,

change to $PPHOME as ppadmin and extract both
supplied
tarballs from there.

They will
populate the

following location with jars: $PPHOME/eScape/tomcat/shared/lib


BES Apache/Tomcat User ‘manager’ role

The integration uses a web application monitor binary which requires access to the BES tomcat. To permit this a user must be
defined in tomca
t
-
users.xml with the
‘manager’ role.

1.

Edit $PPHOME/eScape/tomcat/conf/tomcat
-
users.xml

2.

Ensure at least one user has the manager role defined within the <tomcat
-
users> root XML tag, e.g.

<user username="tomcat" password="t0mcat1" roles="tomcat,manager"/>

3.

Restart the BES web client

Installation:


To install piWS change to $PPHOME as ppadmin and extract the tarball from there, then:


1.

Change to the install directory and run install:

cd Integrations/piWS

./install

2.

There is a post install step which involves editing the tomcat
-
users.xml to set authentication credentials
for external access
to the web service.

Instructions regarding how to do this are displayed at the end of the install script
….


INFO: The following
manual configuration tasks must be followed:
-

INFO: 1. Ensure tomcat
-
users.xml has user/pass added for role=IntegrationUsers

INFO: /opt/ISS/POWERpack/eScape/tomcat/conf/tomcat
-
users.xml

INFO:


<?xml version='1.0' encoding='utf
-
8'?>



<tomcat
-
users>


<user username="BES1" password="ilinkuk1" roles="IntegrationUsers"/>


</tomcat
-
users>

INFO:

INFO: 3. Setup BES Apache to support SSL

if required

-

see documentation for more information

INFO: 4. Restart webclient, su to root from ppadmin:


/opt/ISS/POWERpack/bin/ppwcStop


/opt/ISS/POWERpack/bin/ppwcStart

INFO: 5. Start piWS daemon, as ppadmin: ppStart
-
n piWS


Upgrading:

To upgrade a piWS, follow
the installation pro
cedure


only step 1 required. The existing integration binaries are not backed up but the existing configuration will be
retained
($PPHOME/cfg/piWS.cfg)
.



Files:

piWS log:

$PPLOG/piWS.log

Tomcat web app initialisation log:

$PPHOME/eSc
ape/tomcat/logs/catalina*

Commented configuration file:

$PPHOME/cfg/piWS.cfg

piWS web application:
$PPHOME/eScape/webapps/piWS.war

piWS web application monitor:

$PPHOME/Integrations/bin/piWS


Troubleshooting:


-

piWS daemon is not running:

o

try start with:
ppStart

n piWS

o

check ppState output

o

Check log: $PPLOG/piWS.log

o

Check message channel monitor log: $PPLOG/ppmd/mon_piWS.log


-

piWS
doesn’t receive event updates:

o

Try access the piWS test page from a host on the
current
and then remote

(if applicable) network
:

http://BEShost/piWS/

where BEShost is the hostname/IP
of the BES. You should be prompted with a HTTP authentication page.


-

HTTP 401, 403 error codes received by connecting web service client:

o

C
heck that tomcat
-
users.xml has includes a valid user with the “IntegrationUsers” role set and that the web service client is authenticating us
ing HTTP
authentication.




Integrating using SOAP/XML web service calls:

See the WSDL for the SOAP/XML web
service definition:

http://
BEShost
/piWS/piWS?WSDL

where BEShost is the hostname or IP of your BES.

This file can be used to generate a SOAP/XML web service client using an environment or toolkit such as:

-

Mic
rosoft Visual Studio .NET

-

Microsoft SOAP Toolkit

-

Java 2 Enterprise Edition

-

Sun Microsystem Java Web Services Development Pack

-

IBM Websphere

-

Apache Axis


All SOAP/XML calls return a string back to the client. The first field of each string is a re
turn code which is prefixed by a hyphen, e.g
-
200

The return codes are comparable to HTTP return codes with the main ones being 200 (OK), 500 (Error), 503 (Service unavailable
, i.e. piWS still initialising).


The table below lists the methods/descriptions

which have been implemented:

Method Signature

Description

String createAlert(String message)

Creates a new alert and takes “message” in pipe separated field = value names, e.g:


楮瑥g牡瑩rn䥤 㴠som敕湩qu敖慬ㄲ3⁼ 獥s敲楴y=1⁼ m据慭e㵰=坓

|⁤om慩a㵈=sW1⁼⁣畳 om噡V=123⁼
瑥硴㵈=s琠楳⁤o睮⁼


坨敮⁡渠慬敲琠楳i捲敡c敤⁡e獴物sg⁩猠牥瑵牮敤⁥⹧:

-
200‰001588776 2


周攠慢ove⁳ 物rg⁣on瑡楮猠3⁦楥汤猠獥p慲a瑥T⁢y⁡ 獰s捥


周攠晩f獴⁦楥汤⁩湤楣慴敳e瑨攠牥瑵牮⁣oT攬e椮e
-
200⁩猠O䬮O卥捯nT⁦楥汤⁩

瑨W⁂䕓⁡ 敲琠䥄I慮T 瑨W牤⁦楥汤⁩猠瑨攠
numb敲eo映o捣畲c敮e敳e

却物ng⁡摤No瑥⡓瑲楮g⁡ 敲e䥤Ⱐ却物Hg
no瑥)

䅤T猠愠noW攠Wo⁡渠數楳瑩ig 慬敲琠a

却物ng⁡獳楧n䅬敲琨却物ng⁡ 敲瑉搬⁓瑲eng
op敲慴o爩

䅳獩gn猠慮⁥s楳瑩Wg⁡汥牴⁴o 愠灡a瑩捵W慲aop敲慴o爠*

却物ng⁤敡獳楧n䅬敲琨却物ng 慬敲瑉a)

M敡獳楧n猠愠灡a瑩捵W慲a慬敲a

*

却物ng⁵ T慴a䅬敲琨却物ng⁡ 敲瑉搬e
却物ng⁦楥汤Ⱐ却物Hg 睖慬w攩

啰T慴a猠愠p慲瑩捵W慲⁦楥汤 fo爠慮⁡r敲琠睩瑨⁡wn敷 v慬a攠*

String getAlert(String alertId)



Retrieves the alert <P>

XML for a particular alert ID *

String closeAlert(String alertId, String
operator)

Closes an existing alert *

String getConfig()

Returns the current configuration of the integration *

String getVersion()

Returns the version header of the integration *


* Standard error codes are as follows:

-
200

-
500
Error description

-
503 Service is unavailable


Integrating using RESTful web service calls:


createAlert:




POST:


http://BEShost/piWS/resources/alert

Content: <?xml version="1.0" encoding="UTF
-
8"?><root><value>integrationId = 12345 | mcname = test | mcfile = /tmp/your.log | severity = 2 | text = this is a test
|</value></root>




addNote:


POST:
http://BEShost/piWS/resources/alert/0002375068

Content: <?xml version="1.0" encoding="UTF
-
8"?><root><value>note from external system</value></root>




Operator it set to whatever “UpdatedBy” is set to in $PPHOME/cfg/piWS.cfg which by default is ‘ird’.


addNoteOperator:

POST:
http://BEShost/piWS/resources/alert/0002375068/ppadmin

Cont
ent: <?xml version="1.0" encoding="UTF
-
8"?><root><value>note from external system</value></root>


assignAlert:


PUT:
http://BEShost/piWS/resources/alert/0002375368/assign/p
padmin


assignAlert (bulk)


PUT:
http://BEShost/piWS/resources/alert/bulk/assign/ppadmin

Content: <?xml version="1.0" encoding="UTF
-
8"?><root><value>
0002375068, 0002375069, 0002375070,

0002375071
</value></root>


deassignAlert:


PUT:
http://BEShost/piWS/resources/alert/0002375368/deassign


acceptAlert: PUT:
http://BEShost/piWS/resources/alert/0002375368/accept/ppadmin


acknowledgeAlert: PUT:
http://BESh
ost/piWS/resources/alert/0002375368/acknowledge/ppadmin


deacknowledgeAlert: PUT:
http://BEShost/piWS/resources/alert/0002375368/deacknowledge/ppadmin


updateAlert




P
UT:
http://BEShost/piWS/resources/alert/0002375068/updateField/text

Content: <?xml version="1.0" encoding="UTF
-
8"?><root><value>some new text</value></root>


getAlert:



GET:
http://BEShost/piWS/resources/alert/0002375068


closeAlert:


DELETE:
http://BEShost/piWS/resources/alert
/0002375068/ppadmin


closeAlert (bulk): DELETE:
http://BEShost/piWS/resources/alert/bulk/ppadmin

Content: <?xml version="1.0" encoding="UTF
-
8"?><root><value>
0002375068, 0002375069, 0002375070
, 0002375071
</value></root>


getConfig:


GET:
http://BEShost/piWS/resources/getConfig


getVersion:


GET:
http://BEShost/piWS/resources/getVersion


All XML sent as content in to REST calls must have at least a <root><value></value></root> structure otherwise the input will

not be correctly parsed.

Field

limitations are set to 8192 characters in length.


piWS.cfg:


#

# BES SOAP/XML & RESTful Web Services Integration

#

# WSDL is available from: http://BEShost/piWS/piWS?WSDL

# REST test page is available from: http://BEShost/piWS/

#

# BES message channel name

# Default: piWS

#

McName=piWS


# BES EventDaemon
connection properties (disabled)

#

# Default: localhost

#

EventDaemonHost=localhost

#

# Default: 35000

#

EventDaemonPort=35000


# BES AlertServer connection properties

# Default: 30000

#

AlertServerPort=30000


# Default: localhost

#

AlertServerHost=
localhost


# New alerts can be created either by:

#
-

Writing pipe separated lines to a file which a log file monitor can pick up and send in to the AlertServer. McNameListen need
s to be set to the name of the log message
channel so that piWS can listen o
n the integration work files for the AlertId (AlertIdWait=true McNameListen=piSNLogMon CreateAlertSendPMsg=false
McFile=/var/spool/ISS/POWERpack/piSN_alerts.log).

#
-

Sending <P> messages straight in to the AlertServer thereby bypassing SMARTview normalisa
tion. AlertId and occurrences are still returned from the AlertServer
(CreateAlertSendPMsg=true AlertIdWait=false).


# Send a <P> message direct in to the AlertServer bypassing SMARTview normalisation

# Default: true

#CreateAlertSendPMsg=true


# Wait for a
n AlertId from the integration work files

# Default: false

#AlertIdWait=true


# Timeout in milliseconds to wait for an AlertId from the integration work files

# Default: 30000

#AlertIdWaitTimeMs=30000


# The message channel name to listen for from the in
tegration work files

# Default: piWS

#McNameListen=piWSLogMon


# Specify the default log file which new createAlert messages are logged to

# This can be overriden in the string passed to createAlert by specifying an McFile field

# e.g
: severity=1 | customField1=val1 | McFile=/tmp/mc_piSCOM.log

# Default: nothing, i.e. don't save to a file

#

#McFile=


#

# Default: true

#

Debugging=true


# BES version we're connecting to, valid values: 34, 35

#

# Default: 34

#

BEStype=35


# Set the 'upda
tedBy' token when updating incidents

#

# Default: ird

#

#UpdatedBy=ird


# The switches below specify whether particular web service calls affect BES

#

# Defaults: As below

#

#WS_close=true

#WS_note=true

#WS_assign=true

#WS_deassign=true

#WS_accept=true

#
WS_acknowledge=true

#WS_deacknowledge=true


#WS_assignDoesAccept=true


# Maximum file size per
piWS.cfg
log in bytes

#

# Default: 5242880

#

#LogMaxBytes=5242880


# Web service authentication credentials need to be added in tomcat
-
users.xml:

#

# $PPHOME/e
Scape/tomcat/conf/tomcat
-
users.xml

#

# e.g.

# <?xml version='1.0' encoding='utf
-
8'?>

# <tomcat
-
users>

# <user username="BES1" password="ilinkuk1" roles="IntegrationUsers"/>

# </tomcat
-
users>

#

# A restart of tomcat will be required for this to take effec
t

#