Overview

The LabVantage Enterprise Connector (referred to as "SEC" due to the former product name) provides generic message processing between LabVantage and an external source. LabVantage also provides OOB components that allow SEC to interface with SAP using a default LabVantage XML schema.

Incoming Message Processing and Reprocessing

Top

Web-Based

Processing

LabVantage Web Services receive a message from an external source.

The processAction() operation in LabVantage Web Services sends a Property List containing the message to the ProcessInMessage Action, then executes the Action.

The ProcessInMessage Action gets a Message Type SDI from the database. The Message Type specifies a "Process Action". This is the Action that will be executed by ProcessInMessage. The "Process Action" can be coded to do specific things based on the message. For example, a custom Action and SDC Rules can be used to perform tasks such as add Samples.

If the external source is SAP and you want to use LabVantage's default XML schema definition to define the message, an OOB System Action called ProcessSECMessage is provided for use as the "Process Action". Other external sources and other XML schema require that the "Process Action" be a custom Action.

The Message Type also specifies options that can be exercised during message processing (such as logging and reprocessing messages). If the Message Type allows logging, ProcessInMessage creates a Message Log entry to store information in the Property List, along with the processing status.

The "Process Action" is executed based on the Process Action Mode defined by the Message Type.

In the event of failure, an exception thrown by the "Process Action" is caught by ProcessInMessage and sent to LabVantage Web Services, which forwards a description of the exception back to the external source.

If the ProcessAction is coded to send a response to the message, the Action sends the response back to ProcessInMessage, which sends it LabVantage Web Services (as a Property List), which forwards it back to the external source.

If the Message Type allows logging of the message, a Message Log SDI in the database cuts a record containing the message id, Message Type, message (as a CLOB), status, and other information required for reprocessing the message in the event of message failure (or other reasons).

Reprocessing

Reprocessed messages are sent back to ProcessInAction, which sends them to LabVantage Web Services, which forwards them back to the external source. Note that no response can be sent to reprocessed messages because there has been no request made through LabVantage Web Services. In this case, the Message Type can be set to prohibit reprocessing.

If a user reprocesses a message, ProcessInMessage:

•	Gets information from the Message Log (such as the log id, the user who reprocessed it, whether or not reprocessing is allowed as defined by the Message Type, and the Property List).
•	Updates the Message Log with the user doing the reprocessing and the reprocessing date.
•	Determines the "Process Action" defined by the Message Type, then and executes it with the Property List retrieved from the database. The "Process Action" returns a response if configured to do so.
•	Updates the Message Log.
•	Sends a response back to the source by executing a custom "Send Action" defined by the Message Type.

File-Based

File-based messages can be processed asynchronously by setting up the ProcessFiles Action to run as a Scheduled Task, polling incoming messages contained in a file folder, then passing them to the "Process Action" (through the ProcessInMessage Action).

Outgoing Message Processing, Reprocessing, and Sending

Top

Processing

A LabVantage event (SDC Rules, custom Actions, or button onClick()) call the ProcessOutMessage Action. The event passes in a Property List containing information defined by the Message Type, plus all user-defined properties.

ProcessOutMessage uses the Message Type to determine the "Process Action", then passes this information to it and executes it.

The "Process Action" returns the message back to ProcessOutMessage. If logging is allowed, ProcessOutMessage then updates the Message Log. ProcessOutMessage manages all logging activity.

ProcessOutMessage determines if the Message Type defines a "Send Action". If so, ProcessOutMessage executes the "Send Action", which sends the message back to the awaiting caller.

Reprocessing

If ProcessOutMessage is executed by a user reprocessed the message, ProcessOutMessage:

•	Gets information from the Message Log (such as the log id, the user who reprocessed it, and whether or not reprocessing is allowed as defined by the Message Type).
•	Updates the Message Log with the user doing the reprocessing and the reprocessing date.
	Gets the Property List from the Message Log.
•	Determines the "Process Action" defined by the Message Type, then and executes it with the Property List retrieved from the database. The "Process Action" returns the message.
•	Updates the Message Log.
•	Determines if the Message Type specifies a "Send Action", if so, executes it.

Resending

If ProcessOutMessage is executed by a user resending the message, ProcessOutMessage:

•	Gets information from the Message Log (such as the log id, the user who resent it, and whether or not resendingg is allowed as defined by the Message Type).
•	Updates the Message Log with the user doing the resending and the resend date.
•	Gets the message from the Message Log.
•	Determines if the Message Type specifies a "Send Action" and, if so, executes it.

Processing and Response Status for Incoming Messages

Top

Condition	Processing Status	Response Status
Processing has not yet begun.	Not Started	None
Processing is in progress.	Processing	None
"Process Action" failed.	Error	None
"Process Action" succeeded, but no response is intended.	Complete	None
"Process Action" succeeded, response message exists, "Send Action" succeeded.	Complete	Complete
"Process Action" succeeded, response message exists, " Send Action" put on ToDo list. Not that if the Send Action is put on the ToDo List (asynchronous), it cannot return a status until it executes.	Complete	Complete
"Process Action" succeded, "Send Action" failed.	Error	Senderror
"Process Action" succeded, "Send Action" on ToDo list failed.	Complete	Complete

Message Types and Message Log

Top

Summary

SDC	Description
Message Type (LV_MessageType SDC)	Provides instructions to the ProcessInMessage Action ("Process Action" to execute, reprocessing and logging options). Setup Message Types using the Message Type page.
Message Log (LV_MessageLog SDC)	Provides access to Message logs and handles reprocessing (incoming/outgoing) and resending (outgoing). Access the Message Log using the Message Log page.

Reference Types

Top

Reference Type

Description

MessageClass

For the SEC, this defines the XML schema definition used to format the message.

The "SEC" Message Class is provided OOB, which is LabVantage's default XML schema definition.

MessageProcessStatus

Status of the message during processing (Processing, Complete, Waiting, Error):

Value	Description
Not Started	Message processing has not yet begun.
Processing	Message is currently being processed.
Complete	Message has successfully been processed.
Waiting	If asyncronously processed, message is waiting on the ToDo List.
Error	Message has failed to process.

MessageSendStatus

Status of outgoing message that have been sent (Unsent, None, Senderror, Complete):

Value	Description
None	No status will be reported when sending a message.
Unsent	Message or response has not been sent.
Senderror	Message has failed to send during the last attempt.
Complete	Message was successfully sent.

Actions

Top

These System Actions are used internally to achieve SEC functionality (click the links to view Action properties):

Action	Description
ProcessInMessage	Handles incoming messaging between LabVantage Web Services (or ProcessFiles Action) and other LabVantage components.
ProcessOutMessage	Handles outgoing messaging between LabVantage components and LabVantage Web Services.
ProcessSECMessage	OOB Action used as the "Process Action" for incoming messages from SAP that are formatted to LabVantage's XML schema definition.
CreateSECMessage	OOB Action used as the "Process Action" for outgoing messages to SAP that are formatted to LabVantage's XML schema definition.
ReprocessMessage	Reprocesses messages.
Resend Message	Resends outgoing messages.
SendMessageToFile	Puts an outgoing message into a folder.
ProcessFiles	Conducts a number of file processing tasks.
ProcessFile	Internally called by ProcessFiles (above) for each file being processed. ProcessFile contains a "readfilecontent" property to enable/disable passing of the file content to the "Process Action", and a "filecontentpropertyid" property to identify the property that holds the file content.

SEC XML Schema Definition

Top

SEC.xsd is the OOB LabVantage SEC XML schema definition for messages exchanged by SAP and LabVantage. This XSD consists of two elements: header (<Zheader> element) and Data Blocks (<ZData> element).

header

<ZSEC>

<MsgName>INSPECTIONLOTCREATE</MsgName>

...

</Zheader>

The following XML elements of the header are significant:

XML Element	Description
MsgID	Unique identifier generated by the SAP client (for incoming messages) or LabVantage (for outgoing messages).
MsgVersion	Version of the message.
MsgType	GEN stands for GENERAL. This is the only message type currently supported.
MsgName	This is identical to the identifier of the SAP Message Type.
MsgFlow	Indicates the direction of the message. "IN" and "OUT" indicates that this is an Incoming or Outgoing message for LabVantage, respectively.
MsgRefID	Message tag embedded in the message.

Data Blocks

<ZData>

<ParamName>INSPECTIONLOTDETAILS</ParamName>

<ColumnKey>PRUEFLOS</ColumnKey>

<ColumnType>STRING</ColumnType>

</ZColumn>

...

</ZColumns>

...

</ZData>

Structure of data blocks:

XML Element	Description
ZData	The data component of the message consists of a series of "data blocks" represented by <ZData> elements.
ParamName	Unique identifier for each data block. Note that a single message can have several data blocks with the same ParamName.
Key	Unique key associated with each data block.
Ref	Hierarchical data is represented by the child data block having a <Ref> element that refers to the <Key> of the parent data block.
ZColumns	Each data block has a series of columns specified by <ZColumns> elements.
ZColumn	Each <ZColumn> element defines <ColumnKey> (keyid), <ColumnVal> (value), and <ColumnType> (data type) elements.

As mentioned in the table above, the hierarchical relationship between data is established using the Key and Ref elements. For example, if the XML message has Material and Component data blocks, the relationship between Material data and Component data is established by the Ref element in the Component block referring to the Key in the Material data block:

<ZData>

<ParamName>COMPONENT</ParamName>

<Ref>1</Ref>

...

</ZColumns>

...

</ZData>

<ZData>

<ParamName>MATERIAL</ParamName>

<Key>1</Key>

...

</ZColumns>

...

</ZData>

Using the SAPMsgType

Top

Overview

Incoming messages from SAP that are formatted to LabVantage's XML schema definition use the ProcessSECMessage Action as the "Process Action". For incoming messages, the SAPMsgType parses the message and:

•	Maps the SAP message columns to LabVantage data sets. Note that these are not LabVantage "Data Sets", which are Parameter List instances. These are simply retruned result sets.
•	Map the LabVantage data sets to Action properties.
•	Executes custom Actions that have been configured to process the messages.

Outgoing messages to SAP that are formatted to LabVantage's XML schema definition use the CreateSECMessage Action as the "Process Action". For outgoing messages, the SAPMsgType parses the message and:

•	Queries LabVantage and builds data sets.
•	Maps the LabVantage data sets to SAP message columns.
•	Generates an XML formatted to LabVantage's XML schema definition.

Incoming Message Example 1

Consider an incoming message that has data blocks for Materials that must be added to LabVantage.

Step 1

Define the structure of the incoming XML message (with the SAP data blocks and columns).

•	The header has the MSGNAME specified as "AddMaterial".
•	The data corresponding to a new material is specified in a <ZData> element with <ParamName> as "Material". SAP sends the MATID and DESCRIPTION for each material that needs to be added. Note that the MATID SAP column corresponds to s_materialid in the Material SDC and DESCRIPTION corresponds to materialdesc in the Material SDC.

This incoming SAP Message (below) must be mapped to LabVantage by creating a new SAP Message Type with the identifier "AddMaterial":

<ZSEC>

<MsgName>AddMaterial</MsgName>

</Zheader>

<ZData>

<ParamName>Material</ParamName>

<ColumnKey>MATID</ColumnKey>

<ColumnType>STRING</ColumnType>

<ColumnVal>material1</ColumnVal>

</ZColumn>

<ColumnKey>DESCRIPTION</ColumnKey>

<ColumnType>STRING</ColumnType>

</ZColumn>

</ZColumns>

</ZData>

Step 2

Select System Admin → System Tools → SAP Msg Type. Create a new SAP Message Type by clicking the Add button. Specify the SAP Msg Type, Type, and Direction fields as shown below. Note that SAP Msg Type is identical to the MsgName specified in the incoming message.

Select System Admin → System Tools → Message Type. Create a non SAP Message Type (with the same name) to process the "ProcessSECMessage" Action.

Step 3

For each unique ParamName in the XML message, add a corresponding Query in LabVantage. In this example, the incoming message has a single ParamName ("Material").

Add a Query. In this example, SAP Query Id is "Materials", and the ParamName "Material" is entered in the Data Block field. Note that SAP Query Id is any identifier that is used to identify the dataset that is internally created by ProcessSECMessage from all "Material" data blocks in the incoming SAP Message.

Step 4

Specify the mapping from the SAP columns (from the data block) to the LabVantage columns. Note that the "SAP Column" must correspond to the relevant ColumnKey in the XML message. Also note that "LabVantage Column" is any alphanumeric string that identifies the LabVantage columns in the subsequent configuration steps. In this example, the dataset "Materials" created by ProcessSECMessage will have the columns "materialid" and "materialdesc", which correspond to MATID and DESCRIPTION columns in the SAP Message.

Step 5

The next step is to configure the Actions that do the actual processing of the message. In this example, we now configure the Action and relevant properties to "Add" the materials using the AddSDI Action.

First, add the Action "AddSDI" (Version 1) to the "Actions" section. Note the "Action Instance" number associated with this Action... select this first.
Specify the input properties to the Action and their values. The values for the properties can be one of the following:

•

Hardcoded values (as in the case of "sdcid" property in the figure below).

•

Values from datasets constructed from the data blocks in the incoming message. For example, materialids from dataset "Material" can be passed as keyid1 to the AddSDI action by specifying the value field as "{Material.materialid}". The syntax for this is:

{<SAP Query Id>.<sapphire column id>}

Do not forget the surrounding curly braces.

Incoming Message Example 2

Consider that an incoming message contains Materials and their associated Components that must be added to LabVantage.

Step 1

Define the structure of the XML Message that is sent by SAP to LabVantage:

<ZData>

<ParamName>COMPONENT</ParamName>

<ColumnKey>COMPID</ColumnKey>

<ColumnType>STRING</ColumnType>

<ColumnVal>component1</ColumnVal>

</ZColumn>

<ColumnKey>DESCRIPTION</ColumnKey>

<ColumnType>STRING</ColumnType>

</ZColumn>

<ColumnKey>QUANTITY</ColumnKey>

<ColumnType>STRING</ColumnType>

</ZColumn>

<ColumnKey>UNITS</ColumnKey>

<ColumnType>STRING</ColumnType>

</ZColumn>

</ZColumns>

</ZData>

Step 2

Create the SAP Message Type and specify the mapping between the data blocks in incoming message and the dataset in LabVantage. The mapping between LabVantage columns and SAP columns is done as shown below. For every incoming message, the ProcessSAPMessage Action creates two datasets ("Material" and "Component"), which contain the LabVantage columns specified below.

Step 3

There are some situations when you must establish the relationship between data blocks using the Key and Ref fields. This is accomplished by defining a "Join".

To establish the relationship between the input Materials and Components, you could define a new dataset "MaterialComponents" by joining the "Material" and "Component" queries (see below). You can specify a join on columns configured in the queries, or use the implicit relationship between ZData blocks in the incoming message (using the Key/Ref columns) by joining the datasets as shown below.

The columns to be added to this new dataset are defined in the Filter:

The newly configured MaterialComponents dataset would have the "join" of "Material" and "Component" datasets.

Suppose the incoming message has:

•	Tthree materials with identifiers material1, material2, and material3.
•	Seven components comp1, comp2,comp3, comp4 (having Ref pointing to material1); comp5 (having Ref pointing to material2); and comp6,comp7 (having Ref pointing to material3).

The "MaterialComponents" dataset would then have:

materialid=material1;material1;material1;material1;material2;material3;material3;
materialdesc=<desc1>;<desc1>;<desc1>;<desc1>;<desc2>;<desc3>;<desc3>;
componentid=comp1;comp2;comp3;comp4;comp5;comp6;comp7;
componentdesc=<desc1>;<desc2>;<desc3>;<desc4>;<desc5>;<desc6>;<desc7>;
compmaterialid=material1;material1;material1;material1;material2;material3;material3;

You can refer to the values from this new dataset in the "Action Property" values column as shown below:

Outgoing Message Example 1

This example creates a very simple outgoing message. All Materials from LabVantage are queried and the corresponding data blocks are sent to the SAP client. In particular, the s_materialid and materialdesc columns from Material SDIs are sent back to the SAP client.

Step 1

Enter the SAP Msg Type details, indicating the direction as "OUT". In the case of file-based communication, the default output path for all outbound messages of this SAP Message Type, as well as the filename pattern, are configured. The filename pattern is the prefix appended to the output file name. The filename has the structure:

<filename pattern><uuid generated by SEC>.xml

Step 2

Enter a SAP Query Id that defines the LabVantage data to be queried (it can be a predefined LabVantage Query). In this case, we choose the "All Material" Query based on the "Material" SDC. Enter the Data Block name that corresponds to ParamName in the data block sent back to the SAP client.

Step 3

Add Column Maps to indicate the columns from the MATERIALS query that must be sent back to the SAP Client, and their SAP Columns (the names that appear as Column Keys for each of them). Note that "LabVantage Column" corresponds to the database column name retrieved by the "All Materials" query.

Here is an example of the header that might be created by the outgoing message:

<MsgName>MaterialOut</MsgName>

<MsgID>ADRAE4H7uAQTSGAYPVOO</MsgID>

...

</Zheader>

This is an example of each ZData block for a Material found in the LabVantage database:

<ZData>

<ParamName>MATERIAL_DATA</ParamName>

<ColumnKey>DESCRIPTION</ColumnKey>

<ColumnType>STRING</ColumnType>

</ZColumn>

<ColumnKey>MATID</ColumnKey>

<ColumnType>STRING</ColumnType>

</ZColumn>

</ZColumns>

</ZData>

Outgoing Message Example 2

The next example illustrates the use of custom SQL queries with variables. The response includes the details of a single Material identified by the input variable "matid".

Step 1

Define a new SAP Message Type with the identifier "SingleMaterialOut", and the direction set to "OUT".

Step 2

Define a query "SingleMaterialQuery" by clicking the Add button and entering the custom SQL query with the input variable specified in [] braces. Do not forget the quotes around the variable value. In this example, the custom sql query is:

select materialdesc from s_material where s_materialid='[matid]'

The custom query retrieves the materialdesc column from the s_material table, where s_materialid corresponds to the variable [matid]. Note that the value of matid is sent as an input property to the CreateSECMessage Action.

Enter the data block as "MATERIAL", which appears as the ParamName in the data block in the outgoing message.

Step 3

Define the variable in the Variables tab. Note that the variable can be given a hardcoded value by specifying the default value. As mentioned above, at runtime, the value for the variable is passed as an input property to the CreateSECMessage Action.

Step 4

Define the column map as shown below. Note that "LabVantage Column" corresponds to the database column name retrieved by "SingleMaterialQuery", i.e., "materialdesc". The column map specifies that materialdesc is referred to as "DESCRIPTION" in the data block of the outgoing message.

Here is a sample ZData block generated by CreateSAPMessage for this SAP Message Type. Note that the call to CreateSAPMessage must include the property "matid". The value of this property is substituted into the query.

<MsgName>SingleMaterialOut</MsgName>

<MsgID>HUE7LKLTu4BF6DXOFH84</MsgID>

</Zheader>

<ZData>

<ParamName>MATERIAL</ParamName>

<ColumnKey>DESCRIPTION</ColumnKey>

<ColumnType>STRING</ColumnType>

</ZColumn>

</ZColumns>

</ZData

Outgoing Message: Example 3

This example uses the output of one query as a variable in another query. In general, this configures a SAP Message Type that retrieves a Material identified by an incoming property called "matid" (this is an input to the CreateSECMessage Action). It also retrieves information about the Components for the Material SDI.

Step 1

Create a new SAP Msg Type and add the first query with SAP Query Id set to "material" and the Custom SQL set to

select s_materialid, materialdesc FROM s_material where s_materialid='[matid]'

Step 2

Create another query with SAP Query Id set to "component" and the Custom SQL column defined as:

select s_componentid, s_materialid, amount, unitsid FROM s_materials_component where s_materialid = '[mymaterial]'

Note that this query refers to a new variable "mymaterial", which is defined in the variables tab as coming from the output of the previous query. This is done by specifying the "Source SAP Query" and "Source Column" properties as shown below.

Step 3

Configure the column map for the two data blocks:

Step 4

These are the data blocks for MATERIAL and COMPONENT generated by the CreateSECMessage Action with the input property "matid" sent as "material1":

<ZData>

<ParamName>MATERIAL</ParamName>

<ColumnKey>DESCRIPTION</ColumnKey>

<ColumnType>STRING</ColumnType>

</ZColumn>

<ColumnKey>MATID</ColumnKey>

<ColumnType>STRING</ColumnType>

</ZColumn>

</ZColumns>

</ZData>

<ZData>

<ParamName>COMPONENT</ParamName>

<ColumnKey>COMPID</ColumnKey>

<ColumnType>STRING</ColumnType>

</ZColumn>

<ColumnKey>QUANTITY</ColumnKey>

<ColumnType>STRING</ColumnType>

</ZColumn>

<ColumnKey>NUMBER</ColumnKey>

<ColumnType>STRING</ColumnType>

</ZColumn>

</ZColumns>

</ZData>

Step 5

Note that the COMPONENT is the child data block, but does not have the <Ref> element set correctly. This can be achieved by configuring the "Join" as shown below.

This fixes the missing Ref key issue:

<ZData>

<ParamName>COMPONENT</ParamName>

<ColumnKey>COMPID</ColumnKey>

<ColumnType>STRING</ColumnType>

</ZColumn>

<ColumnKey>QUANTITY</ColumnKey>

<ColumnType>STRING</ColumnType>

</ZColumn>

<ColumnKey>NUMBER</ColumnKey>

<ColumnType>STRING</ColumnType>

</ZColumn>

</ZColumns>

</ZData>

LabVantage Enterprise Connector

Content

Overview

Incoming Message Processing and Reprocessing

Web-Based

File-Based

Outgoing Message Processing, Reprocessing, and Sending

Processing

Reprocessing

Resending

Processing and Response Status for Incoming Messages

Message Types and Message Log

Summary

Reference Types

Actions

SEC XML Schema Definition

Using the SAPMsgType

Overview

Incoming Message Example 1

Incoming Message Example 2

Outgoing Message Example 1

Outgoing Message Example 2

Outgoing Message: Example 3