<?xml version="1.0" encoding="utf-8"?>
<ManualTopic ID="/baanerp/da/onlinemanual/trg_event_handling" xml:lang="en">
	<Header>
		<Title xmlns:HTML="http://www.w3.org/TR/REC-html40">Event handling</Title>
		<Keyword ContextSensitive="No"><Level1>Triggering</Level1>
			<Level2>Event</Level2>
		</Keyword>
		<Keyword ContextSensitive="No"><Level1>i-Flow</Level1>
		</Keyword>
	</Header>
	<GeneralSection><SectionTitle>Introduction</SectionTitle>
		<GeneralSection><SectionTitle>Event structure</SectionTitle>
			<List><ListIntro>An event essentially consists of the following two parts:</ListIntro>
				<ListItem>Control area: Specifies the event type, or event action, and can include other elements such as the class, or entity, of the object that was changed, the event time, or the application that generated the event. Standard event types include: <List><ListItem>Create: A new object instance was added.</ListItem>
						<ListItem>Change: An object instance was updated.</ListItem>
						<ListItem>Delete: An object instance was removed.</ListItem>
					</List>
				</ListItem>
				<ListItem>The data area contains the data of the (business) object that was impacted by the event. The data area also contains <Emphasis>components</Emphasis> and <Emphasis>attributes</Emphasis>.</ListItem>
			</List>
			<Paragraph class="Default">If the data area is filled, which is not mandatory, one component will always have one or more attributes. In addition, this component can have child components. A typical example is a sales order object, in which the main component is the sales order and the child components are the order lines.</Paragraph>
			<Paragraph class="Default">The sales order component will have attributes such as order number, order date, and Sold-to business partner (customer). The order line component will have attributes such as line number, item, quantity, and price.</Paragraph>
			<Paragraph class="Default">Attributes can have old values, new (current) values, or both. Create events typically do not have old values, while delete events do not have new values. Change events can have either old or new values.</Paragraph>
			<Important><SectionTitle>
                                    Important!
                                 </SectionTitle>
				<Paragraph class="Default">Although the logical structure of the events is stable, the technical format can change. The XSDs and XMLs in this chapter are included to illustrate the logical structure. For best results, use the event handling API, as described in "API for event handling" later in this chapter, when you use the contents of an event, because that interface must not change the event even though the XML structure can change.</Paragraph>
			</Important>
			<ExampleSection><SectionTitle>
                                    Example
                                 </SectionTitle>
				<Paragraph class="Default">The following figure illustrates the event used for a change, in this case, on a Customer object. Note that the component name, Customer, and the attributes are specific for this object. Other objects will have other values and can also have child components. Note, however, that events from Exchange will always be simple events, which are events that consist of only one component.</Paragraph>
				<Figure space-and-orientation="indented-estimated"><HTML:IMG height="318" width="696" SRC="../images/nt_screen_event_handling1.gif" path="/enterpriseserver/add-ons/da/onlinemanual" btb-count="1" btb-count2="1" btb-image-name="nt_screen_event_handling1.gif" btb-source-path="C:\SVN\docnl\Technology\EnterpriseServer~8.5\EnterpriseServer" btb-image-path="/enterpriseserver/add-ons/da/images/nt_screen_event_handling1.gif" ID="IDAHYV5B" alt="[...]" xmlns:HTML="http://www.w3.org/TR/REC-html40"/><FigCaption>XSD for change event</FigCaption>
				</Figure>
				<Paragraph class="Default">An XSD file for this structure contains the following code:</Paragraph>
				<CodeBlock space-and-orientation="indented-estimated">&lt;?xml version="1.0"?&gt;
&lt;xs:schema targetNamespace="http://www.baan.com" xmlns="http://www.baan.com" xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="unqualified" attributeFormDefault="unqualified"&gt;
    &lt;xs:element name="EventMessage" type="EventMessageType"/&gt;
    &lt;xs:complexType name="EventMessageType"&gt;
        &lt;xs:sequence&gt;
            &lt;xs:element name="ControlArea" type="ControlAreaType"/&gt;
            &lt;xs:element name="DataArea" type="DataAreaType" 
                minOccurs="0"/&gt;
        &lt;/xs:sequence&gt;
    &lt;/xs:complexType&gt;
    &lt;xs:complexType name="ControlAreaType"&gt;
        &lt;xs:sequence&gt;
            &lt;xs:element name="eventEntity" type="eventEntityDT"/&gt;
            &lt;xs:element name="eventAction" type="eventActionDT"/&gt;
            &lt;xs:element name="eventTimeStamp" type="eventTimeStampDT" 
                minOccurs="0"/&gt;
        &lt;/xs:sequence&gt;
    &lt;/xs:complexType&gt;
    &lt;xs:simpleType name="eventEntityDT"&gt;
        &lt;xs:restriction base="xs:string"/&gt;
    &lt;/xs:simpleType&gt;
    &lt;xs:simpleType name="eventActionDT"&gt;
        &lt;xs:restriction base="xs:string"/&gt;
    &lt;/xs:simpleType&gt;
    &lt;xs:simpleType name="eventTimeStampDT"&gt;
        &lt;xs:restriction base="xs:dateTime"/&gt;
    &lt;/xs:simpleType&gt;
    &lt;xs:complexType name="DataAreaType"&gt;
        &lt;xs:sequence&gt;
            &lt;xs:element name="Customer" type="CustomerType" 
                minOccurs="0" maxOccurs="unbounded"/&gt;
        &lt;/xs:sequence&gt;
    &lt;/xs:complexType&gt;
    &lt;xs:complexType name="CustomerType"&gt;
        &lt;xs:sequence&gt;
            &lt;xs:choice&gt;
                &lt;xs:sequence&gt;
                    &lt;xs:annotation&gt;
                        &lt;xs:documentation&gt;For create, delete, or 
                            other actions&lt;/xs:documentation&gt;
                    &lt;/xs:annotation&gt;
                    &lt;xs:element name="PreviousValues" 
                        type="PreviousValuesEmpty" minOccurs="0"/&gt;
                    &lt;xs:group ref="AVcustomer"/&gt;
                &lt;/xs:sequence&gt;
                &lt;xs:sequence&gt;
                    &lt;xs:annotation&gt;
                        &lt;xs:documentation&gt;For change actions
                        &lt;/xs:documentation&gt;
                    &lt;/xs:annotation&gt;
                    &lt;xs:element name="PreviousValues" 
                        type="customerPreviousValuesType"/&gt;
                    &lt;xs:group ref="AVcustomer"/&gt;
                &lt;/xs:sequence&gt;
            &lt;/xs:choice&gt;
        &lt;/xs:sequence&gt;
        &lt;xs:attribute name="actionType" type="eventActionDT" 
            use="optional"/&gt;
    &lt;/xs:complexType&gt;
    &lt;xs:complexType name="PreviousValuesEmpty"/&gt;
    &lt;xs:complexType name="customerPreviousValuesType"&gt;
        &lt;xs:sequence&gt;
            &lt;xs:group ref="AVcustomer"/&gt;
        &lt;/xs:sequence&gt;
    &lt;/xs:complexType&gt;
    &lt;xs:simpleType name="identifierDT"&gt;
        &lt;xs:restriction base="xs:boolean"/&gt;
    &lt;/xs:simpleType&gt;
    &lt;xs:group name="AVcustomer"&gt;
        &lt;xs:sequence&gt;
            &lt;xs:element name="customer" type="customerType"/&gt;
            &lt;xs:element name="address" type="addressDT" 
                minOccurs="0"/&gt;
            &lt;xs:element name="status" type="statusDT" minOccurs="0"/&gt;
        &lt;/xs:sequence&gt;
    &lt;/xs:group&gt;
    &lt;xs:complexType name="customerType"&gt;
        &lt;xs:simpleContent&gt;
            &lt;xs:extension base="customerDT"&gt;
                &lt;xs:attribute name="identifier" type="identifierDT" 
                    use="optional" fixed="true"/&gt;
            &lt;/xs:extension&gt;
        &lt;/xs:simpleContent&gt;
    &lt;/xs:complexType&gt;
    &lt;xs:simpleType name="customerDT"&gt;
        &lt;xs:restriction base="xs:long"&gt;
            &lt;xs:totalDigits value="10"/&gt;
        &lt;/xs:restriction&gt;
    &lt;/xs:simpleType&gt;
    &lt;xs:simpleType name="addressDT"&gt;
        &lt;xs:restriction base="xs:string"&gt;
            &lt;xs:maxLength value="9"/&gt;
            &lt;xs:pattern value="\p{Lu}"/&gt;
        &lt;/xs:restriction&gt;
    &lt;/xs:simpleType&gt;
    &lt;xs:simpleType name="statusDT"&gt;
        &lt;xs:restriction base="xs:string"&gt;
            &lt;xs:enumeration value="active"/&gt;
            &lt;xs:enumeration value="inactive"/&gt;
            &lt;xs:enumeration value="historic"/&gt;
        &lt;/xs:restriction&gt;
    &lt;/xs:simpleType&gt;
&lt;/xs:schema&gt;</CodeBlock>
				<Paragraph class="Default">The component names and attribute names in this XSD are dependent on the specific trigger. In this example, the component is Customer and the attributes are Customer, Address, and Status. The other parts are generic. The structure will be the same for all triggers.</Paragraph>
				<Paragraph class="Default"><Emphasis>Note:</Emphasis> The component class and attribute names will, in fact, be the ASCII files and ASCII file fields.</Paragraph>
				<Paragraph class="Default">Some examples of a change events based on this structure include the following:</Paragraph>
				<CodeBlock space-and-orientation="indented-estimated">&lt;EventMessage&gt;
        &lt;ControlArea&gt;
                &lt;eventEntity&gt;customer&lt;/eventEntity&gt;
                &lt;eventAction&gt;create&lt;/eventAction&gt;
                &lt;eventTimeStamp&gt;2004-12-17T09:17:28Z&lt;/eventTimeStamp&gt;
        &lt;/ControlArea&gt;
        &lt;DataArea&gt;
                &lt;Customer actionType="create"&gt;
                    &lt;customer&gt;2147483647&lt;/customer&gt;
                    &lt;status&gt;inactive&lt;/status&gt;
                &lt;/Customer&gt;
        &lt;/DataArea&gt;
    &lt;/EventMessage&gt;
    &lt;EventMessage&gt;
        &lt;ControlArea&gt;
                &lt;eventEntity&gt;customer&lt;/eventEntity&gt;
                &lt;eventAction&gt;change&lt;/eventAction&gt;
                &lt;eventTimeStamp&gt;2004-12-17T09:30:47Z&lt;/eventTimeStamp&gt;
        &lt;/ControlArea&gt;
        &lt;DataArea&gt;
                &lt;Customer actionType="change"&gt;
                    &lt;PreviousValues&gt;
                        &lt;customer&gt;2147483647&lt;/customer&gt;
                        &lt;status&gt;inactive&lt;/status&gt;
                    &lt;/PreviousValues&gt;
                    &lt;customer&gt;2147483647&lt;/customer&gt;
                    &lt;status&gt;active&lt;/status&gt;
                &lt;/Customer&gt;
        &lt;/DataArea&gt;
    &lt;/EventMessage&gt;

    &lt;EventMessage&gt;
        &lt;ControlArea&gt;
                &lt;eventEntity&gt;customer&lt;/eventEntity&gt;
                &lt;eventAction&gt;delete&lt;/eventAction&gt;
                &lt;eventTimeStamp&gt;2004-12-23T14:40:18Z&lt;/eventTimeStamp&gt;
        &lt;/ControlArea&gt;
        &lt;DataArea&gt;
                &lt;Customer actionType="delete"&gt;
                    &lt;PreviousValues&gt;
                        &lt;customer&gt;2147483647&lt;/customer&gt;
                        &lt;status&gt;active&lt;/status&gt;
                    &lt;/PreviousValues&gt;
                &lt;/Customer&gt;
        &lt;/DataArea&gt;
&lt;/EventMessage&gt;</CodeBlock>
				<Paragraph class="Default">The "Examples" chapter provides additional examples.</Paragraph>
			</ExampleSection>
		</GeneralSection>
	</GeneralSection>
	<GeneralSection><SectionTitle>Events from Exchange</SectionTitle>
		<GeneralSection><SectionTitle>Row events</SectionTitle>
			<Paragraph class="Default">A row event generated from the Exchange module will always have one of the standard event types: create, change, or delete. In addition, the data area will only have one single component because only one table is involved.</Paragraph>
			<Paragraph class="Default">The ASCII file name is mapped to the component name in the event. The ASCII field names are mapped to the attribute names in the event.</Paragraph>
			<Paragraph class="Default">As a result, the example provided in "Introduction," previously in this chapter, is valid for events from Exchange, except that the component and attribute names will have a maximum of eight characters and will be lowercase. In addition, if you generate the exchange scheme as described in <Emphasis></Emphasis> "To set up a trigger source" in Chapter 2, "To set up triggering," the ASCII file name, and consequently the component name, will be equal to the table code, while the ASCII field names, and consequently the attribute names, will be equal to the table field codes.</Paragraph>
		</GeneralSection>
		<GeneralSection><SectionTitle>End of Data Set event</SectionTitle>
			<Paragraph class="Default">At the end of a batch line, an End of Set event is generated if an end of batch line trigger is defined in the export trigger.</Paragraph>
			<Figure space-and-orientation="indented-estimated"><FigIntro>The following figure shows the event used at the end of an export batch line:</FigIntro>
				<HTML:IMG height="294" width="692" SRC="../images/nt_screen_event_handling2.gif" path="/enterpriseserver/add-ons/da/onlinemanual" btb-count="1" btb-count2="1" btb-image-name="nt_screen_event_handling2.gif" btb-source-path="C:\SVN\docnl\Technology\EnterpriseServer~8.5\EnterpriseServer" btb-image-path="/enterpriseserver/add-ons/da/images/nt_screen_event_handling2.gif" ID="IDAQYV5B" alt="[...]" xmlns:HTML="http://www.w3.org/TR/REC-html40"/><FigCaption>XSD for end of set event</FigCaption>
			</Figure>
			<Paragraph class="Default">An XSD file for this structure contains the following code:</Paragraph>
			<CodeBlock space-and-orientation="indented-estimated">&lt;?xml version="1.0"?&gt;
&lt;xs:schema targetNamespace="http://www.baan.com" xmlns="http://www.baan.com" xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="unqualified" attributeFormDefault="unqualified"&gt;
    &lt;xs:element name="EventMessage" type="EventMessageType"/&gt;
    &lt;xs:complexType name="EventMessageType"&gt;
        &lt;xs:sequence&gt;
            &lt;xs:element name="ControlArea" type="ControlAreaType"/&gt;
            &lt;xs:element name="DataArea" type="DataAreaType" minOccurs="0"/&gt;
        &lt;/xs:sequence&gt;
    &lt;/xs:complexType&gt;
    &lt;xs:complexType name="ControlAreaType"&gt;
        &lt;xs:sequence&gt;
            &lt;xs:element name="eventEntity" type="eventEntityDT"/&gt;
            &lt;xs:element name="eventAction" type="eventActionDT"/&gt;
            &lt;xs:element name="eventTimeStamp" type="eventTimeStampDT" minOccurs="0"/&gt;
        &lt;/xs:sequence&gt;
    &lt;/xs:complexType&gt;
    &lt;xs:simpleType name="eventEntityDT"&gt;
        &lt;xs:restriction base="xs:string"/&gt;
    &lt;/xs:simpleType&gt;
    &lt;xs:simpleType name="eventActionDT"&gt;
        &lt;xs:restriction base="xs:string"/&gt;
    &lt;/xs:simpleType&gt;
    &lt;xs:simpleType name="eventTimeStampDT"&gt;
        &lt;xs:restriction base="xs:dateTime"/&gt;
    &lt;/xs:simpleType&gt;
    &lt;xs:complexType name="DataAreaType"&gt;
        &lt;xs:sequence&gt;
            &lt;xs:element name="ExportBatchLine" type="ExportBatchLineType" minOccurs="0" maxOccurs="unbounded"/&gt;
        &lt;/xs:sequence&gt;
    &lt;/xs:complexType&gt;
    &lt;xs:complexType name="ExportBatchLineType"&gt;
        &lt;xs:sequence&gt;
            &lt;xs:group ref="AVprocess"/&gt;
        &lt;/xs:sequence&gt;
        &lt;xs:attribute name="actionType" type="eventActionDT" use="optional"/&gt;
    &lt;/xs:complexType&gt;
    &lt;xs:simpleType name="identifierDT"&gt;
        &lt;xs:restriction base="xs:boolean"/&gt;
    &lt;/xs:simpleType&gt;
    &lt;xs:group name="AVprocess"&gt;
        &lt;xs:sequence&gt;
            &lt;xs:element name="exchangeScheme" type="exchangeSchemeType"/&gt;
            &lt;xs:element name="batch" type="batchType"/&gt;
            &lt;xs:element name="batchLine" type="batchLineType"/&gt;
            &lt;xs:element name="physicalAsciiFile" type="physicalAsciiFileDT" minOccurs="0"/&gt;
        &lt;/xs:sequence&gt;
    &lt;/xs:group&gt;
    &lt;xs:complexType name="exchangeSchemeType"&gt;
        &lt;xs:simpleContent&gt;
            &lt;xs:extension base="exchangeSchemeDT"&gt;
                &lt;xs:attribute name="identifier" type="identifierDT" use="optional" fixed="true"/&gt;
            &lt;/xs:extension&gt;
        &lt;/xs:simpleContent&gt;
    &lt;/xs:complexType&gt;
    &lt;xs:complexType name="batchType"&gt;
        &lt;xs:simpleContent&gt;
            &lt;xs:extension base="batchDT"&gt;
                &lt;xs:attribute name="identifier" type="identifierDT" use="optional" fixed="true"/&gt;
            &lt;/xs:extension&gt;
        &lt;/xs:simpleContent&gt;
    &lt;/xs:complexType&gt;
    &lt;xs:complexType name="batchLineType"&gt;
        &lt;xs:simpleContent&gt;
            &lt;xs:extension base="batchLineDT"&gt;
                &lt;xs:attribute name="identifier" type="identifierDT" use="optional" fixed="true"/&gt;
            &lt;/xs:extension&gt;
        &lt;/xs:simpleContent&gt;
    &lt;/xs:complexType&gt;
    &lt;xs:simpleType name="exchangeSchemeDT"&gt;
        &lt;xs:restriction base="xs:string"&gt;
            &lt;xs:maxLength value="8"/&gt;
        &lt;/xs:restriction&gt;
    &lt;/xs:simpleType&gt;
    &lt;xs:simpleType name="batchDT"&gt;
        &lt;xs:restriction base="xs:string"/&gt;
    &lt;/xs:simpleType&gt;
    &lt;xs:simpleType name="batchLineDT"&gt;
        &lt;xs:restriction base="xs:long"/&gt;
    &lt;/xs:simpleType&gt;
    &lt;xs:simpleType name="physicalAsciiFileDT"&gt;
        &lt;xs:restriction base="xs:string"/&gt;
    &lt;/xs:simpleType&gt;
&lt;/xs:schema&gt;
</CodeBlock>
			<Paragraph class="Default">An example of an end of set event based on this structure is as follows:</Paragraph>
			<CodeBlock space-and-orientation="indented-estimated">&lt;EventMessage&gt;
    &lt;ControlArea&gt;
        &lt;eventEntity&gt;exportBatchLine&lt;/eventEntity&gt;
        &lt;eventAction&gt;endOfDataSet&lt;/eventAction&gt;
    &lt;/ControlArea&gt;
    &lt;DataArea&gt;
        &lt;ExportBatchLine actionType="endOfDataSet"&gt;
            &lt;exchangeScheme&gt;workflow&lt;/exchangeScheme&gt;
            &lt;batch&gt;BATCH&lt;/batch&gt;
            &lt;batchLine&gt;1&lt;/batchLine&gt;
            &lt;physicalAsciiFile&gt;/home/workflow/export/customer.S
            &lt;/physicalAsciiFile&gt;
        &lt;/ExportBatchLine&gt;
    &lt;/DataArea&gt;
&lt;/EventMessage&gt;
</CodeBlock>
			<Paragraph class="Default">The physicalAsciiFile will not be set if no ASCII file is created.</Paragraph>
			<Paragraph class="Default">Additional examples are provided in Chapter 4, "Examples."</Paragraph>
		</GeneralSection>
	</GeneralSection>
	<GeneralSection><SectionTitle>API for event handling</SectionTitle>
		<Paragraph class="Default">The implementation of the event handling API is stored in the <Emphasis>datrgevent</Emphasis> library.</Paragraph>
		<List><ListIntro>The library contains the following types of functions:</ListIntro>
			<ListItem>Functions to create events You can use these functions from an application customization, but also from the Exchange module.</ListItem>
			<ListItem>Functions to read (use) events and to update (change) events The trigger implementation (conditions and action) can use these functions, if required. In addition, wrapper functions are available to read or create single-component events easily.</ListItem>
			<ListItem>A function to clean up events.</ListItem>
		</List>
		<Important><SectionTitle>
                                 Important!
                              </SectionTitle>
			<Paragraph class="Default">To read events, you must only use the functions in the <Emphasis>datrgevent</Emphasis> library. The implementation can change.</Paragraph>
		</Important>
		<Paragraph class="Default">For details, refer to the specifications of the <Emphasis>datrgevent</Emphasis> library.</Paragraph>
		<Note><SectionTitle>
                                 Note
                              </SectionTitle>
			<Paragraph class="Default">You can retrieve the library specifications from the library objects. At operating-system level, use explode6.2 to locate the library object, and subsequently use bic_info6.2 with the <GUIRef href="" role="manual">-eu</GUIRef> options.</Paragraph>
			<Paragraph class="Default">For example:</Paragraph>
			<Paragraph class="Default"><Code>$ explode6.2 odatrgevent</Code>
			</Paragraph>
			<Paragraph class="Default"><Code>/mybse/application/myvrc/odatrg/otrgevent</Code>
			</Paragraph>
			<Paragraph class="Default"><Code>$ bic_info6.2 -eu /mybse/application/myvrc/odatrg/otrgevent</Code>
			</Paragraph>
			<Paragraph class="Default">This shows the documentation of the event handling functions.</Paragraph>
			<List><ListIntro>This method provides the following:</ListIntro>
				<ListItem>Prototypes Includes the function name and type, and parameters and their types, of the functions in the library</ListItem>
				<ListItem>A description of the functions and their input and output</ListItem>
				<ListItem>The preconditions and post-conditions.</ListItem>
			</List>
		</Note>
	</GeneralSection>
</ManualTopic>
