AVEVA Message Bus Install Guide21

AVEVA Message Bus
Installation &
Configuration Guide
Release 2.1
Issue 4
Disclaimer
Information of a technical nature, and particulars of the product and its use, is given by AVEVA
Solutions Ltd and its subsidiaries without warranty. AVEVA Solutions Ltd and its subsidiaries
disclaim any and all warranties and conditions, expressed or implied, to the fullest extent
permitted by law.
Neither the author nor AVEVA Solutions Ltd, or any of its subsidiaries, shall be liable to any
person or entity for any actions, claims, loss or damage arising from the use or possession of any
information, particulars, or errors in this publication, or any incorrect use of the product,
whatsoever.
Copyright
Copyright and all other intellectual property rights in this manual and the associated software, and
every part of it (including source code, object code, any data contained in it, the manual and any
other documentation supplied with it) belongs to AVEVA Solutions Ltd or its subsidiaries.
All other rights are reserved to AVEVA Solutions Ltd and its subsidiaries. The information
contained in this document is commercially sensitive, and shall not be copied, reproduced, stored
in a retrieval system, or transmitted without the prior written permission of AVEVA Solutions Ltd
Where such permission is granted, it expressly requires that this Disclaimer and Copyright notice
is prominently displayed at the beginning of every copy that is made.
The manual and associated documentation may not be adapted, reproduced, or copied, in any
material or electronic form, without the prior written permission of AVEVA Solutions Ltd. The user
may also not reverse engineer, decompile, copy, or adapt the associated software. Neither the
whole, nor part of the product described in this publication may be incorporated into any third-
party software, product, machine, or system without the prior written permission of AVEVA
Solutions Ltd, save as permitted by law. Any such unauthorised action is strictly prohibited, and
may give rise to civil liabilities and criminal prosecution.
The AVEVA products described in this guide are to be installed and operated strictly in
accordance with the terms and conditions of the respective licence agreements, and in
accordance with the relevant User Documentation. Unauthorised or unlicensed use of the product
is strictly prohibited.
First published 2010.
Copyright 1994 to current year. AVEVA Solutions Limited and its subsidiaries. All rights reserved.
AVEVA Solutions Ltd, High Cross, Madingley Road, Cambridge, CB3 0HB, United Kingdom.
Trademarks
AVEVA and Tribon are registered trademarks of AVEVA Solutions Ltd or its subsidiaries.
Unauthorised use of the AVEVA or Tribon trademarks is strictly forbidden.
AVEVA product names are trademarks or registered trademarks of AVEVA Solutions Ltd or its
subsidiaries, registered in the UK, Europe and other countries (worldwide).
The copyright, trade mark rights, or other intellectual property rights in any other product, its
name or logo belongs to its respective owner.
________________________________________________________________________
Contents
1 SUMMARY ..........................................................................................................................................3
2 BACKGROUND ..................................................................................................................................3
3 INTRODUCTION................................................................................................................................3
4 SUBSCRIBER SERVICE ...................................................................................................................6
4.1 INTRODUCTION ..................................................................................................................................6
4.2 FEATURES ..........................................................................................................................................6
4.3 RECOMMENDED INSTALLATION FOR SUBSCRIBER ..............................................................................7
4.4 PREREQUISITES ..................................................................................................................................7
4.4.1 .NET Framework .....................................................................................................................7
4.4.2 Message Queuing Components ................................................................................................7
4.4.3 Port Conflict ............................................................................................................................7
4.4.4 Oracle Data Access Components (ODAC) ..............................................................................7
4.4.5 Oracle NET Files .....................................................................................................................8
4.5 SUBSCRIBER INSTALLATION ...............................................................................................................9
4.5.1 Installation ...............................................................................................................................9
4.5.2 Subscriber Configuration ......................................................................................................10
4.5.3 Starting the Service ................................................................................................................10
4.5.4 Software removal ...................................................................................................................11
4.6 SUBSCRIBER CONFIGURATION .........................................................................................................12
5 PUBLISHER SERVICE ....................................................................................................................13
5.1 INTRODUCTION ................................................................................................................................13
5.2 FEATURES ........................................................................................................................................13
5.3 RECOMMENDED INSTALLATION FOR PUBLISHER ..............................................................................14
5.4 PREREQUISITES ................................................................................................................................14
5.4.1 .NET Framework ...................................................................................................................14
5.4.2 Message Queuing Components ..............................................................................................15
5.5 PUBLISHER INSTALLATION ...............................................................................................................15
5.5.1 Installation .............................................................................................................................15
5.5.2 Starting the Service ................................................................................................................16
5.6 PUBLISHER CONFIGURATION ...........................................................................................................18
5.6.1 Introduction ...........................................................................................................................18
5.6.2 Configuration file ..................................................................................................................18
5.6.3 Parameters.............................................................................................................................19
6 INTERFACE CONFIGURATION DETAILS ................................................................................20
6.1 VPRM INTERFACE CONFIGURATION ................................................................................................20
6.1.1 Introduction ...........................................................................................................................20
6.1.2 Originating system configuration ..........................................................................................20
6.2 P&ID TO VPE INTERFACE CONFIGURATION ....................................................................................24
6.2.1 Introduction ...........................................................................................................................24
6.2.2 P&ID configuration ...............................................................................................................25
6.2.3 P&ID Plug-in installation .....................................................................................................26
6.2.5 Amend VPE Project ‘.ini’ file ................................................................................................30
7 CHANGING THE DEFAULT PORT FOR MSMQ.......................................................................31
7.1 UPDATE THE PUBLISHER CONFIG FILE .............................................................................................33
AVEVA Message Bus Page 1 of 47

________________________________________________________________________
8 MANAGING MESSAGE BUS QUEUES ........................................................................................34
8.1 INTRODUCTION ................................................................................................................................34
8.2 AVEVA MESSAGE BUS ADMINISTRATOR .......................................................................................35
8.2.1 Message Bus Administrator Menu operations .......................................................................35
9 CREATE AN ENCRYPTED PASSWORD .....................................................................................37
10 INSTALLING MESSAGE QUEUING COMPONENTS ...............................................................38
11 INSTALLING ORACLE DATA ACCESS COMPONENTS (ODAC) .........................................41

________________________________________________________________________
1 Summary
This document will show you how to install and configure your messaging
infrastructure with the AVEVA Message Bus, using Message Queuing version 3.0
on Microsoft Windows Server 2003 and/or Microsoft Windows XP Professional.
A step-by-step guide will help you configure your systems.
2 Background
This document assumes you are familiar with the following:
 Windows Server 2003 / Windows XP Professional

 Message Queuing version 3.0 installation and administration
 XML
 HTTP
 Oracle client setup and configuration
3 Introduction
AVEVA Message Bus (AMB) is a data transport mechanism between AVEVA
applications and other third party applications utilising Microsoft‟s Message
Queuing technology.
Please read the AVEVA products‟ release letters for compatibility with the
AVEVA Message Bus.
Figure 1: A simple overview of the AVEVA Message Bus Architecture

________________________________________________________________________
Benefit and Feature Descriptions
Fast and efficient choice for information transfer across distributed applications
 Once configure the data transfer is automatic (no manual intervention
required)
 Fully recoverable from server reboot
 Fire and forget
Centralised and scalable solution

 Allows deployment of Interfaces either on a dedicated or shared server
 New interfaces can be added by updating configuration files (no code change
to the AVEVA Message Bus)
Enables communication across heterogeneous networks and between computers

not always connected
 Where network connections are not stable
 Allows for scheduled maintenance, server reboots etc.
A secure transport mechanism over the Internet

 Files encrypted when https protocol is enabled
 Password encryption in configuration files
Guaranteed fail-safe delivery mechanism through a queued detached

background process
 Uses Microsoft Message Queue proven technology
 Handles complex transactions that ensures all or none of the operations take
effect
Unicode compliant, and supports the following language sets…

 Far-Eastern,
 non-European and
 European languages
Comprehensive fault diagnostics

 In case of catastrophic hardware failure
 Configurable e-mail notification on failure as appropriate for rapid rectification
Fully maintained audit information

 Transaction logs
 Data archiving
There are three software components to the AVEVA Message Bus:
1. The Subscriber Service (as a Windows service with a configuration file in

XML format)
2. The Queue Administrator, installed with the Subscriber (as a Windows
application which reads the Subscriber Service configuration file)
3. The Publisher Service (as a Windows service with a configuration file in
XML format)

________________________________________________________________________
NOTE: When installing AMB for the first time it is necessary to execute from the
Console desktop; or if using remote desktop it is necessary to execute using
MSTSC with console or admin option depending on your version of Windows e.g.
mstsc /console, otherwise error messages are not visible as they are displayed in
the desktop console. The following remote desktop assess methods correctly
report errors to the desktop console which will be visible and will not cause any
issues;
 VNC
 VMware client

________________________________________________________________________
4 Subscriber Service
4.1 Introduction
The Subscriber Service receives the data in Message format from the Publisher.
The data files are extracted from the Message Queue and processed according
to the individual interfaces.
Setup Check-list
Task Complete
.net framework installed
MSMQ installed
Port Conflict resolved
ODAC installed
Oracle NET Files
Subscriber installed
Subscriber configured
Encrypted password created
Service startup and logon verified
Service started
4.2 Features
The Subscriber is designed to watch one or many queues for incoming
messages and send the message body (data) to an Oracle database instance for
processing.
If processing fails for any reason then the queue is halted (although messages
are not stopped from arriving in the queue) and an email notification is sent.
Note: The main text in the email body is limited to 2,000 characters.
The AMB Administrator must deal with the issue.It may be necessary to delete
the failed message from the queue so that other queued message can be
processed.
NOTE The message shown at the top of the queue in the Queue Administrator or
the Computer Management console is always the current message.
For example, processing „fails‟ if AVEVA Message Bus can not logon to the
database as the specified user but the message will not be deleted.
All delivered Messages are removed off the Queue and data validation is handled
in the receiving AVEVA application. A copy of the file will still be present in the
„Processed‟ sub-folder on the Publisher.

________________________________________________________________________
4.3 Recommended installation for Subscriber
AVEVA recommends that the Subscriber service is installed on the Application
Server of the receiving AVEVA Application.
Typically the Publisher service will be installed on a remote file-server which acts
as the collection point of the transferred files.
NOTE: For the P&ID to VPE interface it is more important that the Subscriber is
installed on the VPE Application Server (see section „6.2 P&ID to VPE Interface‟
for more details)
Subscribers not installed on the application server must be installed on a server

that has Local Area Network (LAN) access to the application database server.
The Publisher and Subscriber services can both run on the same server,
therefore installing them on the same machine is a valid configuration. In this
case AVEVA recommends that both services are installed on the AVEVA
application server.
4.4 Prerequisites
The following software MUST be installed before installing AVEVA Message Bus
Subscriber Service.
4.4.1 .NET Framework

The .NET Framework version 2.0 will be required on the machines that will act as
the publisher and subscriber.
This is available as a free download from Microsoft.
Go to www.microsoft.com/downloads
Search for “.NET Framework”, select „Microsoft .NET Framework Version 2.0
Redistributable Package‟ and follow the instructions to install.
4.4.2 Message Queuing Components

The AVEVA Message Bus utilises Microsoft Message Queuing (MSMQ) as the
transport mechanism. Both the machine hosting the Publisher service and the
machine hosting the Subscriber service will need to have MSMQ installed.
See section „10 Installing Message Queuing Components‟ of this document.
4.4.3 Port Conflict

MSMQ HTTP Support requires the installation of IIS (Internet Information
Services) and therefore (by default) will use port 80.
See section „7 Changing the default port for MSMQ‟.
4.4.4 Oracle Data Access Components (ODAC)

Oracle Data Access Components (ODAC) needs to be installed on the machine
that will act as the Subscriber.(see section „11 Installing Oracle Data Access
Components (ODAC)‟.

________________________________________________________________________
4.4.5 Oracle NET Files
Update the TNSNames.ora and SQLNET.ora files with the relevant database
instances for the AVEVA Applications.
Check with your database administrator if unsure.

________________________________________________________________________
4.5 Subscriber installation

4.5.1 Installation
Run the AvevaMessageBus2.1.msi which will give the option to install the
Publisher and/or the Subscriber.
Select to install the Subscriber service

________________________________________________________________________
Continue through the next steps. This will install the Publisher service and
configuration files to the desired directory e.g. default is C:\Program
Files\AVEVA\MessageBus\
The Message Bus Queue Administrator will also be installed to the same
directory and a shortcut created (see section „8.2 AVEVA Message Bus
Administrator‟).
4.5.2 Subscriber Configuration

Note: - Subscriber service can be configured in two modes:
- Default Mode for VPRM interfaces
- Plug-in Mode for P&ID to VPE interface
See section „6 Interface Configuration details‟ for how to configure the Subscriber
for the relevant mode.
4.5.3 Starting the Service

The Windows Service will show as AVEVA Message Bus Subscriber in
Windows Services (Administrative Tools > Services) and is configured for manual
startup.

________________________________________________________________________
AVEVA recommend that the startup type should be changed to automatic
After successful configuration, start the Message Bus Publisher service from
Windows Services (Administrative Tools > Services).
NOTE:
1. The service must be restarted if any changes are made to the
configuration file(s).
2. The Subscriber Service needs write-access to a Log-File.
If the Log file is not located on the server then you may need to run the
service with named account rather than the Local system account.
To change this, go to „Log On‟ setting in the Properties of the Service.
4.5.4 Software removal

Use „Add or Remove Programs‟ from Control Panel to remove the software.

________________________________________________________________________
4.6 Subscriber Configuration
Note: - Subscriber service can be configured in two modes:

- Default Mode for VPRM interfaces
- Plug-in Mode for P&ID to VPE interface
See section „6 Interface Configuration details‟ for how to configure the Subscriber
for the relevant mode.

________________________________________________________________________
5 Publisher Service
5.1 Introduction
The Publisher Service collects data files from a specified directory and posts
these files as Messages to the Subscriber.
The Subscriber needs to be installed first to ensure the message queues are
created before the Publisher can post to them.
Setup Check-list
Task Complete
.net framework installed
MSMQ installed
Port Conflict resolved
Publisher installed
Publisher configured
Service startup and logon verified
Service started
5.2 Features
Recoverable messages
Each message is recoverable.

This means that the MSMQ system will guard against message delivery failure.
One of the most common failures is that the remote queue cannot be reached –
the remote server may be down.
In this case the MSMQ system will keep trying to reach the remote system until it
is successful.
Stopping and Starting the service
If the Publisher Service is stopped and re-started for any reason it will only start
sending those files that appeared in the directory to be watched after the last
successfully sent file.
This guards against sending files multiple times.
Processed files
All successfully processed files are moved to a directory named „processed‟

( which will be created as a sub-directory of the DirectoryToWatch ).
Publishing all the existing files in a directory

________________________________________________________________________
File for editing postall.cfg

Associated file PublisherConfig.xsd
If it is necessary to send all the processed files again (that are now in the
„processed‟ sub-directory) then follow these steps:
1. Create a file named postall.cfg in the same directory as Publisher.exe.

2. The entry in the file takes the same form as Publisher.cfg
NOTE The DirectoryToWatch parameter should still be the existing
watched directory.
Remember only to include directories and file types that need resending.
3. Stop and start the Publisher Service to process the files.
Once the files are successfully processed the postall.cfg file is deleted.
Transaction log
The file “marker.txt” is created in each directory that is watched and should not
be deleted.
The date-time stamp of the „marker.txt‟ file is set when the Publisher Service last
successfully processed a file.
5.3 Recommended installation for Publisher

AVEVA recommends that the Publisher service is installed on a file-server which
acts as the collection point of the files to be transferred.
Typically the Subscriber service will be installed on the Application Server of the
receiving AVEVA Application.
The Publisher and Subscriber services can both run on the same server,
therefore installing them on the same machine is a valid configuration. In this
case AVEVA recommends that both services are installed on the AVEVA
application server.
The program and configuration files for both services can be installed in the same
directory.
5.4 Prerequisites
The following software MUST be installed before installing AVEVA Message Bus
Publisher Service.
5.4.1 .NET Framework
The .NET Framework version 2.0 will be required on the machines that will act as
the publisher and subscriber.

________________________________________________________________________
This is available as a free download from Microsoft.
Go to www.microsoft.com/downloads
Search for “.NET Framework”, select „Microsoft .NET Framework Version 2.0
Redistributable Package‟ and follow the instructions to install.
5.4.2 Message Queuing Components

The AVEVA Message Bus uses Microsoft Message Queuing (MSMQ) as the
transport mechanism. Both the machine hosting the Publisher service and the
machine hosting the Subscriber service will need to have MSMQ installed (see
section „10 Installing Message Queuing Components‟).
5.5 Publisher Installation

5.5.1 Installation
Run the AvevaMessageBus2.1.msi which will give the option to install the
Publisher and/or the Subscriber.
Select to install the Publisher Service

________________________________________________________________________
Continue through the next steps. This will install the Publisher service and
configuration files to the desired directory.
e.g. default is C:\Program Files\AVEVA\MessageBus\
5.5.2 Starting the Service

The Windows Service will show as AVEVA Message Bus Publisher in Windows
Services (Administrative Tools > Services) and is configured for manual startup.
AVEVA recommend that the startup type should be changed to automatic
After successful configuration, start the Message Bus Publisher service from
Windows Services (Administrative Tools > Services).

________________________________________________________________________
NOTE:
1. The service must be restarted if any changes are made to the
configuration file(s).
2. The Publisher Service needs write-access to the watched directory.
If this is not located on the server then you may need to run the service
with named account rather than the Local system account.
To change this, go to „Log On‟ setting in the Properties of the Service.

Use „Add or Remove Programs‟ from Control Panel to remove the software.

________________________________________________________________________
5.6 Publisher Configuration
5.6.1 Introduction
The Publisher Service sits on the originating end of the Message Bus. It „listens‟
for incoming files and pushes these onto a Message Queue to the Subscriber.
The configuration consists of supplying the correct details of which directories to
„watch‟ and which remote message queues to post the files on.
5.6.2 Configuration file
Configuration file for editing Publisher.cfg

Associated file PublisherConfig.xsd
The configuration file consists of Publisher sections. There needs to be at least

one section (PublisherSection) entry in the configuration file before the Publisher
Service can work correctly.
As this configuration is in XML format there is an accompanying XSD (XML

schema).
A sample configuration file is shown below:

<?xml version="1.0" encoding="UTF-8" ?>
<Publisher xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="PublisherConfig.xsd">
<PublisherSection>
<DirectoryToWatch>C:\AMB\fordelivery1</DirectoryToWatch>
<FileFilter>*.xml</FileFilter>
<EventBufferSize>8</EventBufferSize>
<InternetHTTPS>n</InternetHTTPS>
<RemoteQueue>private$\localq1</RemoteQueue>
<RemoteServer>RemoteServerName1</RemoteServer>
<RemoteServerPort>80</RemoteServerPort>
</PublisherSection>
<PublisherSection>
</PublisherSection>
</Publisher>

________________________________________________________________________
5.6.3 Parameters
Parameter Explanation
DirectoryToWatch The directory that will be watched for files to publish
If the directory containing this file is to be specified in UNC

format ( i.e. „\\ukavevaserver\... ) rather than non-UNC
format ( C:\... ), then it is necessary to right-click on the
Aveva Message Bus Publisher Service, select
„Properties/Log On/This account‟ and supply a generic
User ( like „AVEVA\SystemAdministrator‟ ) with rights to
access that directory using its UNC name.
It‟s advisable to log in as the „generic‟ User above and

check that it does have access to the
<DirectoryToWatch> directory before using it here.
FileFilter Allows the publishing of specific files and/or file types
using the standard wildcard notation
EventBufferSize This is the internal buffer size in bytes. The default is 8192
(8 KB). You can set the buffer to 4 KB or larger, but it
must not exceed 64 KB. If you try to set the
InternalBufferSize property to less than 4096 bytes, your
value is discarded and the InternalBufferSize property is
set to 4096 bytes. For best performance, use a multiple of
4 KB on Intel-based computers.
InternetHTTPS Is the message being sent over secure HTTP (y)es or (n)o
RemoteQueue The remote (subscriber) queue name
Make sure your queue name is always preceded by
private$\
RemoteServer The remote server (subscriber) on which the queue exists
RemoteServerPort The port on which the MSMQ service is installed
Can be left blank if the default of 80 is used.
Any other combination of the above, e.g. a different directory with a different file
filter or the same directory with a different file filter, requires a new
PublisherSection in the configuration file.
Save the configuration file in the same directory as Publisher.exe

________________________________________________________________________
6 Interface Configuration details

6.1 VPRM Interface configuration
6.1.1 Introduction
All VPRM interfaces use a single XML file to import the data into VPRM.
This file is placed on the Message Queue by the Publisher. The Subscriber takes
the data directly from the Queue and pushes this into the VPRM database (it is
not stored anywhere as a file by the subscriber service).
To configure the Message Bus Subscriber service for VPRM interfaces you have
to complete the following steps:
- Update the Message Bus configuration file „Subscriber.cfg‟
- Update the Message Bus configuration file „Interface.cfg‟
6.1.2 Originating system configuration

To configure the originating system for sending data files to VPRM via the
Message Bus, please refer to the system‟s documentation for details.
6.1.3.1 Configuration file: Subscriber.cfg

Recommended configuration:
AVEVA recommends that the Message Bus is configured with a separate Queue
per publisher for each interface which will handle multiple VPRM projects.
The subscriber.cfg configuration file is installed with the Message Bus and will be
in the same directory as the Subsciber.exe file.
Configuration file for editing Subscriber.cfg

Associated file SubscriberConfig.xsd
There needs to be at least one section (SubscriberSection) entry in the

configuration file before the Subscriber Service can work correctly.
As this configuration is in XML format there is an accompanying XSD

(XML schema).
NOTE:
If the subscriber has already been installed for other interfaces, then all that
needs to be done is add a new Subscriber section to the existing file.

________________________________________________________________________

<Subscriber xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="SubscriberConfig.xsd">
<SubscriberSection>
<DatabaseHost>DatabaseServerName</DatabaseHost>
<DatabaseSID>OracleDatabaseSID</DatabaseSID>
<DatabaseUser>admin</DatabaseUser>
<DatabasePassword>HurXYXVB_O-UO3h3CjvwKA2</DatabasePassword>
<IsDBPasswordEncrypted>Y</IsDBPasswordEncrypted>
<DatabasePort>1521</DatabasePort>
<DatabaseProtocol>TCP</DatabaseProtocol>
<EmailAddresses>user1@company1.com</EmailAddresses>
<EmailFromAddress>user1@company2.com</EmailFromAddress>
<AdditionalMessage/>
<EmailServer>mailserver.company.com</EmailServer>
<LocalQueue>private$\localq1</LocalQueue>
<LogFilePath>C:\vmb\logfile1.txt</LogFilePath>
</SubscriberSection>
<SubscriberSection>
<DatabaseHost>DatabaseServerName</DatabaseHost>
<DatabaseSID>OracleDatabaseSID</DatabaseSID>
<DatabaseUser>admin</DatabaseUser>
<DatabasePassword>HurXYXVB_O-UO3h3CjvwKA2</DatabasePassword>
<IsDBPasswordEncrypted>Y</IsDBPasswordEncrypted>
<DatabasePort>1521</DatabasePort>
<DatabaseProtocol>TCP</DatabaseProtocol>
<EmailFromAddress>user2@company2.com</EmailFromAddress>
<LogFilePath>C:\vmb\logfile2.txt</LogFilePath>
</Subscriber>

________________________________________________________________________
DatabaseHost The database server name
DatabasePassword The password for the „DatabaseUser‟ below.
This SHOULD be encrypted, see section ‘9 Create
an Encrypted Password’.
IsDBPasswordEncrypted Is the database password in an encrypted form?
(y)es or (n)o
DatabasePort The instance Port number – normally 1521
DatabaseProtocol The database protocol – normally TCP
DatabaseSID The instance SID – look in the tnsnames.ora file for
the correct entry
DatabaseUser The instance admin user
EmailAddresses A list of users to be notified by email when an error in
processing the data occurs.
Use a semicolon (;) to separate entries.
EmailFromAddress Optional address to which emails will be returned if
users respond to the email notification of a problem
( default is DO_NOT_REPLY@unattended.com ).
AdditionalMessage Optional message which will be displayed at the end
of email notifications.
EmailServer Your email server name
LocalQueue The Message Queue to watch to incoming messages
(this will be created if it does not exist)
Make sure your queue name is always preceded
by private$\
LogFilePath Location of the file to log all transactions for this
section
This must be unique for each section
If the directory containing this file is to be specified in

UNC format ( i.e. „\\ukavevaserver\... ) rather than
non-UNC format ( C:\... ), then it is necessary to right-
click on the Aveva Message Bus Subscriber Service,
select „Properties/Log On/This account‟ and supply a
generic User ( like „AVEVA\SystemAdministrator‟ )
with rights to access that directory using its UNC
name.
It‟s advisable to log in as the „generic‟ User above and

check that it does have access to the <LogFilePath>
directory before using it here.
Save the configuration file in the same directory as Subscriber.exe

________________________________________________________________________
6.1.3.2 Configuration file: Interface.cfg
The Interface.cfg configuration file is installed with the Message Bus and will be
Configuration file for editing Interface.cfg

Associated file Interface.xsd
This configuration file is used to tell the subscriber service where to process the
content of the xml file for each interface.
The XML file is processed on the database so an existing table name is provided
for this purpose.
This file can be extended as new interfaces become available.
As this configuration is in XML format there is an accompanying XSD (XML

schema).

<Interfaces xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="Interface.xsd">
<Interface Name="ProgressPayment" DBTableName="PP_XML" />
<Interface Name="MaterialIssued" DBTableName="MI_XML" />
<Interface Name="MaterialReceipt" DBTableName="MR_XML" />
<Interface Name="FreeIssueReturn" DBTableName="FIR_XML" />
<Interface Name="DataTranfer" DBTableName="PID_XML" />
<Interface Name="CommittedCost" DBTableName="CC_XML" />
</Interfaces>
Please see the receiving application‟s documentation for the exact entries which
need to be added to this file.
Name The interface name
(Name of the Root element of the XML data file)
DBTableName The related database table name for this interface

________________________________________________________________________
6.2 P&ID to VPE Interface configuration
6.2.1 Introduction
When Synchronising a P&ID drawing, 16 separate files are sent to VPE. The files
are put on the Message Bus and received by the Subscriber.
The PIDDataLoader Plug-in „plugs into‟ the Subscriber service and collects the
files. A „drawing folder‟ is created in the working directory and the files are copied
into this folder. Once all 16 files have been received the data is pushed into VPE
and the drawing folder, with all the files, is moved into a processed directory.
End-to-end connection detail:

P&ID is configured with the VPE database instance and VPE project number.
These are exported with all the drawing files from P&ID in a .drgx file.
The Subscriber service reads the .drgx file and, combined with the username and
password from the VPE.ini file, uses these to access the correct database and
VPE project.
To configure the Message Bus Subscriber service for the P&ID to VPE interface
you have to complete the following steps:
- Configure P&ID to use the Message Bus
- Install the PIDDataLoader Plug-in
- Update the Message Bus configuration file „Subscriber.cfg‟
- Update the PIDDataLoader Plug-in configuration file
- Update the VPE.ini file
NOTE:
It is important that the Subscriber service is installed on the VPE Application
Server (Middle Tier). The Subscriber Plug-in will need to access the VPE.ini file
in order to obtain the username and password.
The location of the VPE.ini file is determined from the Registry Key:
HKEY_LOCAL_MACHINE\Software\AVEVA\VPE\
The value in vpe_config is the location of VPE.ini file.
(see section below on Amend VPE Project „.ini’ file)
To avoid port conflict you my need to change the default port for MSMQ (see
section „7 Changing the default port for MSMQ‟).

________________________________________________________________________
Publisher Service: Subscriber Service:

Watches for files from VPE in defined Waits for messages on Message Queues
directory and publishes these to the PIDDataLoader Plugs into Subscriber
Message Queue on the Subscriber and extracts files from Messages.
A Sub-folder is created for each
Drawing.
Once all 16 files have been received the
data is pushed into VPE
MSMQ
Publisher Subscriber
16 Drawing
files copied
into watched PIDDataLoader
Working
directory
Directory
Drawing
Sub-folder
P&ID
Data pushed
into VPE
6.2.2 P&ID configuration

P&ID needs to be configured to use the AVEVA Message Bus.
Specify VPE Database instance and VPE project name.
Either manually type or use VPE.ini file for drop-down list.
(See AVEVA P&ID user guide for more details)
Specify the Publisher Service‟s watched directory (as specified in the

Publisher.cfg configuration file, section „5.6.2 Configuration file‟) in the „Publisher
Folder‟ parameter.

________________________________________________________________________
6.2.3 P&ID Plug-in installation

Install PID Loader Component which comes with the P&ID installer.

________________________________________________________________________
Follow instructions from the Installer.
Change the path for the plug-in.

The plug-in „PIDDataLoader.dll‟ must be installed in the same directory as
Subscriber service e.g. c:\program files\AVEVA\Message Bus\

________________________________________________________________________
NOTE: The configuration file Interface.cfg, which is installed with the Message
Bus, is not used by this interface.
6.2.4.1 Configuration file: Subscriber.cfg

The subscriber.cfg configuration file is installed with the Message Bus and will be
Configuration file for editing Subscriber.cfg

Associated file SubscriberConfig.xsd
There needs to be at least one section (SubscriberSection) entry in the

configuration file before the Subscriber Service can work correctly.
As this configuration is in XML format there is an accompanying XSD
(XML schema). A sample configuration XML file is shown below:
NOTE:
If the subscriber has already been installed for other interfaces, then all that
needs to be done is add a new Subscriber section to the existing file.
Sample file
<Subscriber xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="SubscriberConfig.xsd">
<SubscriberSection>
<PluginAssembly>PluginFolder\AssemblyName.dll</PluginAssembly>
<EmailFromAddress>administrator@company.com</EmailFromAddress>
<LogFilePath>C:\AMBSubscriber\logfile1.txt</LogFilePath>
</Subscriber>
PluginAssembly The relative path to .NET assembly that implements
interface.
e.g. PIDLoader\PIDDataLoader.dll
EmailAddresses A list of users to be notified by email when an error in
processing the data occurs. Use a semicolon (;) to
separate entries
EmailFromAddress Email address of the user or application sending the
mail. It could be P&ID project administrators.
AdditionalMessage Any additional message required for subscriber to
process the message from queue.
EmailServer Your email server name

________________________________________________________________________
LocalQueue The Message Queue to watch to incoming messages
(this will be created if it does not exist) Make sure
your queue name is always preceded by private$\
LogFilePath Location of the file to log all transactions for this
section. This must be unique for each section
6.2.4.2 Configuration file: pidloader.cfg

The „pidloader.cfg‟ configuration file is installed with the Plug-in and will be in the
same directory as the Subsciber.exe file.
Configuration file for editing pidloader.cfg

Associated file n/a
A sample settings file is shown below (the actual data highlighted in yellow):
<?xml version="1.0" encoding="utf-8" ?>

<userSettings>
<setting name="WorkingDirectory" serializeAs="String">
<value>C:\Program Files\AVEVA\MessageBus\PIDLoader\</Value>
</setting>
<setting name="Filter" serializeAs="String">
<value>*.*</Value>
</setting>
<setting name="Processed" serializeAs="String">
<value>C:\Program
Files\AVEVA\MessageBus\PIDLoader\Processed</Value>
</setting>
<setting name="DataFileCount" serializeAs="String">
<value>16</Value>
</setting>
</userSettings>
WorkingDirectory This is the directory where data files received from
subscriber is saved for processing.
Filter Can be used to selectively process files.
Should be set to *.* to allow PIDDataLoader to pick up all
the files from working directory.
Processed This is the directory where P&ID Data files are saved after
processing.
DataFileCount This specifies the number of files that has to be picked up
by PIDDataLoader for processing.
Must be set to 16 for the current PIDDataLoader
Save the settings file in the same directory as the Subsciber.exe file.

________________________________________________________________________
6.2.5 Amend VPE Project ‘.ini’ file
To allow PIDDataLoader to connect to VPE the <Project>.ini file needs to contain
both the Username and Password
The entry to add to the .ini file is

PIDdataLoader]
UserName=Database project User name
Password=Database user passworder password
for example:
[ PI Ddat aLoader ]
User Name=vpe1
Passwor d= i P6xi nJWCNV8_r nTU4bvxQ2
NOTE:
See section „9 Create an Encrypted Password‟ section to ensure the password is
not human-readable.

________________________________________________________________________
7 Changing the default port for MSMQ

MSMQ HTTP support is installed in the default Web Site of the Internet
Information Services (IIS), by default this is installed on port 80.
Both the VPRM and VPE application server (middle tier) will be running the
VPRM/VPE application on port 80 and therefore by default the IIS default Web
Site will be disabled.
In order to be able to run the Message Bus Services (using MSMQ) successfully
and avoid a port conflict the port for the default Web Site will need to be changed
away from port 80, and the Publisher config file will need to be updated to call the
server on the correct port.
Changing the default Web Site port:

Open the IIS Manager (Start->Control Panel->Administrative Tools) and open the
properties of the default Web Site.
Change the TCP port from 80 to another available port number

________________________________________________________________________
NOTE: Check with your Network administrator which ports are available for this
purpose
Click on OK and start the Web Site

________________________________________________________________________
7.1 Update the Publisher Config file

The publisher‟s config file needs to specify the server with the correct port
number, highlighted yellow below:

<Publisher xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="PublisherConfig.xsd">
<PublisherSection>
</PublisherSection>
<PublisherSection>
</PublisherSection>
</Publisher>

________________________________________________________________________
8 Managing Message Bus Queues

8.1 Introduction
Message Queues should not be manually created for use with the Message Bus
application.
Only the application should be used to create and administer (via the Queue
Administrator) the Message Queues.
Message Queues can be deleted by the user using the Computer Management
console – see figure 5.
You cannot however delete individual “bad” messages via this console
– use the Queue Administrator application for this.
Figure 5: Viewing Message Queuing through the Computer Management console.
The Message Bus Queue Manager has been developed for the purpose of
managing those queues relevant to the Message Bus Publisher – see below.

________________________________________________________________________
8.2 AVEVA Message Bus Administrator

The AVEVA Message Bus Queue Administrator is installed along with the
Subscriber software and a shortcut created in „All Programs > AVEVA > Message
Bus‟.
This application gives much more queue management control over the Microsoft
installed tool through the Computer Management console.
The Queue Manager uses the same configuration file (Subscriber.cfg) as the
Subscriber to know which queues to manage.
Figure 6: The Message Bus Queue Administrator
8.2.1 Message Bus Administrator Menu operations

The table below lists each operation available from the menus of the Queue
Manager.
Has right-click context

Menu item Menu sub item Operation
menu?
File Exit Exit the application No
Queue Refresh Refresh the display No
Purge Purge the selected queue – this Yes
does not delete the queue only
the messages
Delete Message Delete the selected message Yes
Tools Create Encrypted Create an encrypted (database) No
Password password for use in the
subscriber.cfg file
Help About Queue Information about Queue No
Manager Manager

________________________________________________________________________
Removing the Subscriber will also remove Message Bus Administrator.

________________________________________________________________________
9 Create an Encrypted Password

As the configuration of the Message Bus system is held in XML files (and so are
human-readable) this can pose a security risk when it comes to passwords, i.e.
the database password in subscriber.cfg.
So that the system can be as secure as possible it is recommended that you

create an encrypted password using the option from the Tools menu of
Administrator.
Figure 7: Creating an encrypted password
Type in the database password as shown above and click Encrypt.
The new encrypted password is shown.
Use the Copy to Clipboard button to help you copy and paste the password into
the <DatabasePassword> element of the subscriber.cfg xml file.

________________________________________________________________________
10 Installing Message Queuing Components

For all production systems it is recommended that Microsoft Server 2003 be used
as it is highly likely that the AVEVA Message Bus Publisher and Subscriber
services will be installed onto systems that already have AVEVA‟s VPE and/or
VPRM products.
Check that Message Queuing has been installed on your system(s):

Control Panel > Add or Remove Programs > Add/Remove Windows Components
Figure 2.1: Adding the Message Queuing component under Windows XP

________________________________________________________________________
Figure 2.2: Adding the Message Queuing component under Windows Server 2003
In addition to installing the Message Queuing component you will need to install
MSMQ HTTP Support to be able to send and receive MSMQ messages via the
Internet.
Press the „Details…‟ button to view the options.

________________________________________________________________________
Figure 3: Adding MSMQ HTTP Support. You must install MSMQ HTTP support to be able to send
and receive MSMQ messages via the Internet.
NOTE:
1. Active Directory Integration is NOT checked
2. The Triggers section is not required for the MessageBus but can be
installed if desired.
IMPORTANT
The Message Bus does not require Active Directory integration and therefore
needs to be installed in Workgroup mode i.e. without Active Directory Integration
support.

________________________________________________________________________
11 Installing Oracle Data Access Components (ODAC)

To install, download Oracle 11g ODAC 11.1.0.7.20 (Oracle Universal Installer
version) from ODAC for Windows Downloads.
To download:
- go to www.oracle.com.
- Click on the „Downloads‟ link.
- In the „Drivers‟ section click on „Oracle Data Access Components for
Windows‟.
- Find the “Oracle 11g ODAC 11.1.0.7.20” section and click to download the
file.
- Accept the License agreement
- Download the ODAC1110720.zip file and installation instructions
Figure 4: Files unzipped from the downloaded ODAC1110720.zip file.
Start installing ODAC using the Setup.exe shown in Fig 4 above. Then follow the
installation wizard as shown in below figures.

________________________________________________________________________
Figure 4.1: Start up installation wizard screen.
Click “Next” to follow the installation.

________________________________________________________________________
Figure 4.2: Product selection screen.
Select Oracle Data Access Components for Oracle Client 11.1.0.7.20
Figure 4.3: Installation folder setup screen.

________________________________________________________________________
Figure 4.4: Component selection screen.
For AMB we require only Oracle Data Provider for .NET 2.0 11.1.0.7.20 and
Oracle Instant Client 11.1.0.7.0 so select only these two components.
Figure 4.5: Installation details screen.
Click “Install” and wait for the installation to complete.

________________________________________________________________________
Once complete update the tnsnames.ora and sqlnet.ora files that should be in the
location:
<OraClient11g_home>\NETWORK\ADMIN

AVEVA Message Bus Install Guide21

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

AVEVA Message Bus Install Guide21

Uploaded by

Copyright:

Available Formats

AVEVA Message Bus

First published 2010.

AVEVA Message Bus Page 1 of 47

AVEVA Message Bus Page 2 of 47

A step-by-step guide will help you configure your systems.

 Windows Server 2003 / Windows XP Professional

Figure 1: A simple overview of the AVEVA Message Bus Architecture

AVEVA Message Bus Page 3 of 47

Centralised and scalable solution

Enables communication across heterogeneous networks and between computers

A secure transport mechanism over the Internet

Guaranteed fail-safe delivery mechanism through a queued detached

Unicode compliant, and supports the following language sets…

Comprehensive fault diagnostics

Fully maintained audit information

There are three software components to the AVEVA Message Bus:

1. The Subscriber Service (as a Windows service with a configuration file in

AVEVA Message Bus Page 4 of 47

AVEVA Message Bus Page 5 of 47

AVEVA Message Bus Page 6 of 47

Subscribers not installed on the application server must be installed on a server

4.4.1 .NET Framework

4.4.2 Message Queuing Components

4.4.3 Port Conflict

4.4.4 Oracle Data Access Components (ODAC)

AVEVA Message Bus Page 7 of 47

AVEVA Message Bus Page 8 of 47

4.5 Subscriber installation

Select to install the Subscriber service

AVEVA Message Bus Page 9 of 47

4.5.2 Subscriber Configuration

4.5.3 Starting the Service

AVEVA Message Bus Page 10 of 47

4.5.4 Software removal

AVEVA Message Bus Page 11 of 47

Note: - Subscriber service can be configured in two modes:

AVEVA Message Bus Page 12 of 47

Each message is recoverable.

Stopping and Starting the service

All successfully processed files are moved to a directory named „processed‟

Publishing all the existing files in a directory

AVEVA Message Bus Page 13 of 47

File for editing postall.cfg

1. Create a file named postall.cfg in the same directory as Publisher.exe.

5.3 Recommended installation for Publisher

5.4.1 .NET Framework

AVEVA Message Bus Page 14 of 47

5.4.2 Message Queuing Components

5.5 Publisher Installation

Select to install the Publisher Service

AVEVA Message Bus Page 15 of 47

5.5.2 Starting the Service

AVEVA recommend that the startup type should be changed to automatic

AVEVA Message Bus Page 16 of 47

5.5.3 Software removal

AVEVA Message Bus Page 17 of 47

5.6.2 Configuration file

Configuration file for editing Publisher.cfg

The configuration file consists of Publisher sections. There needs to be at least

As this configuration is in XML format there is an accompanying XSD (XML

A sample configuration file is shown below:

AVEVA Message Bus Page 18 of 47

If the directory containing this file is to be specified in UNC

It‟s advisable to log in as the „generic‟ User above and