Manufacturing Execution System (MES)

Middleware Extensibility Hooks

Reference

Version 6.0
June, 2018
© 2018 AVEVA Group plc or its subsidiaries. All rights reserved.
The Schneider Electric industrial soft ware business and AVEVA have merged to trade as AVEVA Group
plc, a UK listed company. The Schneider Electric and Life is On trademarks are owned by Schneider
Electric and are being licensed to AVEVA by Schneider Electric.
No part of this documentation shall be reproduced, stored in a ret rieval system, or transmitted by any
means, electronic, mechanical, photocopying, rec ording, 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 docum entation, 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 soft ware described in this
documentation is furnished under a license agreement. This soft ware may be used or copied only in
accordance with the terms of such license agreement.
ArchestrA, Aquis, Avantis, DYNS IM, eDNA, EYESIM, InBatch, InduSoft, InStep, IntelaTrac, InTouch,
PIPEPHASE, PRiSM, PRO/II, PROV IS IO N, ROMeo, SIM4ME, SimCentral, SimSci, Skelta,
SmartGlance, Spiral Software, Termis, 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: 6/29/2018
Contact Information
AVEVA Group plc
High Cross
Madingley Road
Cambridge
CB3 OHB. UK
https://sw.aveva.com/
For information on how to cont act sales, customer training, and technical support, see
https://sw.aveva.com/contact.
 MES Middleware Extensibility Hooks Reference

Contents
Chapter 1 Getting Started..................................................................................................... 5
Using This Guide ...................................................................................................................... 5
Definitions ................................................................................................................................ 5
Introduction to MES Middleware Extensibility Hooks .................................................................... 5
Custom Action Scenarios Using Hooks ................................................................................. 6

Chapter 2 Functional Overview ........................................................................................... 7

Pre-Hook and Post-Hook Configuration ...................................................................................... 7
Execution Flow Diagram ............................................................................................................ 8
Trans action Control ................................................................................................................... 9
Stored Procedure ................................................................................................................ 9
Assembly............................................................................................................................ 9

Chapter 3 Configuring Pre-Hooks and Post-Hooks ....................................................... 11

Installation Location ................................................................................................................ 11
Opening the Middleware Configuration Editor ........................................................................... 11
Middleware SP Name.............................................................................................................. 12
Mappings to New MES Version 6.0 Stored Procedures ........................................................ 12
Pre-Hook/Post-Hook Name ..................................................................................................... 15
Stored Procedure .............................................................................................................. 15
Assembly.......................................................................................................................... 15
Assembly Is Not Added to the GAC .............................................................................. 16
Assembly Is Added to the GA C .................................................................................... 16
Pre-Hook and Post-Hook Type ................................................................................................ 16
Middleware Flow (P re-Hook/Post-Hook) ................................................................................... 16
Stop ................................................................................................................................. 16
Stop on Error .................................................................................................................... 17
Continue E ven on Error ..................................................................................................... 18
Loading the Configuration and Hooks ....................................................................................... 18
Examples of Middleware Hook Configurations and Executions ................................................... 19
Custom Stored Proc edure Hook ......................................................................................... 19
Cont ent of the Custom Stored P rocedure sp_I_Uom_Log .............................................. 19
Action ......................................................................................................................... 20
Custom Stored Proc edure Hook Raises an Error (Middleware Flow: Stop) ............................ 20
Cont ent of the Custom Stored P rocedure sp_I_Uom_Log .............................................. 20
Action ......................................................................................................................... 21
Custom Assembly That Is Not in the GAC ........................................................................... 21
Cont ent of the Code in the TestHooksClass.cs .............................................................. 21
Action ......................................................................................................................... 22
Custom Assembly Is Added to the GA C.............................................................................. 22

Version 6.0 3
MES Middleware Extensibility Hooks Reference Contents

Cont ent of the Code in the TestHooksClass.cs .............................................................. 23

Action ......................................................................................................................... 23

Chapter 4 Configuring Extensibility Hooks on Multiple Middleware Servers ............. 25

Chapter 5 Frequently Asked Questions ........................................................................... 27

4 Version 6.0
 MES Middleware Extensibility Hooks Reference

C HAPTER 1
Getting Started
In This Chapter
Using This Guide ............................................................................................................................ 5
Definitions ...................................................................................................................................... 5
Introduction to MES Middleware Extensibility Hooks ......................................................................... 5

Using This Guide

A Manufacturing Execution System (MES ) Middleware Extensibility Hook is a mechanism for invoking an
assembly or a stored procedure to perform custom actions before and/or after a specific middleware
event is executed.
The purpose of this guide is to help you use the MES Middleware Extensibility Hooks mechanism.
This chapter int roduces and defines concepts used in the manual, and describes the purpose for
Middleware Extensibility Hooks.
Subsequent chapters describe how the hooks function with the middleware, explain how to configure
hooks, and provide configuration and execution examples.

Definitions
 A middleware event is a method expos ed by the MES middleware and that method can be invoked
by the client layer (e.g., stateless API, etc.) to perform some action in the MES dat abas e.
 A hook represents a custom functionality implemented by the end us er in the form of a stored
procedure, assembly, workflow, etc. A pre-hook represents a custom functionality implemented by
the end user to execute that functionality before the middleware event is executed. A post -hook
represents a custom functionality implemented by the end user to execute that functionality after the
middleware event is processed.

Introduction to MES Middleware Extensibility Hooks

The purpose of the Middleware Extensibility Hooks is to enable an end user to execute custom
functionalities, such as invoking an Arc hestrA workflow, calling a custom stored procedure, or calling a
method in an assembly, before or after processing the middleware event. This allows the end user to use
their custom functionalities to check for specific conditions or perform certain processes beyond those
supported by standard MES functionality.
The Extensibility Hooks configuration is stored in the middleware folder, and it is loaded int o the MES
middleware host’s memory to execute the hooks when a corresponding middleware event is made to the
MES middleware.
The middleware can be configured for a set of one or more hooks against a single middleware event.
That is, when the Extensibility Hooks are configured for a middleware event, the MES middleware
executes the pre-hook before the middleware event is processed, processes the middleware event, and
then executes the post-hook aft er the middleware event. The hook configurations provide an option to
cancel the entire middleware event, including the exec utions of pre- and post-hook in case of an error.
The pre-hook configuration also provides an option for an end user to stop processing the middleware
event, if the standard middleware functionality is embedded inside the custom implementation.

Version 6.0 5
MES Middleware Extensibility Hooks Reference Getting Started

Custom Action Scenarios Using Hooks

There are many scenarios where the extensibility hooks can be used to check for specific conditions,
process custom actions to control the flow of middleware event, and so on. The examples listed in the
table below explain how the hooks can be used to perform custom actions.

Hook Intercept Condition/Process Hook Type Example Scenarios

sp_U_Process_CheckIn Process Status Pre-Hook A pre-hook can intercept the

(Process.CheckIn) changed from or to incoming middleware call (e.g.,
Certified. Process.CheckIn) to validate
whet her the user has a special
Changing the status of
permission to change the
a process from or to
process status from/to certified,
Certified requires a
and act based on the outcome
user to have special
from the custom validation.
permission/ privilege.
sp_I_Cert_User_Link A visual inspection of Pre-Hook A pre-hook can intercept the
(Cert_User_Link.Add) user’s certification is incoming middleware call (e.g.,
required before the Cert _User_Link.Add) to send
certification is attached an email (using work flow) to the
to the user. factory supervisor for
authorization before the
certification can be attached to
the user.
sp_U_Job_Exec _ Creating a new work Pre-Hook A pre-hook can intercept the
StrtDataEntry Job order that is not incoming middleware call (e.g.,
(Job_Exec.Start DataEnt ryJob) instantiated from a Job_Exec.StartDataEntryJob)
process requires to initiate a workflow for the
authorization from the supervisor to authorize the
supervisor. transaction before the data
entry job is created in the MES
database.
sp_U_Storage_Exec_AddInv Push the inventory Post-Hook A post-hook can do the post
(Storage_Exec.AddInv) quantities to the ERP. processing on the
Storage_Exec.AddInv call to
push the inventory quantities to
an external
application/database.

6 Version 6.0
 MES Middleware Extensibility Hooks Reference

C HAPTER 2
Functional Overview
In This Chapter
Pre-Hook and Post-Hook Configuration ............................................................................................ 7
Execution Flow Diagram ................................................................................................................. 8
Trans action Control ......................................................................................................................... 9

Pre-Hook and Post-Hook Configuration

A pre-hook and the post-hook can be configured for a single middleware event to invoke one or more
stored procedures (if more than one stored procedure call is embedded inside the single custom stored
procedure configured into an Extensibility Hook; see the second note below for more details) or they can
be configured to invoke a .NE T assembly to handle more complex activities. When invoking a stored
procedure, the custom (hook) stored procedure must exist in the MES database targeted by the
Middleware Server. Similarly, when invoking a .NE T assembly, the assembly must exist in the specified
path (see Assembly on page 15 for more details about assembly configuration).
Both pre- and post-hooks can be configured to either continue or stop if an error is encountered.
Pre-hooks can also be configured to stop after executing and not allow the normal stored procedure t o be
called, even in the absence of an error. See Middleware Flow (Pre-Hook /Post-Hook ) on page 16 for more
information.
Notes
 A single middleware event can have only one pre-hook and one post-hook.
 To execute more than one stored proc edure for a single middleware event, all the custom stored
procedures must be invoked from inside the custom stored procedure named in the hook. Similarly,
to invoke more than one assembly for a single middleware event, all the intended assemblies must
be invoked inside that single custom assembly named in the hook.
 If a pre-hook or a post-hook is not linked to a middleware event, then that middleware event is not
affected by any custom hook implementations inside or outs ide the MES database.

Version 6.0 7
MES Middleware Extensibility Hooks Reference Functional Overview

Execution Flow Diagram

The following diagram illustrates the flow of the pre -hook, middleware event, and the post-hook.

8 Version 6.0
Functional Overview MES Middleware Extensibility Hooks Reference

Transaction Control
If pre- and/or post-hooks are c onfigured, then t he flow of the middleware event (i.e., whether t o commit or
rollback, stop or continue with the flow) is controlled by the Middleware Flow parameter [see Middleware
Flow (P re-Hook /Post-Hook ) on page 16 for more information]. If an exception is raised from the pre- or
post-hooks or from the middleware event itself, and Middleware Flow is set to Stop on Error, then the
current transaction is rolled back, including the transactions from pre - and post-hooks. The end user is
responsible for determining when to raise an error from the stored procedure/assembly and for
controlling the flow of the middleware event.
The stored procedures/assemblies involved for the pre- and post-hooks are execut ed as a part of the
middleware transaction that corresponds to the middleware event. In general, the stored
procedures/assemblies involved for the pre- and post-hooks are executed as a part of the middleware
transaction that corresponds to the middleware event. The total transaction time allotted for the
middleware event is split among the pre-hook, middleware event, and the post-hook. However, if the
Middleware Flow parameter is set to Continue E ven on Error, then each event (i.e. pre-hook, normal
middleware event, post-hook) is executed in a s eparate t rans action. In this case, the transaction time -out
that is configured applies to each transaction.

Stored Procedure
The transaction that corresponds to the middleware event needs to complete executing the custom
stored proc edure configured for t he pre-hook, complete executing the middleware stored procedure, and
complete executing the custom stored procedure configured for the post -hook. All three of these stored
procedures must be executed within the allotted transaction time; otherwise, the middleware raises a
timeout exception to the caller.
It is not recommended to have an autonomous transaction or nested transactions inside custom stored
procedures, becaus e that might affect the transaction flow built inside the MES product.

Assembly
A transaction started by the middleware event needs to be completed within the allotted time. The
amount of time allotted for the middleware transaction time includes the time the middleware takes to
execute custom pre-hook assembly, custom post-hook assembly, and the middleware call itself.
Therefore, end users must be cautious when writing custom assembly hooks such that they do not cause
any performance bottlenecks when executing the actual middleware call. If the code in the assembly
involves processing the files or executing long running transactions, then it is recommended to execut e
those processes on a background thread, so that the pre - or the post-hook processes do not block the
main thread. However, the transactions started on a separate thread (e.g., background thread) are not
part of t he transaction started on the main thread (i.e., Middleware E vent thread). Therefore, the success
or failure on the secondary thread does not affect the trans action on the main thread as long as they do
not create deadlocks.

Version 6.0 9
 MES Middleware Extensibility Hooks Reference

C HAPTER 3
Configuring Pre-Hooks and Post-Hooks
In This Chapter
Installation Location ...................................................................................................................... 11
Opening the Middleware Configuration Editor ................................................................................. 11
Middleware SP Name ................................................................................................................... 12
Pre-Hook/Post-Hook Name ........................................................................................................... 15
Pre-Hook and Post-Hook Type ...................................................................................................... 16
Middleware Flow (P re-Hook/Post-Hook) ......................................................................................... 16
Loading the Configuration and Hooks............................................................................................. 18
Examples of Middleware Hook Configurations and Executions ........................................................ 19

Installation Location
The Middleware Extensibility Hooks mechanism is installed as a part of standard MES installation on
machines where the MES middleware is installed. If default location was used for the MES installation,
this application/editor (MWDBMappingEditor.exe) can be found in the following folder on the machine
that is hosting the MES host (i.e., the machine that is hosting the Middleware Server):
C:\Program Files\Wonderware\MES\Middleware\
However, the installation path can vary if the MES middleware (MES Host) is installed on a different drive
or in a different folder. Therefore, look for this application in your corresponding installation path, which
typically ends with \MES\Middleware\.

Opening the Middleware Configuration Editor

To open the Middleware Configuration Editor
 On the Start menu, click the Middleware Configuration Editor tile.

Version 6.0 11
MES Middleware Extensibility Hooks Reference Configuring Pre-Hooks and Post-Hooks

The Middleware Configuration Editor window appears.

The configuration information entered in the Middleware Configuration Editor is stored in the file
MWDBMappingsCustom.xml file specified in Installation Location on page 11.

Middleware SP Name
This column in the Middleware Configuration Editor represents a unique stored procedure name for
which a post-hook or a pre-hook can be configured.

Note: No stored procedure name can be used more than once.

The stored procedure name is the name of a valid stored procedure that exists in the MES database to
which the MES middleware connects. The end us er is responsible for finding the correct stored
procedure name by manually looking at the stored procedure names in the MES database.
Whenever this stored procedure (c onfigured in this column) is invoked, by virtue of calling an equivalent
middleware method from the client, the middleware determines whether there are any pre- or post-hooks
configured for this stored procedure and execute them according to the Extensibility Hook configuration.
The hooks configured for a stored proc edure can be removed or deleted by highlighting the row in the
grid.

Mappings to New MES Version 6.0 Stored Procedures

The utilization optimization improvements that were implemented in the MES version 6.0 database
schema included removed and replaced utilization-related stored procedures. The following table lists
the affected pre-6.0 stored proc edures and the 6.0 stored procedures that replaced them, if applicable.

12 Version 6.0
Configuring Pre-Hooks and Post-Hooks MES Middleware Extensibility Hooks Reference

If any of these pre-6.0 stored procedures were configured for extensibility hooks, the hooks should be
reconfigured wit h the new stored procedures so that they will work properly with the current schema.

Pre-6.0 Stored Procedure Replacement 6.0 Stored Comments

Procedure

sp_D_Job_Util_Log_Link sp_D_Job_History When deleting a record in the previous

schema, a portion of job duration was
deleted. In the current schema, the
duration of the entire job runtime is
deleted.
sp_D_Tpm_Stat sp_D_Job_Hour_History In the current schema, Job_Start_Utc is
required to identify a unique row.
sp_D_Util_Log sp_D_Util_History In the current schema, Ent Id +
E vent TimeUtc is required, in place of
sp_D_Util_Log_DelUtilE vent sp_D_Util_History
log_id that us ed in the previous schema.
sp_I_Job_Util_Log_Link sp_I_Job_History A portion of job duration was added in
the previous schema. In the current
schema, a history record represents an
entire job runtime (duration).
sp_I_Tpm_Stat sp_I_Job_Hour_History In the current schema, Job_Start_Utc is
required to identify a unique row.
sp_I_Util_Log sp_I_Util_History In the current schema, Ent Id +
E vent TimeUtc is required, in place of
sp_I_Util_Log_AddUtil sp_U_Util_History_
log_id that us ed in the previous schema.
AddE vent
sp_I_Util_Log_AddUtilE vent sp_U_Util_History_
AddE vent
sp_S_Job_Util_Log_Link sp_S_Job_History A portion of job duration was ret urned in
the previous schema. In the current
schema, the entire job duration is
returned.
sp_S_Tpm_Stat sp_S_Job_Hour_History In the current schema, Job_Start_Utc is
required to identify a unique row.
sp_S_Util_Log sp_S_Util_History In the current schema, Ent Id +
E vent TimeUtc is required, in place of
log_id that used in the previous schema
sp_SA_Job_Util_Log_Link sp_SA_Job_History A portion of job duration was ret urned in
the previous schema. In the current
schema, the entire job duration is
returned.
sp_SA_Tpm_Stat sp_SA_Job_Hour_History In the current schema, Job_Start_Utc is
required to identify a unique row.
sp_SA_Util_Log sp_SA_Util_History
sp_U_Job_Exec _ N/A In the current schema, times are
AdjustJobDur calculated on demand, so these
procedures are obsolete.
sp_U_Job_Exec _
CloseCurrE vents

Version 6.0 13
MES Middleware Extensibility Hooks Reference Configuring Pre-Hooks and Post-Hooks

sp_U_Job_Util_Log_Link sp_U_Job_History A portion of job duration was updat ed in

the previous schema. In the current
sp_U_Job_Util_Log_Link_
schema, the duration of the entire job
Join runtime is affected.
sp_U_JULL_AdjustJobUtil
sp_U_Oee_Exec_ N/A This is an internal stored procedure and
SetCurrentOEE should not have been used by the
extensibility hooks.
sp_U_Tpm_Stat sp_U_Job_Hour_History In the current schema, Job_Start_Utc is
required to identify a unique row.
sp_U_TPM_Stat_NewE vent N/A These are internal stored procedures
and should not have been used by the
sp_U_TPM_Stat_NewJob extensibility hooks.
sp_U_TPM_Stat_NewShift
sp_U_TPM_Stat_RefreshCurrV
als
sp_U_TPM_Stat_
UpdateDurations
sp_U_TPM_Stat_UpdDur
sp_U_TPM_Stat_UpdQtys
sp_U_UL_ N/A In the current schema, times are
UpdateDurationBy Name calculated on demand, so this
procedure is obsolet e.
sp_U_Util_Exec_NewE vent N/A These are internal stored procedures
and should not have been used by the
sp_U_Util_Exec_NewJob
extensibility hooks.
sp_U_Util_Exec_
NewJobE vent
sp_U_Util_Exec_NewShift
sp_U_Util_Exec_
SetCurrentUtil
sp_U_Util_Log sp_U_Util_History In the current schema, Ent Id +
E vent TimeUtc is required, in place of
sp_U_Util_Log_ log_id that us ed in the previous schema.
AdjustDuration
sp_U_Util_Log_AdjustE vents
sp_U_Util_Log_MergeLogs N/A This is an internal stored procedure and
should not have been used by the
extensibility hooks.
sp_U_Util_Log_SplitLogs N/A To split or merge events, use
sp_U_Util_History_AddE vent or
sp_U_Util_History_UpdateE vent.
sp_U_Util_Log_ N/A In the current schema, times are
UpdAllDurations calculated on demand, so these
procedures are obsolete.
sp_U_Util_Log_
UpdateDuration

14 Version 6.0
Configuring Pre-Hooks and Post-Hooks MES Middleware Extensibility Hooks Reference

sp_U_Util_Log_UpdateUtil sp_U_Util_History_UpdateE v In the current schema, Ent Id +

ent E vent TimeUtc is required, in place of
log_id that us ed in the previous schema.
However, the
sp_U_Util_History_UpdateE vent is
backward compatible to use with the
local times and log_id.

Pre-Hook/Post-Hook Name
The name of the Extensibility Hook is configured in this column.

Note: If the name is left blank (or empty), the middleware assumes that the Extensibility Hook is not
configured.

Stored Procedure
A valid stored procedure name from the MES dat abas e, if the type of Extensibility Hook is stored
procedure.
The parameter names, dat a types, and presence of default values in the custom (hook) stored procedure
must match exactly those of the parameter names, data types, and pres ence of default values in the
middleware stored procedure (stored procedures configured in the Middleware SP Name column).
However, there can be additional parameters in the custom (hook) stored procedure that might not be
matching the parameters in the middleware stored procedure, but those additional paramet ers must be
defaulted to NULL in the custom stored procedure. If they are not defaulted to NULL, an exception might
be raised by the dat abas e layer for not supplying enough values for those additional parameters. It is
recommended that the list of stored procedure parameters, data types, and default values (if any) be
copied from the middleware stored procedure to the custom stored procedure to ensure all these
properties are identical bet ween them. However, the default values for the custom (hook) stored
procedure do not have to ex actly match the default values in the middleware stored procedure.
The values supplied for the middleware stored procedure (configured in the Middleware SP Name
column) are the same values supplied to the custom (hook) stored procedure.

Assembly
The hook method in the assembly has a single ‘string’ parameter that accepts the XML message from the
middleware event. The XML message is the exact XML generated for the middleware event to process.
The end user is responsible for parsing the XML message and extracting the relevant data from the XML
message. See the Stateless API help for more details about the XML structure. The middleware calls
impersonate the ArchestrA Net work user; therefore, the custom (hook) assembly is invoked as that user.
The assembly name can be configured in two ways:
 If the assembly is added to the GA C, then the detailed information about the assembly version,
public key token, etc. must be specified.
 However, if the assembly is not added to the GAC, then the physical location of the assembly must
be specified.
In both of these cases, the class name and the method name must be specified by separating them by
semi-colon (;).

Note: The configured Extensibility Hook method can accept only one string parameter.

Version 6.0 15
MES Middleware Extensibility Hooks Reference Configuring Pre-Hooks and Post-Hooks

Assembly Is Not Added to the GAC

If the assembly is not currently added to the GAC, the user is required to specify the physical location of
the assembly itself to load the assembly from the specified path.
For example,
C:\Temp\ TestHooks\TestHooks\bin\Debug\TestHooks.dll;TestHooksNamespace. TestHooksClass;
TestHooksMethod
represents the assembly name as TestHooks.dll, located at the pat h
C:\Temp\TestHooks\Te stHooks\bin\Debug\, and that has the namespac e TestHooksNamespace,
class name TestHooksClass, and the met hod name TestHooksMethod.

Assembly Is Added to the GAC

If the assembly is currently added to the GAC, the us er is required to specify the public key token,
assembly version, and so on, to load the right assembly from the GA C.

Note: The assembly must be signed with a strong name.

For example,
TestHooks, version= 1.0.0.0,culture=neutral,processorarchitecture=MS IL,PublicKeyToken= 23106a8
6e706d0ae; TestHooksNamespace. TestHooksClass;TestHooksMethod
represents the assembly name as TestHooks.dll, version as 1.0.0.0, public key token as
23106a86e706d0ae, and that has the namespace TestHooksNamespace, class name TestHooksClass,
and the method name TestHooksMethod.

Pre-Hook and Post-Hook Type

A single middleware event can either execute a stored procedure or invoke an assembly for a pre-hook
and a post-hook. No other types besides the following are allowed in the current release.
 Stored procedure. Indicates that the configured hook type is a stored procedure. In other words, the
name configured in the corresponding Pre-Hook Name or Post-Hook Name column is considered to
be a stored procedure. Therefore, the configured custom stored procedure in the MES dat abas e is
invok ed before or aft er the middleware call depending upon the pre-hook or post-hook configuration.
 Assembly. Indicates the configured hook type is an assembly. In other words, the name configured
in the corresponding Pre-Hook Name or Post-Hook Name column is considered to be an assembly.
Therefore, the c onfigured custom assembly is invoked before or after the middleware call depending
upon the pre-hook or post-hook configuration.

Middleware Flow (Pre-Hook/Post-Hook)

This column in the Middleware Configuration Editor represents the type o f flow that is desired while
processing the middleware event. The following sub -sections explain the different types of middleware
flow supported by the MES middleware.

Stop
This option indicates that the flow of the middleware exec ution will stop after completing the current
execution, regardless of whet her the current execution succeeds or not. In other words, when the pre- or
the post-hook is configured with this option, the execution stops with the current call and returns the
result to the caller, regardless of whether the current transaction was successful or not (i. e., committed or
rolled back). If an error occurs, the error message is returned to the caller.
The table below describes the flow of the middleware call after the pre-hook or post-hook execution is
completed with the Middleware Flow parameter set to Stop.

16 Version 6.0
Configuring Pre-Hooks and Post-Hooks MES Middleware Extensibility Hooks Reference

Hook Type Hook Succe ss Hook Error

Pre-Hook Stop. The pre-hook call is completed Stop. The pre-hook call resulted in an error.
successfully. The error message is returned to the end
user or the error message is logged in the
Note: The data modified on tables for the logger.
pre-hook call is committed. The normal
middleware call will never be executed. Note: The data modified on table for the
pre-hook call is rolled back. The normal
middleware call will never be executed.

Post-Hook Not applicable; this option cannot be Not applicable; this option cannot be
configured for post-hooks. configured for post-hooks.

Stop on Error
This option indicat es that the flow of the middleware execution will stop only if it encounters an error while
processing the current execution. As long as there is no error while executing the pre -hook, post-hook, or
the middleware event, the execution continues.
The table below describes the flow of the middleware call after the pre-hook or post-hook execution is
completed with the Middleware Flow parameter set to Stop on Error.

Middleware Execution
Hook Type Status Hook Succe ss Hook Error

Pre-Hook Not applicable. The pre-hook call Stop. The pre-hook call
completed successfully. resulted in an error. The
error message is returned
Note: The data modified to the caller.
on tables for the pre-hook
call is committed. The Note: The data modified
middleware continues to on tables for the pre-hook
execute the normal call is rolled back. The
middleware call. normal middleware call will
never be executed.

Post-Hook The normal middleware The data modified on The data modified for the
call/transaction has tables for the normal normal middleware call
succeeded. middleware call and for the and for the post-hook are
post-hook are committed. both rolled back. The error
message is returned to the
caller.

Post-Hook Stop. Not applicable. Not applicable.

The normal middleware Note: The post-hook will Note: The post-hook will
call/transaction has failed never be executed, never be executed,
or rolled back. because the normal because the normal
The error message is middleware middleware
returned to the caller. call/event/transaction has call/event/transaction has
failed or rolled back. failed or rolled back.

Version 6.0 17
MES Middleware Extensibility Hooks Reference Configuring Pre-Hooks and Post-Hooks

Continue Even on Error

This option indicates that the flow of the middleware exec ution will continue even when an error is
encountered in any part of the exec ution sequence.
The table below describes the flow of the middleware call after the pre- or post-hook execution is
completed with the Middleware Flow param\-eter set to Continue E ven on Error.

Middleware Execution
Hook Type Status Hook Succe ss Hook Error

Pre-Hook Not applicable. The pre-hook call is Continue even on error.

completed successfully. The pre-hook call resulted
in an error. The generat ed
Note: The data modified error message is ignored
on tables for the pre-hook by the middleware.
call is committed. The
middleware continues to Note: The data modified
execute the normal on tables for the pre-hook
middleware call. call is rolled back. The
middleware continues to
execute the normal
middleware call.

Post-Hook The normal middleware The databas e transactions The data modified on
call/transaction has started for the normal tables for the normal
succeeded. middleware call and for the middleware call is
post-hook call are committed, but the data
committed. modified on tables for the
post-hook is rolled back.
The error message
generated by the
post-hook transaction is
ignored by the middleware.

Post-Hook The normal middleware Stop. The error message is Not applicable.
call/transaction has failed returned to the caller.
or rolled back. Note: The post-hook will
Note: The post-hook will never be executed,
never be executed, because the normal
because the normal middleware
middleware call/event/transaction has
call/event/transaction has failed or rolled back.
failed or rolled back.

Loading the Configuration and Hooks

After the Extensibility Hooks are configured and saved in the Middleware Connection Editor, the MES
Host/MES Middleware must be restarted to reload all the configuration details and the Extensibility
Hooks into its memory.

18 Version 6.0
Configuring Pre-Hooks and Post-Hooks MES Middleware Extensibility Hooks Reference

Examples of Middleware Hook Configurations and Executions

The examples in the following sections illustrate how t he Extensibility Hooks can be configured and used
using different options provided in the Middleware Configuration Editor.

Custom Stored Procedure Hook

This example illustrates how a custom stored procedure can be configured as a hook that can be invoked
when executing a standard stored procedure in the MES middleware.
The following example configuration is added to the Middleware Configuration Edit or.

Configuration Parameter Example Entry Description

Middleware SP Name sp_I_UOM The actual stored procedure name, supplied

out-of-the box, from the MES database.

Pre-Hook Name sp_I_Uom_Log The custom stored proc edure created by the
end user in the MES dat abase after installing
the MES database.
Pre-Hook Type SP Indicates that the type of this hook is a stored
procedure
Middleware Flow STOP ON ERROR Indicates to the middleware to stop the
execution if there was an error while executing
the sp_I_Uom_Log stored proc edure.

Content of the Custom Stored Procedure sp_I_Uom_Log

CREATE PROCEDURE sp_I_Uom_Log
(@description nvarchar(40)
,@abbreviation nvarchar(20)
,@last_edit_comment nvarchar(254)
,@my_arg nvarchar(40) = null
,@last_edit_at datetime OUT
,@uom_id int OUT
) AS
BEGIN
SET NOCOUNT ON
DECLARE @logged_at DATETIME

--Call other SPs if needed.

SET @logged_at = GETDATE()

INSERT INTO error_log (logged_at, severity, instance_info
, object_name, object_section, description, system_msg)
VALUES (@logged_at, 0, @abbreviation
, @description, @description, @description, @description)
SET @uom_id = SCOPE_IDENTITY()

--Call other SPs if needed.

END

Version 6.0 19
MES Middleware Extensibility Hooks Reference Configuring Pre-Hooks and Post-Hooks

As can be seen from its content, the stored procedure sp_I_Uom_Log contains all the parameters and
their properties that sp_I_Uom has, and an additional paramet er containing more contextual information.
The custom stored procedure can c omplet ely ignore the input parameters and the code inside the "begin
and end" block can be customized for individual needs. The statements in bold indicate that one or more
custom stored procedures can be called from this custom stored procedure. The concept described
above is also applicable to configuring the post-hook of type stored procedure.

Action
When a new unit of measurement (UOM) is added from the MES Client application or by using an
ArchestrA script to add the UOM, the middleware typically uses the sp_I_Uom stored proc edure to add
the new unit of meas urement. As explained in Functional Overview on page 7, the middleware first
verifies whet her any pre-hook is configured for the sp_I_Uom stored procedure. Since there is a
pre-hook sp_I_Uom_Log configured for this case, the middleware first executes the stored procedure
sp_I_Uom_Log and then evaluates the result before processing the standard middleware call sp_I_Uom
to create a new unit of measurement in the MES database.

Custom Stored Procedure Hook Raises an Error (Middleware Flow:

Stop)
This example illustrates how a custom stored procedure can be configured as a hook that can be invoked
when executing a standard stored procedure in the MES middleware.
The following example configuration is added to the Middleware Configuration Editor.

Middleware SP
Name Pre-Hook Name Pre-Hook Type Middleware Flow

sp_I_UOM sp_I_Uom_Log SP STOP

Content of the Custom Stored Procedure sp_I_Uom_Log

CREATE PROCEDURE sp_I_Uom_Log
(@description nvarchar(40)
,@abbreviation nvarchar(20)
,@last_edit_comment nvarchar(254) = NULL
,@my_arg nvarchar(40) = null
,@last_edit_at datetime OUT
,@uom_id int OUT
) AS
BEGIN
SET NOCOUNT ON
DECLARE @logged_at DATETIME

--Call other SPs if needed.

SET @logged_at = GETDATE()

INSERT INTO error_log (logged_at, severity, instance_info
, object_name, object_section, description, system_msg)
VALUES (@logged_at, 0, @abbreviation
, @description, @description, @description, @description)

SET @uom_id = SCOPE_IDENTITY()

--Call other SPs if needed.

20 Version 6.0
Configuring Pre-Hooks and Post-Hooks MES Middleware Extensibility Hooks Reference

raiserror('Error message from the custom hook stored procedure -

sp_I_Uom_Log', 16, 1)
END
GO

Action
In this case, when a new UOM is added from the MES Client application or by using an ArchestrA script
to add the UOM, the middleware executes the stored procedure sp_I_Uom_Log, and evaluates the
result before actually processing the standard middleware call sp_I_Uom to create a new unit of
measurement in the MES database. Since the Middleware Flow paramet er is set to Stop after executing
the custom (pre-hook ) stored proc edure, the sequence of execution stops and returns the following error
to the client:
Error message from the custom hook stored procedure - sp_I_Uom_Log
Note that even if there are no errors in t he custom hook stored procedure, the normal middleware call will
never be processed in this case, because the the Middleware Flow parameter is set to Stop after
executing the pre-hook call. That is, in this case, the middleware never adds the unit of measurement.

Custom Assembly That Is Not in the GAC

This example illustrates how a custom assembly that is not in the GAC can be configured as a hook and
invok ed when executing a standard stored procedure in the MES middleware.
The following example configuration is added to the Middleware Configuration Editor.

Middleware SP Middleware
Name Pre-Hook Name Pre-Hook Type Flow

sp_I_UOM C:\Temp\ TestHooks\TestHooks\bin\ ASSEMBLY STOP ON

Debug\ TestHooks.dll; TestHooksNamespace. ERROR
TestHooksClass;TestHooksMethod

The configuration in the pre-hook name can be interpreted as below:

Assembly Name/DLL Name: TestHooks.dll
Namespace: TestHooksNamespac e
Class Name: TestHooksClass
Method Name: TestHooksMethod

Content of the Code in the TestHooksClass.cs

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
namespace TestHooksNamespace
{
public class TestHooksClass
{
public TestHooksClass()
{ }
public void TestHooksMethod(string xmlSource)
{
// Compose a string that consists of three lines.
string lines = string.Format("DateTime: {0}, XMLSource: {1}",

Version 6.0 21
MES Middleware Extensibility Hooks Reference Configuring Pre-Hooks and Post-Hooks

DateTime.Now.ToString(), xmlSource);
// Write the string to a file.
using (System.IO.StreamWriter file = new
System.IO.StreamWriter("c:\\Temp\\UomLog.txt", true))
{
file.WriteLine(lines);
}
}
}
}
The value for the xmlSource parameter contains the XML message for the normal middleware event.
The structure of the XML message used for this case is listed below:
<?xml version='1.0'?>
<request>
<object>uom</object>
<msgtype>exec</msgtype>
<cmd>add</cmd>
<uom>
<session_id>119</session_id>
<description>Unit_001</description>
<abbreviation>ssss</abbreviation>
<last_edit_comment></last_edit_comment>
</uom>
<validate>1</validate>
</request>
The text output is written to the text file UomLog.txt in the format below:
DateTime: 1/2/2013 11:34:44 AM, XMLSource:
<?xmlversion='1.0'?><request><object>uom</object>
<msgtype>exec</msgtype><cmd>add</cmd><uom><session_id>119
</session_id><description>Unit_001</description>
<abbreviation>ssss</abbreviation><last_edit_comment>
</last_edit_comment></uom><validate>1</validate></request>
The concept described above is also applic able to configuring the post -hook of type assembly.

Action
When a new UOM is added from the MES Client application or by using an ArchestrA script to add the
UOM, the middleware typically uses the sp_I_Uom stored procedure to add the new unit of
measurement. As explained in Functional Overview on page 7, the middleware first verifies whether any
pre-hook is configured for the sp_I_Uom stored procedure. Since there is a pre-hook TestHooks.dll
configured for this case, the middleware first executes the method TestMethod in the TestHook s.dll
assembly and then evaluates the result before actually processing the standard middleware call
sp_I_Uom to create a new unit of meas urement in the MES databas e.

Custom Assembly Is Added to the GAC

This example illustrat es how a custom assembly that has been added to the GA C can be configured as a
hook and invoked when executing a standard stored proc edure in the MES middleware. The expectation
is that the assembly is signed with a strong-name.
The following example configuration is added to the Middleware Configuration Editor.

22 Version 6.0
Configuring Pre-Hooks and Post-Hooks MES Middleware Extensibility Hooks Reference

Middleware SP Middleware
Name Pre-Hook Name Pre-Hook Type Flow

sp_I_UOM TestHooks, version= 1.0.0.0,culture=neutral, ASSEMBLY STOP ON

processorarc hitecture= ERROR
MSIL,PublicKeyToken=23106a86e706d0ae; TestH
ooksNamespace. TestHooksClass;
TestHooksMethod

The configuration in the pre-hook name can be interpreted as below:

Assembly Name/DLL Name: TestHooks.dll
Namespace: TestHooksNamespac e
Class Name: TestHooksClass
Method Name: TestHooksMethod

Content of the Code in the TestHooksClass.cs

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
namespace TestHooksNamespace
{
public class TestHooksClass
{
public TestHooksClass()
{ }
public void TestHooksMethod(string xmlSource)
{
// Compose a string that consists of three lines.
string lines = string.Format("DateTime: {0}, XMLSource: {1}",
DateTime.Now.ToString(), xmlSource);
// Write the string to a file.
using (System.IO.StreamWriter file = new
System.IO.StreamWriter("c:\\Temp\\UomLog.txt", true))
{
file.WriteLine(lines);
}
}
}
}
The concept described above is also applic able to the post -hook of type assembly.

Action
When a new UOM is added from the MES Client application or by using an ArchestrA script to add the
UOM, the middleware typically uses the sp_I_Uom store d procedure to add the new unit of
measurement. As explained in Functional Overview on page 7, the middleware first verifies whether any
pre-hook is configured for the sp_I_Uom stored procedure. Since there is a pre-hook TestHooks.dll
configured for this case, the middleware first executes the method TestMethod in the TestHooks.dll
assembly and then evaluates the result before actually processing the standard middleware call
sp_I_Uom to create a new unit of meas urement in the MES databas e.

Version 6.0 23
 MES Middleware Extensibility Hooks Reference

C HAPTER 4
Configuring Extensibility Hooks on Multiple
Middleware Servers
The Middleware Extensibility Hooks are configured in the Extensibility Hooks tab in the Middleware
Configuration Editor, and the hooks configurations are stored in the same folder in the file
MWDBMappingsCustom.xml. The MES Middleware S erver loads the Extensibility Hooks only if the
hook parameters are configured in the MWDBMappingsCustom.xml file in its folder. When there is
more than one Middleware Server configured to connect to the same MES database, then the end user
is responsible for managing the hook configurations and keeping them in sync across all the Middleware
Servers.
For example, let’s say Middleware Server 1 has a pre -hook configured for the sp_I_Uom (Uom.Add) to
perform a pre-action before the actual sp_I_Uom is executed. Middleware Server 2 has a pre-hook
configured for the sp_U_Job_Exec_StartBatchJobs (Job_Exec.StartJob) to perform a pre-action before
the actual sp_U_Job_Exec_StartBatchJobs is executed. These two Middleware Servers are configured
to connect to the same MES database, and these two are the only two hooks configured in their
respective middleware directories.
The table below explains how the pre -hook commands are processed by both the Middleware Servers
using the example above:

Middleware Server1 Middleware Server2

Pre-Hook Execute Pre-Hook Execute

Middleware SP Name Loaded Pre-Hook Loaded Pre-Hook

sp_I_UOM Yes Yes No No

sp_U_Job_Exec _StartBatchJobs No No Yes Yes

The Middleware Server 1 processes the pre-hook for sp_I_UOM before calling the sp_I_Uom stored
procedure on the MES database, but does not process the pre-hook for
sp_U_Job_Exec _StartBatchJobs before calling this stored procedure, because Middleware Server 1
does not know anything about the pre-hook for sp_U_Job_Exec_StartBatchJobs, since the XML file in its
folder does not have any information about the hook for sp_U_Job_Exec_StartbatchJobs.
Similarly, the Middleware Server 2 processes the pre -hook for sp_U_Job_Exec_StartBatchJobs before
calling the sp_U_Job_Exec_StartBatchJobs stored procedure on the MES database, but does not
process the pre-hook for sp_I_UOM before calling this stored procedure.

Note: If the desire is to have an Extensibility Hook processed for a middleware stored procedure,
regardless of the Middleware Server that invok es the stored procedure, then the user must copy the
configuration file or manually configure t he Extensibility Hook configurations into all t he MES Middleware
Servers, thereby keeping the configuration information in sync across the Middleware Servers.

Version 6.0 25
 MES Middleware Extensibility Hooks Reference

C HAPTER 5
Frequently Asked Questions
What are hooks? What is the purpose of having hooks configured in the MES
middleware?
A hook represents a custom functionality implemented by the end user in the form of a stored procedure,
assembly, work flow, and so on. The purpose of having a hook is to allow a custom functionality to be
integrated as a part of standard MES event and ex ecute that functionality as a part of standard MES
event.
How do you determine the name of a stored procedure that corresponds to a specific
middleware event?
In most cases, the name of the MES middleware event matches the name of the MES stored procedure.
If not, they are configured in the MWDBMappings.xml file under the db_objects section. This XML file
resides in the same folder where the MES server is installed on the host machine. It is recommended to
first look in this file to find the name of the stored procedure that corresponds to the name of the
middleware event. If such a configuration is not found in this file, then the stored procedure name is
resolved automatically on-the-fly by the Middleware Server. For example, a middleware event Item.Add
corresponds to the stored procedure sp_I_Item, Attr.Update corresponds to sp_U_Attr, Ent.GetAll
corresponds to sp_SA_Ent, JobExec.DownloadS pecs corres ponds to
sp_U_Job_Exec _DownloadSpecs, and so on. See the "Middleware Configuration Editor" chapter in the
MES Installation Guide or online help for more det ails about how a middleware method is mapped to a
stored procedure.
Can stored procedure names configured in the custom database mappings tab in the
Middleware Configuration Editor be used as part of hooks? How are those stored
procedures related to hooks?
Yes, the stored procedures (names) configured in the custom dat abase mappings can be used to
configure the stored procedure hooks. The custom database mappings is a separate mechanism that
allows to map a custom stored procedure created by an end user, and t hat allows an end user to call that
custom stored procedure from the client applications using the standard XML structure used by the
middleware.
Does the Middleware Server need to be restarted if a hook configuration is modified?
Yes, whenever a hook configuration is modified, the Middleware Server needs to be restarted to reload
the changes in its memory. Otherwise, the changes are not effective until the Middleware Server is
restarted.
If there is more than one Middleware Server, does the hook information need to be
copied to more than one Middleware Server?
Yes. It is the responsibility of the end user to copy and synchronize the hooks configurations on all the
Middleware Servers.
Does the pre-hook or the post-hook mechanism support the UpdateSpecific() method in
the middleware to perform pre- or post-processing?
No. The UpdateSpecific() method in the middleware uses dynamic SQL (a SQL Updat e statement
generated when needed and not pre -compiled) to update the data in the MES database. Since there are
no stored procedures involved with the UpdateSpecific() method, pre- and post-hooks cannot be
configured and exec uted against this method.

Version 6.0 27
MES Middleware Extensibility Hooks Reference Frequently Asked Questions

Under what user name is the custom (hook) assembly executed?

The middleware calls impersonate the ArchestrA Net work user; therefore, the custom (hook) assembly is
invok ed as that user.
Do the extensibility hooks (i.e., custom stored procedures and custom DLLs)
automatically upgrade when the standard MES product is upgraded?
No. The end user is responsible for upgrading the custom stored procedures and custom DLLs to
synchronize the methods and parameters in the custom hooks with the methods and parameters in the
standard MES product.

28 Version 6.0