AVEVA™ Enterprise Integration

User Guide
Version 6.2
September, 2021

aveva.com
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved.

No part of this documentation shall be reproduced, stored in a retrieval system, or transmitted by any means,
electronic, mechanical, photocopying, recording, or otherwise, without the prior written permission of AVEVA.
No liability is assumed with respect to the use of the information contained herein.
Although precaution has been taken in the preparation of this documentation, AVEVA assumes no responsibility
for errors or omissions. The information in this documentation is subject to change without notice and does not
represent a commitment on the part of AVEVA. The software described in this documentation is furnished under
a license agreement. This software may be used or copied only in accordance with the terms of such license
agreement.
ArchestrA, Avantis, Citect, DYNSIM, eDNA, EYESIM, InBatch, InduSoft, InStep, IntelaTrac, InTouch, OASyS,
PIPEPHASE, PRiSM, PRO/II, PROVISION, ROMeo, SIM4ME, SimCentral, SimSci, Skelta, SmartGlance, Spiral
Software, WindowMaker, WindowViewer, and Wonderware are trademarks of AVEVA and/or its subsidiaries. An
extensive listing of AVEVA trademarks can be found at: https://sw.aveva.com/legal. All other brands may be
trademarks of their respective owners.
Publication date: Saturday, September 25, 2021
Contact Information
AVEVA Group plc
High Cross
Madingley Road
Cambridge
CB3 0HB. UK
https://sw.aveva.com/
For information on how to contact sales and customer training, see https://sw.aveva.com/contact.
For information on how to contact technical support, see https://sw.aveva.com/support.
To access the AVEVA Knowledge and Support center, visit https://softwaresupport.aveva.com.
Contents

Chapter 1 Getting Started .................................................................................. 8

Opening the EI Application ....................................................................................................................8
Listing Pages and Details Pages............................................................................................................ 10
Filtering Lists....................................................................................................................................... 11
Refreshing Page Content ..................................................................................................................... 11

Chapter 2 Managing Security ........................................................................... 12

Viewing Security Groups ..................................................................................................................... 13
Security Management Actions and Privileges Required ........................................................................ 13
Filtering Security Groups ..................................................................................................................... 13
Adding a Security Group...................................................................................................................... 14
Editing a Security Group ...................................................................................................................... 15
Deleting a Security Group.................................................................................................................... 15

Chapter 3 Managing Location Types ................................................................ 16

Viewing Location Types ....................................................................................................................... 16
Location Type Actions and Privileges Required..................................................................................... 16
Adding a Location Type ....................................................................................................................... 17
Editing a Location Type ....................................................................................................................... 17
Deleting a Location Type ..................................................................................................................... 18

Chapter 4 Managing Location Groups .............................................................. 19

Viewing Location Groups..................................................................................................................... 19
Location Group Actions and Privileges Required .................................................................................. 19
Filtering Location Groups .................................................................................................................... 19
Adding a Location Group ..................................................................................................................... 20
Editing a Location Group ..................................................................................................................... 20
Deleting a Location Group ................................................................................................................... 21

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 3
 Chapter 5 Managing Message Types ................................................................ 22
Viewing Message Types ...................................................................................................................... 23
Message Type Actions and Privileges Required .................................................................................... 23
Filtering Message Types ...................................................................................................................... 24
Adding a Message Type ....................................................................................................................... 24
Editing a Message Type ....................................................................................................................... 25
Deleting a Message Type ..................................................................................................................... 25
Summary Expressions ......................................................................................................................... 25
Summary Expressions for XML Message Types ......................................................................................... 25
Summary Expressions for Flat File Message Types .................................................................................... 26
Summary Expressions for CSV, Pipe-Delimited, and Tab-Delimited Message Types................................. 26

Chapter 6 Managing Location Categories ......................................................... 27

Viewing Location Categories................................................................................................................ 27
Location Category Actions and Privileges Required .............................................................................. 27
Filtering Location Categories ............................................................................................................... 28
Adding a Location Category ................................................................................................................. 28
Editing a Location Category ................................................................................................................. 28
Deleting a Location Category ............................................................................................................... 29

Chapter 7 Managing Message Services ............................................................ 30

Viewing Message Services ................................................................................................................... 30
Message Service Actions and Privileges Required................................................................................. 30
Adding or Deleting a Message Service ................................................................................................. 30
Editing a Message Service ................................................................................................................... 30

Chapter 8 Managing Message Locations .......................................................... 32

Viewing Message Locations ................................................................................................................. 32
Message Location Actions and Privileges Required............................................................................... 32
Filtering Message Locations................................................................................................................. 33
Setting the Status of Selected Message Locations ................................................................................ 33
Adding Message Locations .................................................................................................................. 34
Message Location Properties ..................................................................................................................... 34
Editing Message Locations................................................................................................................... 36
Deleting Message Locations ................................................................................................................ 37
Working with Inbound Location Types ................................................................................................. 37
Schedules for Inbound Locations ............................................................................................................... 37
Type CODE .................................................................................................................................................. 38
Type DIRECT ............................................................................................................................................... 38
Type FOLDER .............................................................................................................................................. 39

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 4
 Type MESJobEnd ........................................................................................................................................ 39
Type MESShiftEnd ...................................................................................................................................... 40
Type MESTable ........................................................................................................................................... 41
Type MSMQ ................................................................................................................................................ 42
Type SQLQuery ........................................................................................................................................... 43
Working with Outbound Location Types .............................................................................................. 44
Type CODE .................................................................................................................................................. 44
Type FOLDER .............................................................................................................................................. 45
Type MESTable ........................................................................................................................................... 46
Type MSMQ ................................................................................................................................................ 48
Type SQLQuery ........................................................................................................................................... 48
Transfer Destinations .......................................................................................................................... 49
Adding Transfer Destination Locations ...................................................................................................... 49
Editing a Transfer Destination Location's Transforms ............................................................................... 50
Editing Transfer Destination Locations ...................................................................................................... 52
Deleting Transfer Destination Locations .................................................................................................... 53
Mappings ........................................................................................................................................... 53
Location Type Mappings ............................................................................................................................ 53
Delimited Text Source ............................................................................................................................ 53
XML Attribute-Based Source .................................................................................................................. 54
XML Element-Based Source .................................................................................................................... 54
Database Table Source ........................................................................................................................... 54
Flat Source .............................................................................................................................................. 54
MES Table Source ................................................................................................................................... 55
Delimited Text Destination ..................................................................................................................... 55
XML Attribute-Based Destination ........................................................................................................... 55
XML Element-Based Destination ............................................................................................................ 56
Text Template Destination ..................................................................................................................... 56
Adding Mappings........................................................................................................................................ 57
Editing Mappings ........................................................................................................................................ 57
Deleting Mappings ..................................................................................................................................... 59
Helper Functions ........................................................................................................................................ 59
Post Actions ........................................................................................................................................ 62
Adding Post Actions.................................................................................................................................... 63
Post Action Type Properties ................................................................................................................... 64
Editing Post Actions .................................................................................................................................... 66
Deleting Post Actions ................................................................................................................................. 66

Chapter 9 Managing Translations .................................................................... 68

Chapter 10 Managing Distribution Lists ........................................................... 71

Chapter 11 Managing Connections .................................................................. 73

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 5
 Chapter 12 Application Configuration .............................................................. 76
Application Configuration Actions and Privileges Required................................................................... 76
Viewing Plant Configuration Data ........................................................................................................ 77
Editing Plant Configuration Parameter Values...................................................................................... 77

Chapter 13 Event Log ....................................................................................... 78

Event Log Listing Actions and Privileges Required ................................................................................ 78
Viewing Event Log Entries ................................................................................................................... 78
Viewing Event Log Entry Details........................................................................................................... 79
Viewing EI Events in the ArchestrA System Management Console ........................................................ 79

Chapter 14 Message Log .................................................................................. 80

Message Log Actions and Privileges Required ...................................................................................... 81
Viewing the Message Log .................................................................................................................... 82
Filtering the Message Log .................................................................................................................... 82
Viewing Message Details ..................................................................................................................... 83
Re-Processing Messages ...................................................................................................................... 83
Archiving Messages............................................................................................................................. 83

Chapter 15 Message Display ............................................................................ 85

Message Display Actions and Privileges Required ................................................................................ 85
Viewing Message Details ..................................................................................................................... 86
Archiving a Message ........................................................................................................................... 87
Re-Processing Messages ...................................................................................................................... 87
Re-Processing Message Transfers ........................................................................................................ 87
Exporting Messages ............................................................................................................................ 87
Viewing and Editing the Message Content ........................................................................................... 87
Viewing a Message’s Additional Details Pages ..................................................................................... 88

Chapter 16 Message Summary by Location Category ....................................... 89

Message Summary Actions and Privileges Required ............................................................................. 90
Viewing the Message Summaries by Location Category Listing ............................................................. 90
Changing a Location Category’s Status ................................................................................................. 91
Sending EI Messages to a Destination .................................................................................................. 91

Chapter 17 Plug-In Development ..................................................................... 92

IMessageSendReceive ......................................................................................................................... 92
IMessagePreSend................................................................................................................................ 93

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 6
 IMessageTransform ............................................................................................................................ 93
IMessageAbortTransfer ....................................................................................................................... 93
IMessageProcessor ............................................................................................................................. 94

Chapter 18 EI Web Services ............................................................................. 95

User Interface ..................................................................................................................................... 95
Invoking the AddMessage Method from the Details Web Page............................................................. 96
Invoking the AddMessage Method from an Application ....................................................................... 97

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 7
Chapter 1

Getting Started

The Enterprise Integration (EI) application is a scalable, configurable product that provides a loosely-coupled
linkage between the manufacturing system and business systems such as ERP, PLM, SCM, or LIMS. EI facilitates
the exchange of information between disparate systems and software via messages that are buffered and
tracked to provide a seamless and reliable interface. This interface comprises adapters that provide any
endpoint specific transformations, database processing, and internal processing causing secondary message
generation.
This guide describes the EI user interface for defining message groups, types, categories source and destination
locations, and the transfer requirements that enable the transport of messages from the source location to the
specified destination location. Details are provided for mapping source and destination locations as well as
configuring post-actions to execute based on the processing status of outbound locations.
This guide also describes how to attach custom plug-ins to message locations or to transfer requirements
between message locations. The plug-in provides extended message processing functionality to an EI adapter.
Finally, this guide describes the application program interface (API) needed to implement a custom EI plug-in.

Opening the EI Application

By default, EI will be installed with its configuration and management website on the server computer. The
website can be accessed from any computer with an Internet Explorer 10 or greater browser and an authorized
connection to the server.
The URL is http://<computer>/EI, where <computer> represents the network name of the server computer.
When using the web browser on the actual server computer, the URL is http://localhost/EI.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 8
 AVEVA™ Enterprise Integration User Guide
Chapter 1 – Getting Started

Upon connecting to the EI website, the Overview page appears.

From this page, you can navigate to all other pages using the navigation menu at the top left, as shown below.

To return to the Overview page, click the icon at the upper left corner of any page.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 9
 AVEVA™ Enterprise Integration User Guide
Chapter 1 – Getting Started

Listing Pages and Details Pages

Many of the pages have a hierarchy that begins with a listing page that lists related entries in a grid, as shown
below for the Manage Message Locations page.

You can then open an entry's details page by:

 Clicking the Add or New button on the page's toolbar to create a new entry
 Clicking the entry's ID hyperlink to open its details page for viewing or editing

On most details pages, you can return to the listing page by clicking the Listing button on the page's toolbar.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 10
 AVEVA™ Enterprise Integration User Guide
Chapter 1 – Getting Started

Filtering Lists
Many of the pages with lists have filter boxes above the list grid that allow you to filter the list to see only
entries of interest.

The filters behave as follows:

 As you enter text in a filter text box or select an entry from a filter list, the list automatically updates. Only
list entries whose corresponding columns match what has been entered in the filter boxes appear in the list.
 When entering text in a filter text box, any list entry's whose corresponding column content contains the
text box entry will be considered a match. For example, if the Message Type Id filter entry is XML, then
message types with IDs of XML In or Incoming XML will match.
 To not include a filter text box in the filter, leave the box blank.
 To not include a filter list box in the filter, leave the list box blank or select <ALL>.
 The filter can be cleared by clicking the Reset button on the page's toolbar.

Refreshing Page Content

Many pages include a Refresh button in the page's toolbar. Click the Refresh button to update the page
contents with the latest data in the system.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 11
Chapter 2

Managing Security

The EI website uses Windows authentication to allow access to the system. Security groups can be created, to
which Windows Active Directory (AD) users and groups can be associated, as well as specific application
privileges.
All users who require access to the application must be defined in the Windows AD and assigned to an EI
security group.
Initial Security Groups
By default, when EI is first installed, the following security groups are defined.
View
Users in this group can view all pages.
Admin
Users in this group can perform all possible actions (all privileges) in the EI website.
Privileges
The EI system has the following privileges that can be assigned to security groups. These privileges allow for
different access within the EI system.
PortalBase_View
Can view pages.
PortalBase_Security_Config
Can create, modify, and manage security groups and users.
PortalBase_AppSettings_Config
Can create and modify plant configuration settings.
WEI_MessageService_Config
Can create and modify Message Services.
WEI_Message_Send
Can send paused messages to external systems.
WEI_Message_Modify
Can archive, modify, and re-process messages.
WEI_Location_Modify
Can create, modify, and disable message locations.
WEI_Location_ChangeStatus
Can turn locations On and Off.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 12
 AVEVA™ Enterprise Integration User Guide
Chapter 2 – Managing Security

WEI_General_Config
Can add or modify location groups (systems), message types, and message categories.

Viewing Security Groups

 On the Configuration menu, click Manage Security Groups.
The Manage Security Groups page appears.

Security Management Actions and Privileges Required

The table below shows the list of privileges required for the actions available on the Security Group pages.

Action Privileges

Create New PortalBase_Security_Config

Add PortalBase_Security_Config

Delete PortalBase_Security_Config

View PortalBase_View, PortalBase_Security_Config

Filtering Security Groups

You can filter the security groups listed on the Manage Security Groups page or search for a specific group.
 In the Group box, enter the security group ID or a portion of the ID of the group or groups that you are
searching for.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 13
 AVEVA™ Enterprise Integration User Guide
Chapter 2 – Managing Security

Adding a Security Group

1. On the Manage Security Groups page toolbar, click New.
The Security Group Details page appears.

2. Enter the properties described below.

Security Group ID
A unique ID for the security group.
Description
A description of the security group.
3. Click Save.
To add a Windows user or group to the security group
 Click New above the Members grid.
To remove a Windows user or group from the security group
1. In the Members grid, click the Delete button of the user or group to be deleted.
2. Click OK on the confirmation prompt.
To add a privilege to the security group
 Click New above the Privileges grid.
To remove a privilege from the security group
1. In the Privileges grid, click the Delete button of the privilege to be deleted.
2. Click OK on the confirmation prompt.
To return to the Manage Security Groups page
 On the page's toolbar, click the Listing button.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 14
 AVEVA™ Enterprise Integration User Guide
Chapter 2 – Managing Security

Editing a Security Group

1. On the Manage Security Groups page, click the group ID of the security group to be edited.
The Security Group Details page appears.
2. Make changes to the user or group members and privileges as needed.
3. On the page’s toolbar, click Save.

Deleting a Security Group

1. On the Manage Security Groups page, click the group ID of the security group to be deleted.
The Security Group Details page appears.
2. On the page’s toolbar, click Delete.
3. Click OK on the confirmation prompt.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 15
Chapter 3

Managing Location Types

Any number of location types can be added. Each location type includes details about the Send-Receive Class
that will be used to process the message that is associated with a particular location.

Viewing Location Types

 On the Configuration menu, click Messaging Configuration and then click Manage Location Types.
The Manage Location Types page appears.

Location Type Actions and Privileges Required

The table below shows the list of privileges required for the actions available on the Location Type pages.

Actions Privileges

Add WEI_General_Config

Edit WEI_General_Config

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 16
 AVEVA™ Enterprise Integration User Guide
Chapter 3 – Managing Location Types

Actions Privileges

Delete WEI_General_Config

Update WEI_General_Config

Refresh PortalBase_View

Adding a Location Type

1. On the Manage Location Types page toolbar, click Add.
The location type properties appear.

2. Enter the properties.

Location Type Id
A unique ID for the location type.
Description
A description of the location type.
Send Receive Class
This is a custom plug-in that must implement EI interfaces. For more information, see Plug-In Development
on page 92.
3. To create the location type, click the Add button below the properties.

Editing a Location Type

1. On the Manage Location Types page, click the Edit button of the location type to be edited.
The Description and Send Receive Class columns become available for editing.

2. Change the location type properties as needed.

3. To save the changes, click Update.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 17
 AVEVA™ Enterprise Integration User Guide
Chapter 3 – Managing Location Types

Deleting a Location Type

1. On the Manage Location Types page, click the Delete button of the location type to be deleted.
2. On the confirmation prompt, click OK.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 18
Chapter 4

Managing Location Groups

Location groups are used to associate message locations with each other. Any number of location groups can be
added.

Viewing Location Groups

 On the Configuration menu, click Messaging Configuration and then click Manage Location Groups.
The Manage Location Groups page appears.

Location Group Actions and Privileges Required

The table below shows the list of privileges required for the actions available on the Location Group pages.

Actions Privileges

Add WEI_General_Config

Edit WEI_General_Config

Delete WEI_General_Config

Update WEI_General_Config

Refresh PortalBase_View

Filtering Location Groups

You can filter the message types on the Manage Location Groups page or search for a specific type using the
following filter properties.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 19
 AVEVA™ Enterprise Integration User Guide
Chapter 4 – Managing Location Groups

Location Group Id
Filter for groups with an ID matching any part of the entry in this box.
Description
Filter for groups with a description matching any part of the entry in this box

Adding a Location Group

1. On the Manage Location Groups page toolbar, click Add.
The location group properties appear.

2. Enter the properties.

Location Group
A unique ID for the location group.
Description
A description of the location group.
3. To create the location group, click the Add button below the properties

Editing a Location Group

A location group’s description can be edited.
1. On the Manage Location Groups page, click the Edit button of the location group to be edited.
The Description column becomes available for editing.

2. Change the location group description as needed.

3. To save the changes, click Update.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 20
 AVEVA™ Enterprise Integration User Guide
Chapter 4 – Managing Location Groups

Deleting a Location Group

1. On the Manage Location Groups page, click the Delete button of the location group to be deleted.
2. On the confirmation prompt, click OK.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 21
Chapter 5

Managing Message Types

Message types are used to categorize different formats of messages being processed. Also, in some cases, a
message type is used to determine how EI should react with the messages. For example, message type
properties can be used to specify that message content be appended to XML or CSV type messages.
The Manage Message Types page, shown below, lists each message type that you have defined. Each message
type created is first defined by two parameters: Data Type and Has Header Row. The following basic Data Types
are available: CSV, FLAT, PIPE, TABBED, and XML. Has Header Row is set to True or False and is used only for
CSV, PIPE, and TABBED data types.
The details and summary expression of each message type can also be viewed and edited. The summary
expression associated with each message type is used to extract information from within the message structure.

CSV Data Type

CSV data files contain data in table-structured format that is comma-delimited:
Material,Quantity,Unit
Dough,10,lb
Cheese,3,lb
Pepperoni,100,each
Flat File Data Type
Flat File data files are generally an unstructured data format for which data is found with positional coordinates:
Work Order Bom Ingredients – Bom Item 1
Material:Dough
Quantity:10
Unit:lb

Pipe-Delimited Data Type

Pipe-delimited data files contain data in table-structured format that is pipe-delimited:
Material|Quantity|Unit
Dough|10|lb

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 22
 AVEVA™ Enterprise Integration User Guide
Chapter 5 – Managing Message Types

Cheese|3|lb
Pepperoni|100|each
Tab-Delimited Data Type
Tab-delimited data files contain data in table-structured format that is tab-delimited:
Material Quantity Unit
Dough 10 lb
Cheese 3 lb
Pepperoni 100 each

XML Data Type

XML data files contain data in a structured XML format:
<BomItem1Data>
<Material>Dough</Material>
<Quantity>10</Quantity>
<Unit>lb</Unit>
</BomItem1Data>

Viewing Message Types

 On the Configuration menu, click Messaging Configuration and then click Manage Message Types.
The Manage Message Types page appears.

Message Type Actions and Privileges Required

The table below shows the list of privileges required for the actions available on the Message Type pages.

Actions Privileges

Create New WEI_General_Config

Edit WEI_General_Config

Delete WEI_General_Config

Save WEI_General_Config

Refresh PortalBase_View

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 23
 AVEVA™ Enterprise Integration User Guide
Chapter 5 – Managing Message Types

Filtering Message Types

You can filter the message types on the Manage Message Types page or search for a specific type using the
following filter properties.
Message Type ID
Filter for message types with an ID matching any part of the entry in this box.
Data Type
Filter for message types by type: XML, FLAT, CSV, Tab Delimited, and Pipe Delimited.
Has Header Row
Filter message types on whether they have a header row.

Adding a Message Type

1. On the Manage Message Types page toolbar, click Create New.
The message type details page appears.

2. Enter the properties described below.

Message Type Id
A unique ID for the message type.
Description
A description of the message type.
Data Type
The message file format: XML, FLAT, CSV, Tab Delimited, or Pipe Delimited.
Has Header Row
Determines if messages of this message type will have a header row.
This is applicable to CSV, Tab Delimited, and Pipe Delimited types only. This property is used when extracting
a summary expression or when appending message structures into an outbound Folder location type.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 24
 AVEVA™ Enterprise Integration User Guide
Chapter 5 – Managing Message Types

Summary Expression
Used to extract important data from a Message Structure. This property is dependent on the Data Type and
Has Header Row properties.
o If Data Type is XML, an XLT expression is entered here.
o If Data Type is FLAT, CSV, Tab Delimited, or Pipe Delimited, a simple text file format is entered.
For more information, see Summary Expressions on page 25.
3. Click Save.
4. To create another message type while you are still on the message type details page, click Create New.

Editing a Message Type

1. On the Manage Message Types page, click the ID link of the message type to be edited.
The message type details page appears.
2. Change the message type properties as needed.
3. To save the changes, click Save.

Deleting a Message Type

1. On the Manage Message Types page, click the Delete button of the message type to be deleted.
2. On the confirmation prompt, click OK.

Summary Expressions
Summary expressions are optional but can be used to extract key information from the file or message being
processed to display it in a message listing and on the details of particular messages. For example, an expression
could be written to extract the work order number, item to produce, and entity to run on from an XML file of
work orders. This allows the key information to be clearly visible when troubleshooting which work order files
were processed successfully versus those that might have failed due to an error.
The following topics describe how summary expressions are written for each of the message types.

Summary Expressions for XML Message Types

Summary expressions for XML are written using XSLT expressions. For example:
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"
xmlns="http://www.w3.org/1999/xhtml">
<xsl:template match="/">
<xsl:value-of select="concat('WO:',//*[local-name() = 'ProductionRequestID'],'
Mat:',number(//*[local-name() = 'MaterialDefinitionID']), '"/>
</xsl:template>
</xsl:stylesheet>
The above expression extracts the order ID and material from a hypothetical XML file containing a
<ProductionRequestID> node and a <MaterialDefinitionID> node to display the contents in a summary like this:

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 25
 AVEVA™ Enterprise Integration User Guide
Chapter 5 – Managing Message Types

WO:0012848831, Mat:12029940
Any valid XSLT expression can be used to extract and combine textual summaries that EI will display. The details
and range of functionality for the XSLT language are outside of the scope of this document.

Summary Expressions for Flat File Message Types

Flat files contain positional data across columns and rows within the file. Summary expressions for flat files use
an expression as follows:
Mat:{0}, Type:{1}
5,18|66,20
Where:
 5 corresponds to the index (zero-based) in the file where the material name starts
 18 is the number of characters after the start location to read
 66 corresponds to the index (zero-based) where the material type can be found
 20 corresponds to the number of characters after the start location to read
The expression shown above extracts the material and type of material from a hypothetical file and displays the
contents in a summary like this:
Mat:Sugar, Type:Raw Ingredient

Summary Expressions for CSV, Pipe-Delimited, and Tab-Delimited

Message Types
Summary expressions for delimited files use expressions like the following CSV example:
Mat:{0}, Type:{1} 1:0|1:1
where
 1:0 is the second row in the file and 0 is the first field in the comma-separated list
 1:1 is the second row in the file and 1 is the second field in the comma-separated list
The expression shown above extracts the material and type of material from a hypothetical CSV file and displays
the contents in a summary list this:
Mat:Sugar, Type:Raw Ingredient
The next example would create a summary for each row in the file:
Materials:{0}, Types:{1}
:0|:1
The expression would produce the following type of result:
Materials:Sugar,Milk,Chocolate, Types:Raw Ingredient,Finished Product,Produced Material

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 26
Chapter 6

Managing Location Categories

Location categories provide another level of filtering when viewing messages and when managing locations. In
addition, they add a setting that controls whether users can turn any of the locations in a given category on or
off.

Viewing Location Categories

 On the Configuration menu, click Messaging Configuration and then click Manage Location Categories.
The Manage Location Categories page appears.

Location Category Actions and Privileges Required

The table below shows the list of privileges required for the actions available on the Location Category pages.

Action Privileges

Add WEI_General_Config

Edit WEI_General_Config

Delete WEI_General_Config

Update WEI_General_Config

Refresh PortalBase_View

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 27
 AVEVA™ Enterprise Integration User Guide
Chapter 6 – Managing Location Categories

Filtering Location Categories

You can filter the location categories on the Manage Location Categories page or search for a specific category
using the following filter properties.
Category ID
Filter on location categories with an ID matching any part of the entry in this box.
Description
Filter on the description or partial description of the entry in this box.

Adding a Location Category

1. On the Manage Location Categories page toolbar, click Add.
The location category properties appear.

2. Enter the properties.

Category Id
A unique ID for the location category.
Description
A description of the location category.
Display Position
The position at which the category should be displayed on the Message Summary page. Also, defines the
order in which messages are received and sent from and to locations.
3. To create the location category, click the Add button below the properties.

Editing a Location Category

1. On the Manage Location Categories page, click the Edit button of the location category to be edited.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 28
 AVEVA™ Enterprise Integration User Guide
Chapter 6 – Managing Location Categories

The Description, Display Position, and Allow Status User Toggle columns become available for editing.

2. Change the properties as needed.

If the Allow Status User Toggle property is set to True, users will be able to turn locations in this category
On and Off.
3. To save the changes, click Update.

Deleting a Location Category

1. On the Manage Location Categories page, click the Delete button of the location category to be deleted.
2. On the confirmation prompt, click OK.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 29
Chapter 7

Managing Message Services

Message services allow users to control the status of each service and the amount of time between executions
of the service.

Viewing Message Services

 On the Configuration menu, click Messaging Configuration and then click Manage Services.
The Manage Message Services page appears.

Message Service Actions and Privileges Required

The table below shows the list of privileges required for the actions available on the Message Service pages.

Action Privileges

Edit WEI_Processor_Config

Save WEI_Processor_Config

Refresh WEI_Processor_Config, PortalBase_View

Adding or Deleting a Message Service

Message services can be added or deleted using the EI Configurator utility. For information about this utility, see
the Enterprise Integration Installation Guide.

Editing a Message Service

1. On the Manage Message Services page, click the ID link of the message service to be edited.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 30
 AVEVA™ Enterprise Integration User Guide
Chapter 7 – Managing Message Services

The Message Service Details page appears.

2. Make changes to the following editable message service properties as needed.

Description
A description of the service.
Service Status
Click the Start/Stop button to change the status.
Sleep Time
The amount of time (in milliseconds) between each execution of the service.
3. To save the changes, click Save.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 31
Chapter 8

Managing Message Locations

Message locations provide a means of triggering an EI Service instance to act on something and pass that data
along to another type of location for further processing. In EI, message locations behave differently based on
their direction (Inbound or Outbound) and the location type they use (Folder, MSMQ, MESJobEnd, etc.).
Locations can be used to monitor file folders to pick up files and send their content to custom plug-in code
(CODE), where custom logic can process it further. Examples include importing complex production orders into
MES, executing a SQL query to obtain production summaries and create files from the SQL results, and importing
data into a Manufacturing Execution System (MES) table. Possible operations are described in Working with
Inbound Location Types on page 37 and Working with Outbound Location Types on page 44.

Viewing Message Locations

 On the Configuration menu, click Messaging Configuration and then click Manage Locations.
The Manage Message Locations page appears.

Message Location Actions and Privileges Required

The table below shows the list of privileges required for the actions available on the Message Location pages.

Action Privileges

Create New WEI_Location_Modify

Edit WEI_Location_Modify

Delete WEI_Location_Modify

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 32
 AVEVA™ Enterprise Integration User Guide
Chapter 8 – Managing Message Locations

Action Privileges

Save WEI_Location_Modify

Change Location Status WEI_Location_ChangeStatus

Refresh WEI_Location_Modify, PortalBase_View

Filtering Message Locations

You can filter the message locations on the Manage Message Locations page or search for a specific message
location using the following filter properties.
Direction
Filter for message locations with the selected direction.
Category
Filter for message locations with the selected category.
Location Type
Filter for message locations with the selected location type.
Group
Filter for message locations with the selected group.
Status
Filter for message locations with the selected status.
Location ID
Filter for message locations whose location ID match any part of the filter entry.

Setting the Status of Selected Message Locations

You can set the status of one or more messages from the Manage Message Locations page, or set the status of
the message currently displayed on the Message Location Details page.
To change the status of one or more messages on the Manage Message Locations page
1. On the Manage Message Locations page, select the check boxes of the message locations whose status you
want to change.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 33
 AVEVA™ Enterprise Integration User Guide
Chapter 8 – Managing Message Locations

2. On the toolbar, click one of the following buttons.

Turn On
Turn the locations On to have their associated EI service attempt to process messages sent to them.
Disable
Disable the locations so that their associated EI service does not process messages sent to them but does
queue them in the MessageHub.
Turn Off
Turn the locations Off so that messages sent to them are refused by their associated EI service but can be
triggered manually through the user interface. The refused messages are not queued in the MessageHub.
To change the status of an existing message that has been opened on the Message Location Details page
 On the Status section of the page, click the Turn On, Disable, or Turn Off button.

Note: Message locations can also be hidden so they do not show in the user interface. This setting is currently
only available through the database by updating the Hidden column of the MessageLocation table.

Adding Message Locations

1. On the Manage Message Location page toolbar, click New.
The Message Location Details page appears.

2. Enter the properties described in Message Location Properties on page 34.

3. To create the message location, click Save.

Message Location Properties

Location
The unique ID and specifics about a location’s behavior.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 34
 AVEVA™ Enterprise Integration User Guide
Chapter 8 – Managing Message Locations

Location Id
Required. A unique ID for the message location.
Direction
Used to define if a message location is an inbound (IN) or outbound (OUT) location.
– An IN location is one for which messages are received and entered into the EI system.
– An OUT location is one from which messages already in the EI system are sent to a destination (for
example, a folder on disk) by the message service.
Location Type
Required. The behavior of the location. Both Direction and Location Type define what the location does
when processed by the associated EI service.
See Working with Inbound Location Types on page 37, Working with Outbound Location Types on page
44, and Managing Location Types on page 16.
Processing Priority
An integer value that specifies the priority (0 = highest) for this location. The EI message service
processes locations with higher priorities first. Locations with the same priorities are processed in a
round robin fashion.
Grouping
Grouping properties allow a location to be grouped with other similar message locations. The groupings
section serves as a means of categorizing locations by a user-defined type (with implied data type) to
represent the message structures contained within a user-defined category and user-defined group. The EI
service instance designated to process the location is also configured in this section.
Message Service
Required. Defines which message service will run the message location.
The entry is populated by the message services defined on the Manage Message Services page.
EI_Default is the default service created during the installation configuration.
Message Type
Required. A user-defined message type with an implied Data Type, such as XML, FLAT, CSV,
Tab-Delimited, or Pipe-Delimited.
For CSV, Tab-Delimited, and Pipe-Delimited, the message type also indicates whether the message
contents contain a header row.
Message Category
Required. Defines with which Message Category the message location is associated.
The entry is populated by the Message Categories defined on the Manage Message Categories page.
Group
Required. Is used to group message locations (e.g., SAP).
Populated by the location groups defined on the Manage Message Location Group page.
Configuration
Configuration properties allow you to control the service’s retry and batch sizes and how many days to keep
history within EI on this location.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 35
 AVEVA™ Enterprise Integration User Guide
Chapter 8 – Managing Message Locations

Retry Limit
The number of retries allowed before an error is logged.
Retry Delay (ms)
The time (in milliseconds) between each retry after a failure to receive a message from this location or
to send a message to this location.
Current Retries
Read-only property showing the current retry state (or 0) for the location. Applies only when the service
is running.
Purge After (days)
The number of days that must pass before a message location’s history is purged from the database. For
example, 365 would indicate keeping 365 days of history and purging history entries older than that.
Batch Size
Required. The number of files to be processed at one time from this location. This is only applicable for
Inbound locations.
Context
The properties that appear here vary based on the Direction and Location Type entries.
For information about these properties, see the location type topics in Working with Inbound Location Types
on page 37 and Working with Outbound Location Types on page 44. Also see Managing Location Types on
page 16.

Editing Message Locations

1. On the Manage Message Locations page, click the ID link of the message location to be edited.
The Message Location Details page appears.

2. Change the message location properties as needed.

3. To save the changes, click Save.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 36
 AVEVA™ Enterprise Integration User Guide
Chapter 8 – Managing Message Locations

Deleting Message Locations

1. On the Manage Message Locations page, click the ID link of the message location to be deleted.
The Message Location Details page appears.
2. Click Delete.
3. On the confirmation prompt, click OK.

Working with Inbound Location Types

Inbound locations are used to monitor and trigger based on an event. The associated EI service monitors these
locations periodically (based on the service’s Sleep Time Milliseconds configuration). If a trigger condition is met,
the contents of the message is stored in the EI MessageHub.
Typical scenarios for inbound locations are to monitor folders for incoming files and send the results of that file
to an outbound location for further processing. Other common scenarios are to run scheduled queries to pick up
data and send the results to an outbound processor.
There are various types of inbound locations to suite various needs. The following topics detail these location
types.

Schedules for Inbound Locations

All inbound locations are capable of being configured to run based on a predefined schedule. Schedules are
useful to limit when the service attempts to process a location. For example, a Folder location without a
schedule will trigger whenever a file matching the Label Format is dropped into the folder identified in the URI
field (the service monitors the folder every Sleep Time Milliseconds interval). Using a schedule will limit the
associated EI service to monitor that folder only during the schedule run time.
All scheduled locations have the following properties.
Is Scheduled
Selecting this option allows for picking a type of schedule. Clearing this option hides the schedule controls
and, if saved, the location becomes event-based, relying solely on the associated service’s Sleep Time
Milliseconds to determine when processing will occur.
Type of Schedule
The available schedule types are:
Daily
The location is processed every day at a specific time.
Weekday
The location processed during weekdays (Monday through Friday) at a specific time.
Weekly
The location is processed on a specific day of the week at a specific time.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 37
 AVEVA™ Enterprise Integration User Guide
Chapter 8 – Managing Message Locations

Time Interval
The location is processed daily between a start and end time. When EI detects that the current time falls
within the start and end times, it will process for each Interval Seconds configured. For example: Process
the location between 8 am to 10 am daily and verify every 3600 interval seconds.

Type CODE
Note: Code locations require a professional license to use them.
Code locations are used to call custom EI plug-ins. The inbound plug-in must implement the ReceiveMessage of
IMessageSendReceive. These locations can be used for any custom processing and should return a result set to
be stored into MessageHub upon successful processing. The result set can then be further processed by
outbound locations.
On the Message Location Details page, the following Context properties are available for these location types.
Assembly
The fully qualified assembly name containing a class that implements ReceiveMessage.
Class
The fully qualified class name (AssemblyName.ClassName) containing the implementation of
ReceiveMessage.
Is Scheduled, Type of Schedule
See Schedules for Inbound Locations on page 37.

Type DIRECT
Direct locations are intended as placeholder-type locations. That is, defining a Direct location does not cause any
processing to occur but is intended as a placeholder to allow for tying in transfer destinations to pass data along
to a downstream, outbound location.
Direct locations expect an external system to populate data for them in MessageHub. An example of a direct
location could be an external warehousing system that periodically collects new stock and sends those stock
records to EI by inserting them directly into the EI MessageHub SQL table. The stock records could then be
passed to an outbound CODE plug-in for further processing.
On the Message Location Details page, the following Context properties are available for these location types.
Assembly
The fully qualified assembly name containing a class that implements ReceiveMessage.
Class
The fully qualified class name (AssemblyName.ClassName) containing the implementation of
ReceiveMessage.
Is Scheduled, Type of Schedule
See Schedules for Inbound Locations on page 37.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 38
 AVEVA™ Enterprise Integration User Guide
Chapter 8 – Managing Message Locations

Type FOLDER
Inbound Folder locations are used to monitor a folder for specific file types and to take those files and store
their content into MessageHub where they can then be transferred to an outbound location for further
processing.
When EI detects a file matching the search criteria, it removes that file from the folder and stores its content in
MessageHub. When configuring Folder locations, it is important to pick a message type that uses the same file
format so that summary expressions can be tied to all Folder locations within that message type grouping. For
example, Folders with a Label Format of *.XML should use message types with a data type of XML.
On the Message Location Details page, the following Context properties are available for these location types.
URI
Specifies a folder or network share where the service can access files. For example: F:\Data\WorkOrders.
Label Format
Identifies what files to look for.
Wildcards can be used. For example: *.xml or *.txt.
Is Scheduled, Type of Schedule
See Schedules for Inbound Locations on page 37.

Type MESJobEnd
The MESJobEnd location type uses a polling system to monitor when jobs on MES entities end. If a job has ended
(that is, has the status Complete), a query or stored procedure is triggered to run. This location relies on the MES
middleware to obtain a connection to the MES database. It also relies on user credentials provided in the EI
service’s config file.
EI exposes certain parameters that can be used by the query or stored procedure to gather pertinent
information regarding the job that just ended. These parameters are:
@ent_id
The entity ID on which a job just ended.
@last_wo_id
The work order ID of the job that just ended on the entity.
@last_oper_id
The operation ID of the job that just ended on the entity.
@last_seq_no
Sequential number of the job that just ended on this entity.
@job_pos
The job position on this entity for the job that just ended.
@user_id
ID of the user who ended the job.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 39
 AVEVA™ Enterprise Integration User Guide
Chapter 8 – Managing Message Locations

It is important to note that EI stores a last executed UTC date/time for each entity being monitored. Each time
the service wakes up (or the configured schedule time has occurred), it queries the MES Job table for each entity
being monitored. If completed jobs have been found since the last wake-up time, EI loads the available
@parameters and executes the associated query or stored procedure. The last executed UTC date/time is
updated to indicate the last time slice verified in the MES Job table even when no job activity has been detected.
This trigger type runs on a polling system and will pick up any job end records each time it checks. This means
that linked jobs will get picked up on the polling once they are marked Complete. Using linked jobs in MES will
not enforce an order of operation.
Note: There is a potential for querying larger amounts of job data from the MES if the EI service is off for
extended periods or the location has been off or disabled for a long period of time. This is because EI must
internally query the MES for job activity since the last executed UTC date/time. If needed, the location’s
properties should be edited to reduce the <LastExecuteUTCDateTime>. These properties can be found in the
MessageLocationProperty table.
On the Message Location Details page, the following Context properties are available for these location types.
Entity to Monitor
Lists all entities being monitored for job end activity.
Clicking the Add Entity button displays a list of entities to choose from that can run jobs.
SQL or SP
A SQL query or stored procedure that will be executed on the MES database and accessible through the MES
middleware configuration.
The query (or stored procedure) can make use of the dynamic parameters indicated above. For example: get
all item_prod records produced by @ent_id when running @last_wo_id, @last_oper_id and @last_seq_no.
Is Scheduled, Type of Schedule
See Schedules for Inbound Locations on page 37.

Type MESShiftEnd
The MESShiftEnd location type is used to monitor shifts on MES entities and trigger a query or stored procedure
to run each time a shift has ended. This location relies on the MES middleware to obtain a connection to the
MES database. It also relies on user credentials provided in the EI service config file.
EI exposes certain parameters that can be used by the query or stored procedure to gather pertinent
information regarding the shift that just ended. These parameters are:
@ent_id
The entity ID on which a shift change occurred.
@last_shift_start_time
The UTC start time of the shift that just ended on the entity.
@last_shift_id
The ID of the shift that just ended on the entity.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 40
 AVEVA™ Enterprise Integration User Guide
Chapter 8 – Managing Message Locations

It is important to note that EI stores a last executed UTC date/time for each entity being monitored. Each time
the service wakes up (or the configured schedule time has occurred), it queries the MES Shift_History table for
each entity being monitored. If completed shifts have been found since the last wake-up time, EI loads the
available @parameters and executes the associated query or stored procedure. The last executed UTC date/time
is updated to indicate the last time slice verified in the MES Shift_History table even when no shift activity has
been detected.
Note: There is a potential for querying larger amounts of shift data from the MES database if the EI service is off
for extended periods or the location has been off or disabled for a long period of time. This is because EI must
internally query the MES for shift activity since the last executed UTC date/time. If needed, the location’s
properties should be edited to reduce the <LastExecuteUTCDateTime>. These properties can be found in the
MessageLocationProperty table.
On the Message Location Details page, the following Context properties are available for these location types.
Entity to Monitor
Lists all entities being monitored for shift end activity.
Clicking the Add Entity button displays a list of entities to choose from that can schedule shifts and any child
entities that could inherit a schedule from a parent entity.
SQL or SP
A SQL query or stored procedure that will be executed on the MES database and accessible through the MES
middleware configuration.
The query (or stored procedure) can make use of the dynamic parameters indicated above. For example: get
all item_prod records produced by @ent_id within the start/end date/times of @last_shift_id.
Is Scheduled, Type of Schedule
See Schedules for Inbound Locations on page 37.

Type MESTable
The inbound MESTable location type can be used to export table data from an MES database. The data to be
exported can be gathered by a query, stored procedure, or an MES API GetAll middleware call.
If the chosen method returns one or more rows, then the contents of that result set are stored in MessageHub
and available for downstream outbound message locations. As an alternative, the primary query, stored
procedure, or middleware call can be used as the trigger and a secondary query, stored procedure, or
middleware call used as the results to store in MessageHub. In either case, the executed query must return one
or more rows to trigger the location.
When using a middleware call, a list of MES tables is provided to select from and the table’s associated MES API
GetAll parameters are exposed. Basic filtering is also possible by using one or more of the parameters. If one or
more filters are provided, they are passed to the associated GetAll and executed through the middleware.
Note that this location relies on the MES middleware to obtain a connection to the MES database. It also relies
on user credentials provided in the EI service config file.
On the Message Location Details page, the following Context properties are available for these location types.
Primary MES Type
Allows for configuring SQL (query or stored procedure) or MES middleware.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 41
 AVEVA™ Enterprise Integration User Guide
Chapter 8 – Managing Message Locations

Use the results from the Primary SQL to pass to the destination location(s)
Selected by default. If selected, indicates that the results from the primary will be used as both the trigger
and the results to store in MessageHub. If not selected, the Secondary MES In Type properties appear.
Secondary MES In Type
If Use the results from the Primary SQL option is not selected, the secondary MES In Type can be used as
the data to store in MessageHub.
Query/SP
Appears if SQL is selected in the Primary MES In Type or Secondary MES In Type list.
Allows for entering a SQL query or stored procedure to be executed against the MES database for gathering
data to export.
To test the query or stored procedure entered here, click the Test button.
Table
Appears if Middleware is selected in the Primary MES In Type or Secondary MES In Type list.
Provides a list of all MES API classes containing a GetAll() method. The classes listed relate to a specific MES
table such as the Ent (entity) or Attr (attribute) table.
Parameters
Populates when Middleware is selected as the In Type and an MES API class is selected in the Table list.
The list of parameters provided by the GetAll() method selected. Basic filters can be provided and their
filtering functionality conforms to the specific GetAll() method.
Example: Backflush = 1 on table BOM Items would return all BOM items set to Backflush in the ERP.
Is Scheduled, Type of Schedule
See Schedules for Inbound Locations on page 37.

Type MSMQ
MSMQ locations are intended to work with Microsoft Message Queuing where EI can read messages from an
accessible queue and store the contents of that message in MessageHub for further downstream processing.
Typically, the queues accessed are Private queues but Public queues would also work.
On the Message Location Details page, the following Context properties are available for these location types.
Queue
The name of the MSMQ to monitor using Microsoft Direct Format Name Syntax.
For example, monitoring a queue called EIInboundOrders:
DIRECT=OS:.\PRIVATE$\EIInboundOrders DIRECT=OS:WOServer\PRIVATE$\EIInboundOrders
DIRECT=TCP:157.18.3.1\PRIVATE$\EIInboundOrders
Is Scheduled, Type of Schedule
See Schedules for Inbound Locations on page 37.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 42
 AVEVA™ Enterprise Integration User Guide
Chapter 8 – Managing Message Locations

Type SQLQuery
SQLQuery locations are intended for running a query or stored procedure on a Microsoft SQL Server database to
gather data to store in MessageHub and pass onto an outbound location. An example of this type of location
could be to query inventory on a remote proprietary database based on certain conditions (in a where clause)
and to pass that data to an outbound location for further processing.
The SQLQuery location’s context contains a Primary and optional Secondary query or stored procedure and
requires a Schedule configuration to limit how often the query or stored procedure is executed on the remote
database. EI will trigger the location to run if the primary query returns one or more rows and will use the
results of that query as the data to pass to outbound (destination) locations. If the query or stored procedure
returns 0 rows, then the location will not trigger.
The Secondary query or stored procedure can be used as the data pump (instead of the Primary) to pass data to
one or more outbound locations. For example, use the Primary to determine if the location should trigger and
use the Secondary as the data to collect and pass to an outbound location for processing.
Note: The account used in the connection strings should be set up with restricted security access to the
database to which EI is being connected. EI relies on SQL security to prevent malicious intent such as dropping
tables or databases. There is no restriction to what DML statements can be executed on the SQL database and
therefore these situations need to be prevented via security. If using Integrated Security for the SQL connection,
make sure that the EI service user account has permissions to execute the statements.
On the Message Location Details page, the following Context properties are available for these location types.
Primary SQL
Connection
An encrypted connection defined in the Connection Listing page.
To test the connection entered here, click Test.
Query/SP
A valid SQL query or stored procedure name.
To test the query or stored procedure, click Test. The results of the executed SQL are displayed in a
separate window.
Use the results from the Primary SQL to pass to the destination location(s)
If selected, use the results from the Primary SQL to pass to the destination locations. By default, this check
box is selected.
When selected, the Primary SQL is used as both the trigger and the data to pass to destination locations.
When cleared, the Primary SQL is used as the trigger and the data from the Secondary SQL is used to pass to
destination locations. The Secondary SQL properties are defined in the following property description.
If the Primary SQL returned rows, then use this SQL to pass data to the destination location(s)
Connection String
An encrypted connection is defined on the Connection Listing page.
To test the connection entered here, click the Test button.
Query/SP
A valid secondary SQL query or stored procedure name.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 43
 AVEVA™ Enterprise Integration User Guide
Chapter 8 – Managing Message Locations

To test the query or stored procedure entered here, click the Test button. The results of the executed
SQL will be displayed in a separate window.
Is Scheduled, Type of Schedule
Required. See Schedules for Inbound Locations on page 37.

Working with Outbound Location Types

Outbound locations are intended as processors of data collected and stored in the EI MessageHub from an
inbound location. Outbound locations are linked to Inbound locations via Message Transfer Requirements.
When the outbound location’s associated service processes the location, it gathers the data stored by the source
location specified on the transfer requirement.
Typical scenarios for outbound locations are to execute a plug-in (CODE) to process the contents of an XML file
received via an inbound Folder location. Another scenario would be to import data into MES database tables
from a source file (Folder location) into one or more outbound MESTable locations, such as creating work orders
by process, or importing item and item BOM data from a CSV file.
There are various types of outbound locations to suit various needs. The next topics detail these location types.

Type CODE
Note: Code locations require a professional license to use them.
CODE locations are used to call custom EI plug-ins. The outbound plug-in must implement the SendMessage of
IMessageSendReceive. These locations can be used for any custom type of processing.
On the Message Location Details page, the following Context properties are available for these location types.
Assembly
The fully qualified assembly name containing a class that implements ReceiveMessage.
Class
The fully qualified class name (AssemblyName.ClassName) containing the implementation of
ReceiveMessage.
PreSend Assembly
Optional. If used, both the pre-send assembly and class must be specified.
The fully qualified assembly name containing a class that implements IMessagePreSend.
Common use would be to modify the content (body of the message) or its label before a message is
processed.
PreSend Class
Optional. If used, both the pre-send assembly and class must be specified.
The fully qualified class name (AssemblyName.ClassName) containing the implementation of
IMessagePreSend.
Common use would be to modify the content (body of the message) or its label before a message is
processed.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 44
 AVEVA™ Enterprise Integration User Guide
Chapter 8 – Managing Message Locations

Type FOLDER
Outbound Folder locations are used to store the contents of an inbound location’s MessageHub body to a file.
By default, the location creates new, unique files every time a message transfer moves data from an inbound
location to the outbound location.
Outbound Folder locations can be configured to create new files, overwrite files, append to existing files, or
simply return an error if the file exists. When configuring outbound Folder locations, it is important to select a
message type that uses the same file format not only for summary expressions but it becomes necessary for
using file append functionality.
When appending message content to a file, EI uses the message type Data Type to determine how to process an
append operation. For example, a Data Type of XML will tell EI to expect an XML structure and to take all of the
contents of that XML message except for the root node and append that to an existing file. Similarly, a Data Type
of CSV will tell EI to append the full content of the file. Or, if the message type was defined as CSV with a header
row, then EI would take the second row onward for its append operation.
On the Message Location Details page, the following Context properties are available for these location types.
URI
Specifies a folder or network share where the service can access files. For example: F:\Data\WorkOrders.
Label Format
Identifies either the file extension when using File Option – Create Unique or a specific file name when using
any of the other File Options.
For example: *.xml or *.txt, or Orders.csv.
PreSend Assembly
Optional. If used, both the pre-send assembly and class must be specified.
The fully qualified assembly name containing a class that implements IMessagePreSend.
Common use would be to modify the content (body of the message) or its label before a message is
processed
PreSend Class
Optional. If used, both the pre-send assembly and class must be specified.
The fully qualified class name (AssemblyName.ClassName) containing the implementation of
IMessagePreSend.
Common use would be to modify the content (body of the message) or its label before a message is
processed.
File Options
Create Unique
Creates a unique file with an extension as provided by Label Format and stores this file at the location
specified in the URI.
Files will be unique even when re-processing the same message. EI will append a unique number to the
file as Orders_1.xml or Orders_56.xml.
Overwrite
EI overwrites the file with file name = Label Format at the location specified in the URI.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 45
 AVEVA™ Enterprise Integration User Guide
Chapter 8 – Managing Message Locations

This location expects a valid file name to be entered in the Label Format field. Example: Orders.txt.
Append
EI appends the message contents to the file with file name = Label Format at the location specified in
the URI.
This location expects a valid file name to be entered in the Label Format field. Example: Orders.txt.
If Append is selected, there are the following additional options.
– Max File Size (MB): On each append operation, EI will verify the current file size + estimated file size
of the message content to be appended. If the size projected is >= Max File Size, then the If Max
Exceeded rule is executed
– If Max Exceeded: Create New: EI creates a new file using Label Format and appends the current
date/time stamp. Example: Orders20150402091233202.txt (YYYYMMDDHHMMSSms#).
– If Max Exceeded: Log Error: If EI projects that the append operation will exceed the Max File Size,
then an error is logged and nothing is appended to the file.
Return An Error
EI either creates the file with file name = Label Format at the location specified in the URI or returns an
error if the file name already exists.
This location expects a valid file name to be entered in the Label Format field. Example: Orders.txt.

Type MESTable
Outbound MESTable locations are intended for importing data into an MES database using the MES API. These
locations are typically linked via Message Transfer Requirement to an inbound Folder location or SQLQuery
location. The data gathered from the file or query can then be mapped to the parameters of one or more MES
database tables. This location relies on the MES middleware to obtain a connection to the MES database. It also
relies on user credentials provided in the EI service config file.
Several tables are available for selection. Upon selection, the table’s API parameters (Field Names) are
displayed. Bolded Field Names are required and must be mapped or defaulted to a value. Required fields and
some others (depending on API) are displayed with the Included option check box selected, indicating that the
content fields need to be mapped to them. Other fields are optional but do require a default value, which EI
provides (e.g., Backflush = 0 on BOM items). Selecting the Included check box will cause these fields to require a
mapping.
EI uses the If Row Exists options to determine what actions to take if the data already exists in the MES
database. The If Row Exists functionality is dependent on the table selected and the table’s alternate key.
It is important to note that when importing data from a mapped data source (Folder or SQLQuery), EI will import
each source row into the associated MES database table and track the overall success of that batch operation.
That overall success is what determines the location’s MessageHub Status when viewing from the Message
Listing and Detail.
For example, when importing 10 rows into Table Attribute:
 Message Status = Success if all 10 rows were imported without error.
 Message Status = Partial Success if 5 rows imported without error and 5 rows existed already and the If Row
Exists option was set to Treat as Error.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 46
 AVEVA™ Enterprise Integration User Guide
Chapter 8 – Managing Message Locations

 Message Status = Error on fatal errors or all 10 rows existed already and the If Row Exists option was set to
Treat as Error.
EI uses the Message Transfer Requirement’s Exec Seq No parameter to determine the order to import data into
tables when mapping a single file or query to multiple outbound MESTable locations. It is important to sequence
each of these outbound MESTable locations in the proper order to satisfy the MES database’s referential
integrity.
On the Message Location Details page, the following Context properties are available for these location types.
Table
Identifies the table in the MES database in which to import the data.
If Row Exists
Options that determine what to do if the data being imported already exists in the MES database.
Ignore
EI queries the table based on the selected table’s key. If the row already exists, then EI does nothing.
Otherwise, the row is added.
Update
EI queries the table based on the selected table’s key. If the row already exists, then EI updates it.
Otherwise, the row is added.
Treat As Error
EI queries the table based on the selected table’s key. If the row already exists, the message status
potentially goes to Partial Success. Otherwise, the row is added.
Delete
EI queries the table based on the selected table’s key. If the row already exists, it is deleted.
Ignore and Treat as Success
Ignore the imported data and display the status as success (provided all rows are successful).
Parameters
The columns of the parameter table are described below. For information about the parameters associated
with MES API methods, see the Wonderware MES Stateless API Reference help.
Field Name
A list of all parameters associated to the table. These are not necessarily table columns but a
combination of those and the associated API calls to perform Add, Update, or Delete functionality.
Included
When selected, indicates that the Field will be found in the imported data. Fields with the Included
option check box selected require the user to map the source location to these Fields. Mappings are
created after the outbound MESTable has been saved. For more information, see Mappings on page 53.
Default
A default value can be entered that will then be used as the value for that Field when EI makes MES API
calls.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 47
 AVEVA™ Enterprise Integration User Guide
Chapter 8 – Managing Message Locations

Type MSMQ
MSMQ locations are intended to work with Microsoft Message Queuing where EI can write messages to an
accessible queue. Typically, the queues accessed are Private queues but Public queues can also be used,
provided the necessary security access has been considered.
On the Message Location Details page, the following Context properties are available for these location types.
Queue
The name of the MSMQ to monitor using Microsoft Direct Format Name Syntax.
For example, monitoring a queue called ProductionData:
DIRECT=OS:.\PRIVATE$\ProductionData DIRECT=OS:WOServer\PRIVATE$\ProductionData
DIRECT=TCP:157.18.3.1\PRIVATE$\ProductionData
PreSend Assembly
Optional. If used, both the pre-send assembly and class must be specified.
The fully qualified assembly name containing a class that implements IMessagePreSend.
A common use would be to modify the content (body of the message) or its label before a message is
processed.
PreSend Class
Optional. If used, both the pre-send assembly and class must be specified.
The fully qualified class name (AssemblyName.ClassName) containing the implementation of
IMessagePreSend.
A common use would be to modify the content (body of the message) or its label before a message is
processed.

Type SQLQuery
Outbound SQLQuery locations are intended for running a query or stored procedure on a SQL Server database.
An example of this type of location is executing a stored procedure on a production database after instructions
are received from the inbound location.
Note: The account used in the connection strings should be set up with restricted security access to the
database to which EI is being connected. EI relies on SQL security to prevent malicious activity such as dropping
tables or databases. There is no restriction to what DML statements can be executed on the SQL database and
therefore these situations need to be prevented via security. If using Integrated Security for the SQL connection,
make sure that the EI service user account has permissions to execute the statements.
On the Message Location Details page, the following Context properties are available for these location types.
Connection
An encrypted connection defined in the Connection Listing page
To test the connection entered here, click the Test button.
Query/SP
A valid SQL query or stored procedure name.
To test the query or stored procedure entered here, click the Test button. The results of the executed SQL
are displayed in a separate window.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 48
 AVEVA™ Enterprise Integration User Guide
Chapter 8 – Managing Message Locations

Execute on Data
Used to set whether the outbound query should be run only once or for every row provided by the inbound
location.

Transfer Destinations
Transfer destinations define the transport or link between a source location (inbound) and a destination location
(outbound). A message transfer requirement can be defined for any inbound location and appears when editing
a location with a direction of IN.
There is no limit to how many outbound destination locations that can be configured against an inbound
location and in some cases (MESTable OUT), the processing sequence can be defined using the Exec Seq No field
to control the sequence of which outbound location processes the message content first.
Transfer destinations can also transform the message before passing it onto a destination location. These
transformations can be configured using XSLT or a plug-in to alter the message body before being processed by
the destination location.
When using plug-ins, a transfer can be aborted based on logic and the contents of the message can be
transformed from one format to another based on custom logic.
It is also possible to configure multiple abort and/or transform operations before a final message structure is
delivered to the destination location.

Adding Transfer Destination Locations

After an IN message location has been created and saved, on the message location's Message Location Details
page you can add an existing OUT message location as a transfer destination location.
To add a transfer destination location
1. On the Transfer Destination tab, click Add (on the right side of the grid).

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 49
 AVEVA™ Enterprise Integration User Guide
Chapter 8 – Managing Message Locations

The New Message Transfer Requirement dialog box appears.

2. Complete the following properties.

Destination Location ID
Select the destination.
Status
Select the initial status for the transfer.
3. To create the transfer destination location, click Add.

Editing a Transfer Destination Location's Transforms

Once a transfer destination location has been created and added to the Transfer Destination tab on the
Message Location Details page, you can add and edit its transforms.

To add or edit a transfer destination location's transforms

1. Click its Transform Details button.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 50
 AVEVA™ Enterprise Integration User Guide
Chapter 8 – Managing Message Locations

The Transform Details page appears.

2. To add a transform entry to the grid, click Add.

The transform entry is added to the grid. The Abort Transfer: Assembly and Class properties become
available for editing.
3. Select the Transform Class option and complete the corresponding properties.
None
Select this option to specify only the Abort Transfer properties.
Transfer
The following properties become available. Use them to specify the plug-in that performs transformation
processing of the received message before it is transferred. See IMessageTransform on page 93 for
information about this type of plug-in class.
Assembly
The assembly name for the transfer class. For example: WW.Messaging.
Class
The class name for the transfer class. For example: WW.Messaging.TransformClassName.
Parameters
Additional parameter values. The parameters are passed to the plug-in as a string value. The plug-in is
responsible for parsing out individual values.
XSLT
The following property becomes available.
XSLT
The XSLT expression that will transform the message.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 51
 AVEVA™ Enterprise Integration User Guide
Chapter 8 – Managing Message Locations

4. Optionally, complete the Abort Transfer properties for the plug-in that will perform abort processing of the
received message before it can be transferred to the specified OUT location.
See IMessageAbortTransfer on page 93 for more information about this type of plug-in class. These
properties can be left blank if there is no abort transfer plug-in configured.
Assembly
The assembly name for the abort transfer class. For example: WW.Messaging.
Class
The class name for the abort transfer class. For example: WW.Messaging.AbortClassName.
5. To save the transform entry with the current property settings, click Save on the page's toolbar.
Once a transform entry has been created, you can perform the following tasks with it from the Transfer
Destination tab.
Transform Order
You can apply multiple transfer operations to a single location. This helps avoid the need to copy code to specific
transfer classes. For example, the system might need to look up a piece of data and apply it to the message. This
has already been defined in a class. For this location, you might also need to modify the format of the message.
By applying two layers of transforms—and controlling the order of operations—you can do both without
modifying code.
To change a transform's order in the grid and thus its order of operation
 Select the entry and click the Move Up or Move Down button on the page's toolbar.
Deleting the Transform Entry
To delete the entry
 Click its Delete button.

Editing Transfer Destination Locations

Once a transfer destination location has been created and added to the Transfer Destination tab on the
Message Location Details page, several editing-related tasks can be performed with it.

To open the destination location on the Message Location Details page

 Click its Location Id link.
To enable or disable the transfer
 Click its Enable or Disable button.
To change the order of the entry in the transfer sequence
 Click its Up or Down button.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 52
 AVEVA™ Enterprise Integration User Guide
Chapter 8 – Managing Message Locations

Deleting Transfer Destination Locations

1. On the Message Location Details page, click the Delete button of the transfer destination on the Transfer
Destination tab grid to be deleted.
2. On the confirmation prompt, click OK.

Mappings
Mappings provide the ability to map a data source such as a file or SQL query result to an outbound MESTable
location. The mapping describes which elements from the source file signify rows and which elements within
those rows map to which parameter in the outbound MESTable’s field list.
The data to be mapped can be XML, CSV, pipe-delimited, or tab-delimited. Text templates are also possible.
Mapping functionality in EI allows messages to be transformed between two destinations: a column in
destination A can be mapped to move to a different name column in destination B. Similarly, with a delimited
text file, a value on index 0 of a file can be mapped to become the value on index 3 of a destination location.
On the Message Location Details page, the Mapping tab in OUT direction locations manages all the mappings
actions. See the figure below for an example of the Mapping tab.

Note that mappings requirements can only be added for locations that are already tied with a Message Transfer
Requirement.

Location Type Mappings

Mappings support several types of location type mappings. These types and their syntax are described in the
following topics.

Delimited Text Source

The source file for this mapping is a delimited text file.
Mapping entries for this type need to have a source value that represents the index (zero-based) of the column
to which they belong. See the table below for an example.

Source Destination

0
1
5

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 53
 AVEVA™ Enterprise Integration User Guide
Chapter 8 – Managing Message Locations

XML Attribute-Based Source

The source file for this mapping is an attribute-based XML document.
Mapping entries for this type need to have a source value that should be the attribute of each element that
represents a row that will be read from and mapped. See the table below for an example.

Source Destination

can_run_jobs
description
can_capture_util

XML Element-Based Source

The source file for this mapping is an element-based XML document.
Mapping entries for this type need to have a source value that should be the element within each XML node
that represents a row that will be read from and mapped. See the table below for an example.

Source Destination

can_run_jobs
description
can_capture_util

Database Table Source

The source for this mapping is data read from a database table.
Mapping entries for this type need to have a source value that should be the column name of the column to be
read from and mapped. See the table below for an example.

Source Destination

col_1
col_2
col_3

Flat Source
The source file for this mapping is a flat file.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 54
 AVEVA™ Enterprise Integration User Guide
Chapter 8 – Managing Message Locations

Mapping entries for this type need to have a source value that should be a pair of numerical values separated by
a comma. The first value is the index (zero-based) of where the system should start reading in the source file.
The second value is the number of characters that the system should read after the index. See the table below
for an example.

Source Destination

0,10
60,20
90,11

MES Table Source

The source for this mapping is a database table belonging to MES.
Mapping entries for this type need to have a source value that should be the column name of the MES table’s
column to be read from and mapped. See the table below for an example.

Source Destination

can_run_jobs
description
can_capture_util

Delimited Text Destination

The output of this mapping is a delimited text file.
Mapping entries for this type need to have a destination value that represents the index (zero- based) of the
column to which they belong. See the table below for an example.

Source Destination

1
2
3

XML Attribute-Based Destination

The output of this mapping is an attribute-based XML document.
Mapping entries for this type need to have a destination value that should be the attribute of each element that
represents a row that will be read from and mapped. See the table below for an example.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 55
 AVEVA™ Enterprise Integration User Guide
Chapter 8 – Managing Message Locations

Source Destination

can_run_jobs
description
can_capture_util

XML Element-Based Destination

The output of this mapping is an element-based XML document.
Mapping entries for this type need to have a destination value that should be the element within each XML
node that represents a row that will be read from and mapped. See the table below for an example.

Source Destination

can_run_jobs
description
can_capture_util

Text Template Destination

The output of this mapping will use a text template as a base.
Mapping entries for this type need to have a destination value that should be the string to be searched for in the
Template Format string option that will be substituted with the value of the source.
For example, consider the following scenario.
The source location file is of type delimited text without a header row and contains just two lines:
"Milk,Raw Material,Tank01" "Chocolate,Raw Material,Silo03"
Mapping entries have been mapped as follows:

Source Destination

0 item_id
1 item_type
2 location_name

The template format used is the following:

Material is: %%item_id%%, Item Type is:
%%item_type%%, currently Item is located in:
%%location_name%%
After mapping the output of this mapping would be the following:
Material is: Milk, Item Type is: Raw Material, currently Item is located in: Tank01
Material is: Chocolate, Item Type is: Raw Material, currently Item is located in: Silo03

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 56
 AVEVA™ Enterprise Integration User Guide
Chapter 8 – Managing Message Locations

Adding Mappings
Mappings can only be added for locations that are already tied with a Message Transfer Requirement.
1. On the Mapping tab on the Message Location Details page, click the Add button to the right of the grid.

The New Mappings Requirement dialog box appears.

2. Complete the property settings.

Source Location Id
ID of the source location for this mapping requirement.
Destination Location Id
Read-only. The ID of this location.
Source Location Type Mapping
The mapping type for the source location.
Destination Location Type Mapping
The mapping type for the destination location.
3. To create the mapping, click Add.

Editing Mappings
1. On the Mapping tab grid on the Message Location Details page, click the Mapping Details button of the
mapping to be edited.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 57
 AVEVA™ Enterprise Integration User Guide
Chapter 8 – Managing Message Locations

The Message Mapping Requirement Details page appears.

2. Change any source or destination option values, as needed, and add, edit, or delete any number of mapping
entries.
The mappings details are described below.
Delimiter Character
Read-only. Displays the delimiter character in the delimited text file to be used in this mapping, based on the
locations-configured message type.
Has Header Row
Determines whether the delimited text file involved has a header row.
Template Format
The template to be used in the flat file used in this mapping.
This template format will be applied to each record in the source input.
The template’s keywords to be substituted need to be enclosed in double percentage signs as shown below.
%%keyword%%
For example:
Material is: %%item_id%%, Item Type is:
%%item_type%%, currently Item is located in:
%%location_name%%
XML Element To Contain Rows
The name of the XML element that will represent a row of data.
XML Header
The header, if any, of the XML file used in this mapping.
Mapping Entry
Represents a single mapping entry. It is formed by a Source Column/Index/Element/Attribute, a Destination
Column/Index/Element/Attribute, and a Translation ID if any. For more information about translations, see
Managing Translations on page 68.
3. To save the changes, click Save.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 58
 AVEVA™ Enterprise Integration User Guide
Chapter 8 – Managing Message Locations

Deleting Mappings
1. On the Mapping tab grid on the Message Location Details page, click the Delete button of the mapping to
be deleted.
2. On the confirmation prompt, click OK.

Helper Functions
When Source Location is either XML Attribute-Based Source or XML Element-Based Source and output is MES
Table Destination to update data, there might be Helper Functions available to identify target rows.
When a Helper Function is available, a button appears in the ID column of the table:

Clicking the button displays the Helper Options panel.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 59
 AVEVA™ Enterprise Integration User Guide
Chapter 8 – Managing Message Locations

Entering the name of a template XML file placed in the server directory …/EI/Config/, the data-bearing
attributes and elements are displayed for selection to resolve the desired row key. (Values must resolve to
unique rows within the MESTable.)

Data elements from the XML template can be dragged to the appropriate parameters for the Helper Function.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 60
 AVEVA™ Enterprise Integration User Guide
Chapter 8 – Managing Message Locations

Once selected, the parameters are displayed in the Mapping Entries panel.

When the Source Location Type is MESTable and the Output Type is XML Attribute-Based or XML
Element-Based, Helper Functions allow the selection of row data from tables where a Helper Function is
available.

Clicking the Add Format Mapping button displays a new Mapping Entry Row. Clicking the Helper Function
button displays the Helper Options panel, where a Helper and source column can be selected.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 61
 AVEVA™ Enterprise Integration User Guide
Chapter 8 – Managing Message Locations

Columns are selected by dragging the desired column to the mapping input.

Once a column has been selected, a label is applied, which will appear in the Destination XML.

Upon closing the Helper Options panel, the Mapping Entries panel displays the output label and indicates the
source as the table key with the Helper Function button, indicating a Helper Function was used.

Post Actions
Post actions can be used to act on the process message status result of an outbound location. A post action can
be used to simply email a distribution list, informing recipients that a message failed. Or it can chain another
inbound location to run depending upon success or failure. Post actions can typically be defined on two different
message status results:

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 62
 AVEVA™ Enterprise Integration User Guide
Chapter 8 – Managing Message Locations

 Success
 Error
When the outbound location has a type of MESTable, then a third status is available to which to tie post actions:
 Partial Success
Partial Success occurs when a batch operation of insert/updates or deletes was partially processed successfully
but certain rows in the batch of records were marked as errors due to how the location was configured. For
example: If Row Exists = Treat as Error.

Adding Post Actions

On the Message Location Details page, the Post Actions tab in OUT direction locations allows you to manage all
the post actions functionality.

Note that post action requirements can only be added for locations that are already tied with a Message
Transfer Requirement.
To add post actions
1. Click the Edit button of the source location and status pair that will trigger the post action (i.e., the success
status or the error status).
The Post Action Details page appears.

2. Click Add.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 63
 AVEVA™ Enterprise Integration User Guide
Chapter 8 – Managing Message Locations

A post action is added to the grid.

3. Select a Post Action Type.

4. The post action type properties change depending on the selection. For information about them, see Post
Action Type Properties on page 64.
5. To save the post action, click Save.
6. To create additional post actions, click the Add button again.

Post Action Type Properties

Email
Emails can be sent depending on the resulting process status of an outbound message location. The email
recipients and SMTP server are defined in named distribution lists and each email post action must select one of
them.
The following properties are available to this Post Action type.
Distribution List
A list of saved email distribution lists, each of which contains the SMTP server to send mail through, a list of
email recipients, and an identifier to signify that EI is sending the email. See Managing Distribution Lists on
page 71.
Subject
The Subject for the email message.
Attachment
An optional file attachment to include with the email.
Note: This attachment must exist on an accessible drive or network share that the EI service resides on.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 64
 AVEVA™ Enterprise Integration User Guide
Chapter 8 – Managing Message Locations

Body
The text to include in the email body.
Include Message Body
When this option is selected, EI will send the message body of the processed message as content in the
email body. For example, this can be used to send the contents of a file that failed to process.
Copy to Folder
The Copy to Folder post action can be used to copy the message body to a file folder or network share.
The following property is available to this post action type.
File Path
A file folder or network share accessible by the EI service. The folder must also have Write permission
enabled for the service to create files.
Execute EXE
The Execute EXE post action can be used to run an executable depending on the status outcome of the location
being processed. The executable must not expose a UI and cannot expect user input.
The following context fields are available to this post action type.
Path
A file folder or network share accessible by the EI service.
File
A valid executable file to execute.
Note: Executables that provide a user interface, such as NotePad.exe or any executable expecting user
input, will not work. EI services are not expected to interact with the desktop, and desktop interaction for
Microsoft services in general is being deprecated by Microsoft in future Windows releases.
Context Parameters
Optional context parameters (command line parameters) to pass to the executable file. For example: 123,
"Order".
SQL Query
Depending on the status outcome of the location being processed, the SQL Query post action can be used to
trigger a query.
Connection
An encrypted connection defined on the Connection Listing page.
To test the connection entered here, click the Test button.
Query/SP
A valid SQL query or stored procedure name.
To test the query or stored procedure entered here, click the Test button. The results of the executed SQL
are displayed in a separate window.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 65
 AVEVA™ Enterprise Integration User Guide
Chapter 8 – Managing Message Locations

Chain EI Message Location

Chaining a message location allows for executing different locations based on the status of an outbound
location. Only locations with a Direction of IN can be chained. However, the IN location selected can have one or
more OUT locations tied in via Message Transfer Requirements. The result can be a logical chain of actions to
take upon success, partial success, and/or failure of a message process.
A Message Transfer Requirement is created between the outbound Location and the selected IN location after
saving. The resulting Message Transfer Requirement can then be edited to use typical transfer requirement
functionality such as data transformations, abort classes, and/or transform classes. In other words, the data can
be transformed before the EI service executes the next message location in a chain.
The following property is available to this post action type.
Location Id
A list of locations with a Direction of IN.
Once a location has been selected and the post action has been saved, the Edit Transfer button becomes
available. Click this button to open the Transform Details page for the selected location. On that page, you can
configure transformations and abort classes to occur before processing is passed onto the chained Inbound
location.
It is important to note that locations selected as Chained will not be processed by the EI service except when the
outbound location referencing it is processed and results in a status matching the Post Action status configured.
Locations that have been chained appear on the Message Location Detail page with a status warning as follows:

Editing Post Actions

1. On the Post Actions tab on the Message Location Details page, click the Edit button of the of the source
location and status pair that will trigger the post action (i.e., the success status or the error status).
The Post Action Details page appears.
2. Select the post action to be edited in the Listing grid.
3. Change the Type or any of the type properties.
4. To save the changes, click Save.

Deleting Post Actions

1. On the Post Actions tab on the Message Location Details page, click the Edit button of the of the source
location and status pair which post action is to be deleted (i.e., the success status or the error status).
The Post Action Details page appears.
2. Click the Delete button of the post action to delete.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 66
 AVEVA™ Enterprise Integration User Guide
Chapter 8 – Managing Message Locations

3. On the confirmation prompt, click OK.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 67
Chapter 9

Managing Translations

The EI Translations functionality is tightly coupled with the Mappings functionality. Translations allows the
contents of a message to be manipulated and values within messages to be substituted.
To open the Translations Listing page
 On the Configuration menu, click Messaging Configuration and then click Translations.

To filter the list of transactions by name

 In the Name box, enter the name or a portion of the name of the transaction or transactions that you are
searching for.
To add a translation set
1. On the Translation Listing page toolbar, click Create New.
The Translation Details page appears.

2. Specify a Translation Name and a Translation Description and click Save.

The Translation Entries grid appears.

3. To add a translation entry, click the Add Entry button above the grid.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 68
 AVEVA™ Enterprise Integration User Guide
Chapter 9 – Managing Translations

The translation entry properties appear.

4. Complete the Source Value and Destination Value properties.

The Source Value is the value that will be searched for in the message if a match is found. The Source Value
will be replaced with the Destination Value.
5. Click Add.
The translation entry is added to the grid.

6. Continue adding entries as needed.

7. To save the changes to the set, click Save.
To edit a translation set
1. On the Translation Listing page, click the Name link of the translation set to be edited.
The Translation Details page appears.
2. Change the description and add, edit, or delete translation entries as needed.
 To add an entry, click the Add Entry button.
 To edit an entry, click its Edit button.
 To delete an entry, click its Delete button.
3. To save the changes, click Save.
To delete a translation set
1. On the Translation Listing page, click on the translation set to be deleted.
The Translation Details page appears.
2. Click the Delete button on the page's toolbar.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 69
 AVEVA™ Enterprise Integration User Guide
Chapter 9 – Managing Translations

3. On the confirmation prompt, click OK.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 70
Chapter 10

Managing Distribution Lists

The Distribution Lists functionality of EI is tightly coupled with the Post Actions functionality. It offers a means of
managing groups of email addresses as a single unit. Email distribution lists offer a way of reusing lists of
from/to/SMTP server addresses for repetitive references in post action configurations. For example, an email
distribution list can be defined for Production Planners to send emails based on the success or failure of
importing SAP control recipes into MES or lists of quality personnel for sending the results of held product
awaiting inspection.
To open the Distribution List Listing page
 On the Configuration menu, click Messaging Configuration and then click Distribution Lists.

To filter the list of distribution lists by name

 In the Name box, enter the name or a portion of the name of the list or lists that you are searching for.
To add a distribution list
1. On the Distribution List Listing page toolbar, click Create New.
The Distribution List Details page appears.

2. Complete the distribution list properties.

Name
A unique name for the distribution list.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 71
 AVEVA™ Enterprise Integration User Guide
Chapter 10 – Managing Distribution Lists

Description
Description of the distribution list.
SMTP Server
SMTP server to be used for sending the emails.
From Address
From Address to be used for sending the emails. The From Address does not have to be a real email address
and is used solely for identifying the sender.
For example: [email protected].
To Address
Address or addresses that will belong to this distribution list. Multiple addresses must be separated by a
semi-colon (;).
3. To create the distribution list, click Save.
To edit a distribution list
1. On the Distribution List Listing page, click the Name link of the distribution list to be edited.
The Distribution List Details page appears.
2. Modify the properties as needed.
3. To save the changes, click Save.
To delete a distribution list
1. On the Distribution List Listing page, click the Name link of the distribution list to be deleted.
The Distribution List Details page appears.
2. Click Delete.
3. On the confirmation prompt, click OK.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 72
Chapter 11

Managing Connections

The connections functionality of EI allows you to encrypt SQL connection strings. Each connection string is
stored and transported in an encrypted state. The connection details are only decrypted when used. If an error
occurs, only the connection is identified.
To open the Connection Listing page
 On the Configuration menu, click Messaging Configuration and then click Connections.

To filter the list of connections by name

 In the Name box, enter the name or a portion of the name of the list or lists for which you are searching.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 73
 AVEVA™ Enterprise Integration User Guide
Chapter 11 – Managing Connections

To add a new connection

1. On the Connection Listing page toolbar, click Create New.
The Connection Details page appears.

2. Complete the Connection properties.

Name
A unique name for the connection.
Description
Description of the connection.
Server
The server that hosts the database.
Database
The database used in the connection.
User Id
The user ID to access the database.
Password
The password to access the database.
Integrated Security
Select this option to enable Windows Integrated Security for user authentication to establish the connection.
When using Integrated Security, the user in the web environment will be the currently logged-in user.
However, the EI service user will be the local system account by default. Make sure that the EI service user
account also has access to the database and server being configured. If the service user does not have
access, the Test buttons on the locations using the connection might work but the location will fail when
executed by the EI service.

3. To create the connection, click Save.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 74
 AVEVA™ Enterprise Integration User Guide
Chapter 11 – Managing Connections

If the connection is successful, the Connection Status field changes to green and updates to Connection
Established Successfully.

To edit a connection
1. On the Connection Listing page, click the Name link of the connection to be edited.
The Connection Details page appears.
2. Modify the properties as needed.
3. To save the changes, click Save.
To delete a distribution list
1. On the Connection Listing page, click the Name link of the connection to be deleted.
The Connection Details page appears.
2. Click Delete.
3. On the confirmation prompt, click OK.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 75
Chapter 12

Application Configuration

The Application Configuration feature allows you to manage configuration data for a specific plant and set their
default values.
The configuration data consists of the following event log items only at this time.
Email
If an email distribution list is defined here, EI sends a warning message to the distribution list when a
location is automatically disabled.
EventLog_DaysToKeep
Retention period for event log messages.
MessageHub_PurgeErrors
If set to 1, then errors are purged based upon the associated locations days to keep value.
MES Enabled
Determines if the MES functionality is enabled in EI. By default, this flag is set to 0 (off).
To use MES type locations (MESShiftEnd, MESJobEnd, MESTable), this flag must be set to 1 and the EI
service’s app.config file must also be set.
Use the EI Configurator utility to turn MES functionality on by navigating to the MES Connection and Failure
Behavior tab and configuring the MES user/password, then click Update.

Application Configuration Actions and Privileges Required

The table below shows the list of privileges required for the actions available on the Application Configuration
pages.

Action Privileges

Edit PortalBase_AppSettings_Config

Update PortalBase_AppSettings_Config

Refresh PortalBase_View

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 76
 AVEVA™ Enterprise Integration User Guide
Chapter 12 – Application Configuration

Viewing Plant Configuration Data

Displaying the Application Configuration page allows you to view the configuration data defined for the plant.
To display plant configuration data
 On the Configuration menu, click Application Configuration.

To filter the list by a configuration group

 Select the configuration group in the filter Configuration Group list.

Editing Plant Configuration Parameter Values

1. On the grid on the Application Configuration page, click the Edit link of the configuration parameter to be
edited.
The Value column becomes available for editing.

2. Change the value and click Update.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 77
Chapter 13

Event Log

The Event Log Listing page allows you to view EI sub-systems errors or warnings that have occurred and
recorded in the system event log. In addition, errors and warnings might also be sent to the ArchestrA System
Management Console.

Event Log Listing Actions and Privileges Required

The table below shows the list of privileges required for the actions available on the Event Log Listing pages.

Action Privileges

View PortalBase_View

Refresh PortalBase_View

Viewing Event Log Entries

 On the Configuration menu, click Event Log Listing.
The Event Log Listing page appears.

To filter the list of error log entries

 Enter filter criteria in the filter boxes, described below.
Message Text
Filter for event logs with Message matching any part of the entry given in this box.
Start Date
Filter for event logs with a start date on or more recent than the entry in this box.
Source
Filter for event logs from the selected source.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 78
 AVEVA™ Enterprise Integration User Guide
Chapter 13 – Event Log

Viewing Event Log Entry Details

 On the Event Log Listing page, click the event log entry’s View link.
The Event Log Details page appears.

Viewing EI Events in the ArchestrA System Management Console

In addition to recording events in the EI Event Log, EI can be configured to send all EI events to the ArchestrA
System Management Console.
To configure EI events so they are sent to the System Management Console
1. Open the WW.MessagingService.exe.config file located in the EI instance folder.
The default folder location for this file is:
C:\Program Files (x86)\EI\Instances\EI
2. Change the value of the LogErrorToSMC key from False to True as shown in the following example.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 79
Chapter 14

Message Log

The Message Log feature allows you to view messages received from or sent to external systems (e.g., SAP,
SAM, etc.)
The Message Log page displays all the messages that the EI system has handled and provides details of these
messages.

The Message Log grid displays the message details described below. Depending on the message type, some of
the contextual information described below might not be available.
#
The unique message ID created by the system.
Location Id
The message location ID of the message's location type.
Insert Date Time
The date/time that the message entered or exited the system.
Group
The message group.
Dir.
The message direction:
OUT
Message goes from EI to another system

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 80
 AVEVA™ Enterprise Integration User Guide
Chapter 14 – Message Log

IN
Message entering EI from another system
Src #
The unique source message ID created by the system.
Source Location Id
The source message's location ID of the source message's location type.
Message Type
The message type of a given message category.
Summary
Important information from the message. Content is based on the message type.
Status
The message status indicator:
Processing
A message that is currently being processed.
Processed
A message that has successfully entered or exited the system.
Error
There was an error processing the message.
Paused
A message that is held back from leaving the EI system (because its target location is Off).
Archived
A message that has been archived.
Un-Paused
A message that was paused and has been manually selected for re-processing. This state will only exist
temporarily between the user marking it for re-processing and the message processor processing the
message.
Retrying
A message that has caused an error, but the EI system is attempting to process it again.
Status Message
The latest status message for this message.

Message Log Actions and Privileges Required

The table below shows the list of privileges required for the actions available on the Message Log pages.

Buttons Privileges

Refresh Portalbase_View

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 81
 AVEVA™ Enterprise Integration User Guide
Chapter 14 – Message Log

Buttons Privileges

Reset Portalbase_View

Advanced Options WEI_Message_Modify

Re-Process WEI_Message_Modify

Archive WEI_Message_Modify

Viewing the Message Log

 On the Configuration menu, click Message Log.
The Message Log page appears.

Filtering the Message Log

You can filter the messages on the Message Log page or search for a specific message using the following filter
properties.
Insert Date/Time
Filter for messages within a date and time range:
Date/Time Boxes
Use the two boxes to specify a date/time range.
1D
Click to set the date/time range to one day prior to the current date/time.
5D
Click to set the date/time range to 5 days prior to the current date/time.
All
Click to not use a date/time range to filter the messages.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 82
 AVEVA™ Enterprise Integration User Guide
Chapter 14 – Message Log

Message #
Filter for messages whose ID is within this range. If an incorrect range is given, the Message Log is simply
refreshed.
Status
Filter for messages with the selected status.
Summary
Filter for messages with a summary that matches any part of this entry.
Message Type
Filter for messages of the selected message type.
Category
Filter for messages of the selected category.
Location
Filter for messages whose location match this entry.
Content
Filter for messages with content that matches any part of the entry.
Direction
Filter for messages of the selected direction.
Group
Filter for messages of the selected group.

Viewing Message Details

 On the Message Log page, click the number link in the # or Src # column.
A Message Display page appears. For more information about this page, see Message Display on page 85.

Re-Processing Messages
You can re-process a single message or a group of messages.
1. On the Message Log page, select the check boxes of the messages listed in the grid to be re-processed.
2. Click the Re-Process button.
3. When prompted by the confirmation message, click OK.

Archiving Messages
You can archive a single message or a group of messages. The corresponding message records in the database
are marked as archived. The archived message records are not deleted from the database. The result of this is
that messages that have been archived will no longer appear in the Message Log unless the search criteria are
set to All or Archived.
1. On the Message Log page, select the check boxes of the messages listed in the grid to be archived.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 83
 AVEVA™ Enterprise Integration User Guide
Chapter 14 – Message Log

To select all messages, select the check box at the top left corner of the grid.
2. Click the Archive button.
3. When prompted by the confirmation message, click OK.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 84
Chapter 15

Message Display

On the Message Display page, you can view message details received from or sent to external systems (e.g.,
SAP, SAM, etc.).

Message Display Actions and Privileges Required

The table below shows the list of privileges required for the actions available on the Message Display page.

Actions Privileges

Refresh Portalbase_View

Listing Portalbase_View

Export WEI_Message_Modify

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 85
 AVEVA™ Enterprise Integration User Guide
Chapter 15 – Message Display

Actions Privileges

Re-Process WEI_Message_Modify

Re-Process Transfer WEI_Message_Modify

Archive WEI_Message_Modify

As text Portalbase_View

As xml Portalbase_View

Save WEI_Message_Modify

Viewing Message Details

 On the Message Log page, click the number link of the message in the # or Src # column.
The Message Display page appears, showing the details of the selected message.

To return to the Message Log page

 On the Message Display page, click the Listing button.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 86
 AVEVA™ Enterprise Integration User Guide
Chapter 15 – Message Display

Archiving a Message
Archiving an EI message allows you to remove a message that has been sent and is no longer required. Note that
these steps will mark a record as archived in the database. It does not delete the record from the database.
To archive the current message on the Message Display page
1. Click the Archive button.
2. When prompted by the confirmation message, click OK.

Re-Processing Messages
Any message in the EI system can be re-processed—that is, resent—to its destination if required. For example,
you might want to re-process an error or paused message.
To re-process the current message on the Message Display page
1. Click the Re-Process button to re-process the message.
2. When prompted by the confirmation message, click OK.
Note: Check the Event Log Listing page for more information on errors.

Re-Processing Message Transfers

Any message in the EI system can re-process—that is, resend—its transfer destination message, if required. For
example, you might want to re-process an error or paused message transfer. A transfer destination table will be
displayed with the option to Re-Process Transfer if available, and only for messages with a direction of IN.
To re-process a message transfer for the current message on the Message Display page
1. Click the Re-Process Transfer button in the Transfer Destination Table to re-process the message transfer.
2. When prompted by the confirmation message, click OK.

Exporting Messages
To export the current message on the Message Display page
1. Click the Export button.
2. Choose a Destination location.
The message will be exported to the selected location.

Viewing and Editing the Message Content

By default, the message content in the Message Body box appears in XML format. You can also view the content
in plain text and edit it.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 87
 AVEVA™ Enterprise Integration User Guide
Chapter 15 – Message Display

To view and edit the message content of the current message on the Message Display page
1. On the toolbar, click the As Text button.
The message appears in plain text in the Message Body box.

2. Optionally, edit the message in the Message Body text box as needed and click SaveMsg.
3. On the toolbar, click the As XML button to view message as XML again.

Viewing a Message’s Additional Details Pages

The Message Display page allows you to open details pages corresponding to the current message.
To open additional details pages for the current message on the Message Display page
 Click one of the following links to open the corresponding details page:
Location ID
Opens the Location Details page.
Message Type
Opens the Message Type Details page.
Message Category
Opens the Manage Message Categories page.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 88
Chapter 16

Message Summary by Location Category

The Message Summary by Location Category page lists summaries of various EI messages. The following actions
can be performed:
 Turn Off or On a location category.
 Send EI messages.
 View the message log for each location category.

The Message Summary by Location Category grid displays the number of messages declared and sent to
external systems for each message category. The grid includes the following columns.
Change Status
Buttons for changing the location category status.
o Click On to change the status from Off (manual routing of messages to the destination location) to on
(automatic routing of messages to the destination location).
o Click Off to change the status from On to Off.
Status
Location category status: On (green) or Off (red).
Category
The location category. This can be one of the location categories as described in Managing Location
Categories on page 27.
Processing
Total number of messages currently being processed.
Processed
Total number of messages sent to an external system.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 89
 AVEVA™ Enterprise Integration User Guide
Chapter 16 – Message Summary by Location Category

Errored
Total number messages that have failed.
Retrying
Total number of message that are in the retry state.
Paused
Total number of messages that have a status paused.
Created Date/Time
The date and time when the category was created.
Send Paused Messages
Buttons to send a specific number of or all paused messages.
View Messages
Opens the Message Listing page, pre-populated for the message category.

Message Summary Actions and Privileges Required

The table below list the privileges required for the actions available on the Message Summary by Location
Category page.

Buttons Privileges

Refresh Portalbase_View

Change Status (On/Off) WEI_Location_ChangeStatus

Send Next WEI_Message_Send

Send All WEI_Message_Send

View Messages Portalbase_View

Viewing the Message Summaries by Location Category Listing

 On the Configuration menu, click Message Summary.
The Manage Summary by Location Category page appears.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 90
 AVEVA™ Enterprise Integration User Guide
Chapter 16 – Message Summary by Location Category

To filter the summary list by date

 Enter a date in the Created After Date box.
The default is one week prior to the system date.

Changing a Location Category’s Status

While changing a location category’s Status, all messages from that location category will be prevented from
being processed.
 On the Manage Summary by Location Category page, click the location category’s On or Off button.

Sending EI Messages to a Destination

To send a specified number of messages in selected location category
1. On the Manage Summary by Location Category page, enter the number of messages to send in the Send
Paused Messages column of the desired location category.
2. Click the Send Next button.
The messages are sent to their destination.
To send all messages in a selected location category
 On the Manage Summary by Location Category page, click the location category’s Send All button in the
Send Paused Messages column.
The messages are sent to their destination.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 91
Chapter 17

Plug-In Development

A EI system plug-in can be created to implement custom functionality. A EI system user can define plug-in
references throughout the EI application that will execute when a message is processed.
The Plug-in Reference locations and their corresponding interfaces are listed in the following table.

Screen Item Plug-In Interface

Manage Location Types Send-Receive Class IMessageSendReceive

Location Details Pre-Processor Class IMessagePreSend

Location Details URI IMessageProcessor

Location Details TransformClass IMessageTransform

Location Details AbortTransferClass IMessageAbortTransfer

To create a plug-in, the correct API interface must be used. The following topics describe the API interfaces for
the plug-in class types.

IMessageSendReceive
Definition
This interface defines two methods: SendMessage and ReceiveMessage.
Implementation
This interface would be implemented in a plug-in when defining a Send-Receive Class. The fully-resolved class
name can then be entered in the Send-Receive Class field on the Manage Location Types edit page.
By default, three Send-Receive Class plug-ins have been defined for use:
WW.Messaging,WW.Messaging.FolderSendReceive
Used to process XML, flat file, or CSV files. It can receive them from a folder (usually dropped by another
system) or output the message contents to a folder.
o Must define a folder path in the URI field of the message location.
WW.Messaging,WW.Messaging.DotNetClassSendReceive
Used to do in-depth processing of the message contents that require the use of Microsoft.NET classes.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 92
 AVEVA™ Enterprise Integration User Guide
Chapter 17 – Plug-In Development

o Used for custom code implementation.

o Must define a URI (AssemblyName, ClassName) that implements the IMessageProcessor for the plug-in
to work.
WW.Messaging,WW.Messaging.MSMQSendReceive
This location type interacts with Windows MSMQ. It can be used as a connection point between systems.
However, it used very infrequently since EI has its own message queue.
Common Use
Folder, database, FTP, or MSMQ message transfers.

IMessagePreSend
Definition
Defines the method PreSend.
Implementation
This interface would be implemented in a plug-in when defining a PreSend Class. The fully-resolved class name
can then be entered in the PreSend Class field on the Location Details page for the desired message location. A
class that implements this interface can only be used on a message location where the Direction field is set to
OUT.
Common Use
Modifying the content (body of the message) or its label before a message is processed.

IMessageTransform
Definition
Defines the method TransformMessage, which returns a structure of type MessageData.
Implementation
This interface would be implemented in a plug-in when defining a TransformClass. The fully-resolved class name
may then be entered in the Transform Class field of a Transfer Destination Location for a message location.
Common Use
Modifying the status or category before a message is processed.

IMessageAbortTransfer
Definition
Defines the method CheckAbortTransfer.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 93
 AVEVA™ Enterprise Integration User Guide
Chapter 17 – Plug-In Development

Implementation
This interface would be implemented in a plug-in when defining an AbortTransferClass. The fully-resolved class
name can then be entered in the Abort Transfer Class field of a Transfer Destination Location for a message
location.
Common Use
When a message is still waiting for crucial information to be updated and cannot be sent out until that data is
received.

IMessageProcessor
Definition
Defines the methods ProcessMessage and GetMessage.
Implementation
This interface would be implemented in a plug-in when defining a MessageProcessorClass. The fully-resolved
class name can then be entered in the URI field on the Message Location page.
Common Use
Only used for message locations with a Location Type Send-Receive Class plug-in defined as a
WW.Messaging.WW.Messaging.DotNetClassSendReceive.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 94
Chapter 18

EI Web Services

EI Message Manager is a web service that provides a message passing mechanism that provides positive
feedback to the remote application that the message was received and stored in the EI database as opposed to
message passing using MSMQ or files. The web service defines one action and that is to add a single message to
a specified location.

User Interface
The web service may be exercised manually by opening the web page at a URL such as
http://<ComputerName>/<EIInstanceName>/MessageManager.asmx
where
 <ComputerName> is replaced with the name of the EI server
 <EIInstanceName> is replaced with the name of the EI instance that was created using the EI Configurator
utility
For example, if browsing from the EI Server and the default EI instance name was used in the configuration, then
the URL would be http://localhost/EI/MessageManager.asmx and the web page would appear as shown in the
figure below.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 95
 AVEVA™ Enterprise Integration User Guide
Chapter 18 – EI Web Services

This web page lists the methods offered by the web service that consists of the AddMessage method. The
method name is a link that can be clicked to display a page, as shown in the figure below, showing the
AddMessage details and a form which can be used to invoke the method to insert a message into EI. In addition,
the Service Description link may be clicked to view the web service definition (WSDL).

Invoking the AddMessage Method from the Details Web Page

To pass a message to EI from the AddMessage details web page
1. Open the MessageManager page.

2. Complete the message properties, described below.

locationId
A valid message location
messageBody
The message content.
messageLabel
The message label. This would be the file name.
3. Click Invoke.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 96
 AVEVA™ Enterprise Integration User Guide
Chapter 18 – EI Web Services

A message indicating the success or failure of the AddMessage operation appears.

The following two figures show the EI Message Log and the Message Display pages showing the just-added
message.

Invoking the AddMessage Method from an Application

The EI Web Service was designed to receive messages from other software applications. The C# code snippets
shown below create an instance of the web service in an application and then call the AddMessage method from
that same application.
//Create new object from Web Reference
EISvc.MessageManager WebSvc = new EISvc.MessageManager();
//Get Web Service URL from config file

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 97
 AVEVA™ Enterprise Integration User Guide
Chapter 18 – EI Web Services

WebSvc.Url = Properties.Settings.Default.EI_Plugin_EISvc_MessageManager;
WebSvc.UseDefaultCredentials = true;
//Call the AddMessage method to insert the message into EI:
//Add message to EI
WebSvc.AddMessage("TestIn","<? xml version = 1.0 encoding = utf - 8 ?>
< TestMsg >< MsgBody > This is the message content.</ MsgBody >
</ TestMsg >","Test Message Sent");
These code snippets are from a Visual Studio project in which a reference to the web service was created using
the following procedure.
1. In the Visual Studio Solution Explorer tree, right-click References and then click Add Service Reference.

The Add Service Reference dialog box appears.

2. Click the Advanced button.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 98
 AVEVA™ Enterprise Integration User Guide
Chapter 18 – EI Web Services

The Service Reference Settings dialog box appears.

3. Click the Add Web Reference button.

The Add Web Reference dialog box appears.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 99
 AVEVA™ Enterprise Integration User Guide
Chapter 18 – EI Web Services

4. Enter the URL of the EI web service in the URL box and click the Go button.
The URL shown in the previous figure contains a placeholder, <EI server name>, which should be replaced
with the node name of the EI server.
If the URL is successfully contacted, then the MessageManager.asmx page appears below the URL. The Web
reference name box can be edited to customize the class name for the web service that will be available for
use in the code, as shown in the figure below. This value was entered as WebSvc for the code snippet above.

When this procedure is complete, the new web reference appears in the Solution Explorer window under
the Web References category, as shown in the figure below.

Version 6.2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 100