Developer's Guide for BDEs for Infor ERP LN · About this Guide This document is a Developer’s...

Infor Integration 6.2

Developer's Guide for BDEs for Infor ERP LN

Copyright © 2007 Infor Global Technology Solutions GmbH and/or its affiliates and subsidiaries All rights reserved. The word and design marks set forth herein are trademarks and/or registered trademarks of Infor Global Solutions Technology GmbH and/or its affiliates and subsidiaries. All rights reserved. All other trademarks listed herein are the property of their respective owners.

Important Notices The material contained in this publication (including any supplementary information) constitutes and contains confidential and proprietary information of Infor Global Solutions.

By gaining access to the attached, you acknowledge and agree that the material (including any modification, translation or adaptation of the material) and all copyright, trade secrets and all other right, title and interest therein, are the sole property of Infor Global Solutions and that you shall not gain right, title or interest in the material (including any modification, translation or adaptation of the material) by virtue of your review thereof other than the non-exclusive right to use the material solely in connection with and the furtherance of your license and use of software made available to your company from Infor Global Solutions pursuant to a separate agreement (“Purpose”).

In addition, by accessing the enclosed material, you acknowledge and agree that you are required to maintain such material in strict confidence and that your use of such material is limited to the Purpose described above.

Although Infor Global Solutions has taken due care to ensure that the material included in this publication is accurate and complete, Infor Global Solutions cannot warrant that the information contained in this publication is complete, does not contain typographical or other errors, or will meet your specific requirements. As such, Infor Global Solutions does not assume and hereby disclaims all liability, consequential or otherwise, for any loss or damage to any person or entity which is caused by or relates to errors or omissions in this publication (including any supplementary information), whether such errors or omissions result from negligence, accident or any other cause.

Trademark Acknowledgements

All other company, product, trade or service names referenced may be registered trademarks or trademarks of their respective owners.

Publication Information

Document code: U9066C US

Release: Infor Integration 6.2

Publication date: July 07

Table of Contents

Chapter 1 Introduction............................................................................................................. 1-1 Related documents .................................................................................................................... 1-1 Acronyms ................................................................................................................................... 1-1

Chapter 2 To Create BDEs for Infor ERP LN.......................................................................... 2-1 To use the Table Importer.......................................................................................................... 2-1

Prerequisites ........................................................................................................................ 2-2 Import tables ........................................................................................................................ 2-2

To model the Business Interface Implementation ...................................................................... 2-2 Overview.............................................................................................................................. 2-2 Component and Attribute Implementations.......................................................................... 2-3 Methods and method arguments ......................................................................................... 2-4 Referential Integrity Methods ............................................................................................... 2-8 Other guidelines................................................................................................................. 2-11

To generate BDE runtime ........................................................................................................ 2-12 Prerequisites ...................................................................................................................... 2-12 To generate the runtime..................................................................................................... 2-14 To delete or expire BDE Runtime ...................................................................................... 2-15 Notes ................................................................................................................................. 2-16

To test BDE runtime................................................................................................................. 2-16 General notes .................................................................................................................... 2-16 To test a changed Implementation..................................................................................... 2-16 Event publishing................................................................................................................. 2-17

Troubleshooting ....................................................................................................................... 2-19 Overview............................................................................................................................ 2-19

ii | Table of Contents

Overview of the implementation in ERP LN ....................................................................... 2-20 Generation issues .............................................................................................................. 2-20

Chapter 3 To Use Hooks for Infor ERP LN ............................................................................. 3-1 To use Libraries (DLLs).............................................................................................................. 3-1

To use Includes.................................................................................................................... 3-1 To use subfunctions............................................................................................................. 3-2 To use global variables ........................................................................................................ 3-3 Transactions ........................................................................................................................ 3-3

Attribute hooks ........................................................................................................................... 3-3 Guidelines ............................................................................................................................ 3-4 On get/set hooks.................................................................................................................. 3-7 Conversion hooks .............................................................................................................. 3-13 Standard Conversions ....................................................................................................... 3-14 Default value hooks ........................................................................................................... 3-18 Before/after get/set hooks.................................................................................................. 3-19

Filter hooks .............................................................................................................................. 3-20 Method hooks .......................................................................................................................... 3-20

General Guidelines ............................................................................................................ 3-21 To use method arguments for top-down and bottom-up methods ..................................... 3-21 To use standard control data ............................................................................................. 3-23 Before execute method...................................................................................................... 3-24 On execute method............................................................................................................ 3-26 After execute method......................................................................................................... 3-27 To use hooks for batch methods........................................................................................ 3-27

To use multiple implementations.............................................................................................. 3-31 How to model ..................................................................................................................... 3-31 Example for Event Publishing ............................................................................................ 3-33 Required method hooks..................................................................................................... 3-35

Chapter 4 To Generate Events from the Application............................................................. 4-1 PublishEvent .............................................................................................................................. 4-3 ShowAndPublishEvent............................................................................................................... 4-5

Table of Contents | iii

Protected method................................................................................................................. 4-5 ShowAndPublishStandardEvent ................................................................................................ 4-8

Introduction .......................................................................................................................... 4-8 How to model the BII to publish standard events from the application................................. 4-9 How to adapt the application to publish standard events ................................................... 4-10 Filtering Notes.................................................................................................................... 4-11

Chapter 5 To Import from BOR Repository............................................................................ 5-1 Introduction ................................................................................................................................ 5-1 Prerequisites .............................................................................................................................. 5-1 To import from BOR................................................................................................................... 5-2 Post-import................................................................................................................................. 5-2 Compatibility at runtime.............................................................................................................. 5-3

Chapter 6 Event Publishing Deployment ............................................................................... 6-1 What happens in ERP LN .......................................................................................................... 6-1

User interface....................................................................................................................... 6-2 Detecting and publishing events .......................................................................................... 6-2 To publish application events............................................................................................... 6-3

Troubleshooting ......................................................................................................................... 6-4 To perform tracing................................................................................................................ 6-4

About this Guide

This document is a Developer’s Guide that describes how to develop and implement BDE business interfaces for Infor ERP LN application servers, using the BDE development environment of Integration Studio.

To understand and use this guide, you require general knowledge about Business Data Entity (BDE) interfaces and ERP LN.

This document contains the following chapters:

Chapter 1, “Introduction,” provides a general introduction to BDE business interfaces and to this document.

Chapter 2, “To Create BDEs for Infor ERP LN,” describes how to use the Integration Studio to create business interface implementations specifically for ERP LN application servers.

Chapter 3, “To Use Hooks for Infor ERP LN,” describes how to write BDE-specific logic in hooks.

Chapter 4, “To Generate Events from the Application,” describes how to adapt an ERP LN application package to publish application-specific events for a BDE.

Chapter 5, “To Import from the BOR Repository,” describes how to migrate existing ERP LN BDEs from the BOR to the Integration Studio.

Chapter 6, “Event Publishing Deployment,” describes how to use the event publishing mechanism at runtime. This information is relevant for testing a BDE having event publishing methods.

Send us your comments

We continually review and improve our documentation. Any remarks/requests for information concerning this document or topic are appreciated. Please e-mail your comments to [email protected].

mailto:[email protected]?subject=Documentation

vi | Table of Contents

In your e-mail, refer to the document code and title. More specific information will enable us to process feedback efficiently.

Table of Contents | vii

1 Chapter 1 Introduction

This document describes how to use Integration Studio to develop Business Data Entity (BDE) interfaces for Infor ERP LN application servers. This document also describes how to use ERP LN BDE Implementation Generator to generate BDE runtime code to implement the developed BDEs on these application servers.

This document is valid for the following product versions:

Infor Enterprise Server 8.3, or higher

Integration Studio 6.1, as available in Infor Integration 6.2

When you use FP3, install all components as listed in solution 213717.

Caution: Although most functionality for BDE development is available in Integration Studio 6.0, do not use that version when developing BDEs for ERP LN.

Related documents

Online Help of Integration Studio

Event Publishing Deployment Guide (U8780A US)

Acronyms

Acronym Description

BDE Business Data Entity

BI Business Interface

1-2 | Introduction

BID Business Interface Definitions

BII Business Interface Implementation

ERP Enterprise Resource Planning

FP Feature Pack

2 Chapter 2 To Create BDEs for Infor ERP LN

The process to model business interface implementations in Integration Studio is the essentially the same for any application server.

The general steps in the procedure are:

1 Import the required table definitions from the application server from a specified business interface definition (BID).

2 Define the mapping in the business interface implementation (BII)

3 Generate the implementation for the application server.

Alternatively:

1 Import the required table definitions from the application server.

2 Generate a default BID and BII.

3 Adapt the BID and BII to your needs.

4 Generate the implementation for the application server.

For details, refer to the Integration Studio online Help.

This chapter only provides information specific to ERP LN.

To use the Table Importer

The following sections describe the process to use the Integration Studio Table Importer.

2-2 | To Create BDEs for Infor ERP LN

Prerequisites

You can only use the Integration Studio Table Importer if you have development authorizations. In other words, you can only import tables if you can also view the tables in the Table Definitions (ttadv4520m000) session.

Before you use the Table Importer, specify the BusComponent for the runtime repository in the SSA Connectivity preferences: On the Window menu, click Preferences SSA Connectivity.

On the Runtime Repository page, in the BusComponent field, specify a BusComponent that refers to company 000 of the ERP LN environment that contains the tables to be imported. Make sure the BusComponent is installed and running before you use the importer.

Finally, an interface project must be available or created to import the tables into.

Import tables

To import tables from an ERP LN runtime repository, take the following steps:

1 Right-click the project that must contain the imported definitions and, on the shortcut menu, click Import….

2 Click SSA Table and click Next.

If you set up the connection to the ERP LN environment correctly, as described previously, Integration Studio lists the available tables in ERP LN. The list is based on the user’s package combination. As a result, you will not see tables from packages or package versions that are not included in the package combination.

3 Select the tables you want to import.

4 Click Finish to import.

To model the Business Interface Implementation

Overview

If you create a Business Interface Implementation (BII) for ERP LN, you must take a number of factors into account. The ERP LN BDE Implementation Generator checks several, but not all, of these factors automatically. The following sections describe the most significant constraints.

To Create BDEs for Infor ERP LN | 2-3

Component and Attribute Implementations

Identifiers

If a component maps to a table, then the identifying attributes for that component must map to the identifying columns of the table.

Aggregated Components

If the parent or child component is mapped to a table, the following requirements apply:

Unrelated attribute implementations must be defined for each identifying attribute that is not linked to the component’s identifiers, but is related to the identifier of a parent component.

An aggregation relation must be defined. The relationship implementation attributes in that aggregation relation must relate to identifying columns of the parent and child. Each of the parent’s identifiers must be used in that aggregation relation. Calculated attributes must not be used to define the aggregation relation.

Non-Root Tables

If you use a non-root table, the identifier of the non-root table must precisely match the identifier of the root table.

Data Types

Every attribute implementation must have a data type specified, unless the attribute implementation is linked directly to a table column. A data type used in a BII must always have a native data type that contains an existing ERP LN domain.

If standard conversion is applicable, for example, UTC, boolean, enumerate, or text, the public data type must match that conversion, unless a conversion hook is specified. If no standard conversion is applicable, the public data type must match the native data type (domain), unless a conversion hook is specified.

Data Types having Dimensions

Dimensions (array) use is not supported for ERP LN, except for table columns. To use array columns, you must apply the Additional Instructions property of the attribute implementation that maps to the array column.

For example, a table has a column prcs (Prices). Three attributes are defined: costPrice, localPrice and cataloguePrice. These attributes must be mapped to the first three array elements of the prcs column. To achieve this,


you must map costPrice to column prcs and enter value "1" for the Additional Instruction property of the costPrice attribute implementation. For localPrice, enter value “2” and for cataloguePrice, enter value “3”.

The attributes and attribute implementations use a data type with no dimensions. Only the data type of the table column will have dimensions.

The Import from BOR (see Chapter 5, "To import from the BOR Repository") will include direct mappings from attribute implementations to table columns. In case the mapping is to an array element, the Additional Instruction is filled automatically based on the information from the BOR.

Attribute Grouping

If one attribute from a group is mandatory then the group must also be mandatory.

If an attribute group is mandatory it must contain at least one mandatory attribute.

If an attribute group is read-only, all the group's children must be read-only as well.

Methods and method arguments

Method dependencies

If you implement You must also implement Notes

SubscribeEvent Show Unless the SubscribeEvent has an on-execute hook and no default behavior.

SubscribeEvent PublishEvent

SubscribeList List

SubscribeList PublishEvent

Show List

Change Create, Delete Unless the BID has no subcomponents

Delete Show, Change Unless the BID has no subcomponents


Method implementations per component

Methods that have processing scope Batch must only be implemented on the top-level component.

If a method is implemented on a subcomponent, the method must also be implemented on the method’s parents.

Method arguments

ERP LN does not support method arguments with scope Unknown, Result Set, or Return.

In addition, you cannot use controlling attributes as method arguments for ERP LN, with the exception of standard controlling attributes of standard methods, which are not explicitly defined in the Integration Studio.

The following table lists the requirements for the method argument scope for each method.

Method Method argument implementations

List Scope Out, except for unrelated attribute implementations that represent the identifiers of parent components, which must have scope Inout.

Show Scope Out, except for identifying attribute implementations, which must have scope Inout.

Create Scope In or Inout, except for attributes for which the value is generated in ERP LN, which must have scope Out.

Change Scope In or Inout, except for identifying attributes, which must have scope In.

Delete Scope In. Only method argument implementations exist for identifying attributes.

SubscribeEvent No arguments

UnsubscribeEvent No arguments

SubscribeList No arguments

PublishEvent Scope In

OnEvent Scope In

CreateRef Scope In; only method argument implementations exist for identifying attributes.


DeleteRef Scope In; only method argument implementations exist for identifying attributes.

SupportsProcessingScope No implementation needed

SupportsReferentialIntegrity No implementation needed

Method argument sequence

For each component, the sequence, or position, of the identifying PublishEvent arguments must match sequence of the identifying Show arguments.

Method Argument Implementations

For each method implementation having arguments, each of the component’s identifiers must be available as a parameter (input, input/output or output, depending on the method).

List and Show methods

For the List and Show methods, only the method argument implementations are used. Other aspects, such as method hooks, are unused. As a result, no customized List and Show implementation is possible. In addition, if a List or Show is implemented, each component must map to a table.

List and Show must have the same method arguments in the same sequence.

OnEvent method

For the OnEvent method, a default implementation is available for:

Standard event actions:

Create

Change

Delete

Specific event actions, in which case the request is forwarded to the corresponding method, unless another implementation is coded in the OnEvent on execute hook.

For example, a ‘change’ event is by default processed by invoking the ‘Change’ method, and an ‘approve’ event is by default processed by invoking the ‘Approve’ method.


No default implementation is currently available for List events. Note that you cannot forward List events to the List method.

Note: The default implementation for handling of create events may cause problems in case of generated data. For example, if an order number is automatically generated in the Create method, but a create event is received from another application which already contains an order number, the order number from the event is unused. This means the corresponding orders in the applications will have a different number. To avoid this, you must handle the create event in the on execute hook for the OnEvent method.

Standard Event Publishing

To publish events from ERP LN, you can usually rely on the standard implementation of the event publishing mechanism. In this case, however, you must realize that changes on BDE instances in ERP LN are only detected if they correspond to changes on one or more ERP LN table columns. This means that when you use the standard event publishing, at least one BDE component must be mapped to a database table.

Regarding calculated attributes please note the following.

Standard event publishing uses the calculations as modelled in the BDE, based in the assumption that the calculation is modelled completely. So, if you set the relevant attribute implementations that are mapped one-to-one on table columns, and you subsequently get the public attribute that is mapped to those attribute implementations, you must get the right value.

Consequently, change events can not be detected if 'work-arounds' using hand-crafted code are implemented, such as:

Coding calculation logic in the wrong place in the BDE hooks.

Using values from other table columns or attributes that are not defined as ‘used attributes’.

Using an attribute that is mapped to nothing, but in the implementation code selects data from the BDE's table(s). For example, for an Order line attribute, program an SQL query on the Order header table to calculate the value, or invoke an existing library function that does something like that.

Processing order

The processing order for standard methods must be as follows:

Method Processing Order


List topDown

batch: Only if the method has an on execute hook and no default behavior *

Show topDown

batch: Only if the method has an on execute hook and no default behavior *

Create topDown

batch: Only if the method has an on execute hook and no default behavior

Change topDown


Delete topDown


SubscribeEvent batch

UnsubscribeEvent batch

SubscribeList batch

PublishEvent batch

OnEvent batch

CreateRef topDown or batch (batch only if the method has an on execute hook and no default behavior)

DeleteRef bottomUp or batch (batch only if the method has an on execute hook and no default behavior)

SupportsProcessingScope No implementation needed

SupportsReferentialIntegrity No implementation needed

* Note that you can only use a batch implementation for Show if the List is also a batch method, and vice versa.

Referential Integrity Methods

Introduction

When using the Business Object Repository, referential integrity tables were automatically generated when converting to runtime. This is not the case


anymore in Integration Studio. This section describes how to set up referential integrity methods.

Important

According to the definition of the DeleteRef method in the standard BDE specification, all references for a specific referenceID can be deleted by using no or an empty data area. Currently, however, this functionality is unsupported in ERP LN. Instead, you must delete all references by explicitly specifying the BDE instances (or component instances) for which a reference was defined. In other words, the data area used for the CreateRef must also be used for the corresponding DeleteRef method.

Suppose, for example, a BII exists for ERP LN, in which two components are defined, called ‘Order’ and ‘OrderLine’. These components map to the following table columns:

Component Attribute / Attribute Implementation

Table Column

Order orderNumber ppmmm001 orno

OrderLine orderNumber (not a public attribute)

ppmmm002 orno

OrderLine lineNumber ppmmm002 lino The following sections show how to implement the CreateRef and DeleteRef methods for both the Order and the OrderLine.

Table Definitions and DALs

In ERP LN, create two tables. You must create the tables in a VRC that is equal to, or is a predecessor of, the VRC that will contain the generated libraries for the ERP LN BDE implementation.

The tables must have the following definition:

Table ppmmm901 – External References for ppmmm001

Column Domain Notes

orno Same as ppmmm001.orno

mandatory

ref_rkey A string(40) domain such as tcmcs.st40

mandatory

cmba n/a combined (orno, ref_rkey), primary


key

cmbb n/a combined (orno), reference to ppmmm001.orno, mandatory reference using lookup check

Note

Strictly speaking the combined columns are not needed in this case, but they are used to keep the definition consistent for all referential integrity tables.

You must always define a mandatory reference to the component’s root table. If you do not define such a reference, the CreateRef will have no effect at all, because the referential integrity cannot be checked.

Table ppmmm901 – External References for ppmmm001

Column Domain Notes

orno Same as ppmmm002.orno

mandatory, part of primary key

lino Same as ppmmm002.orno


ref_rkey A string(40) domain such as tcmcs.st40


cmba n/a combined (orno, lino, ref_rkey), primary key

cmbb n/a combined (orno, lino), reference to ppmmm002.cmba (orno, lino), mandatory reference using lookup check

Convert the table definitions to runtime and, if required, create the tables in the companies. Also create a DAL (Data Access Layer) script for each table.

Important: The column names for ref_rkey and the identifiers must be as specified above. In other words, the Reference Key column must always be called ‘ref_rkey’, and the identifier columns must always have the same code as the columns for the component’s root table. This implies that you cannot define reference tables for BIIs that are not mapped to (other) tables.

Note

In theory you can define reference tables for BIIs that do not map to tables. In that case, however, the referential integrity is not checked. The fact is that the


referential integrity cannot be checked if the data model does not contain a reference from the reference table to the BDE component’s root table.

BII

In Integration Studio, import the tables. Link them to the corresponding components and set the Is Referential Integrity Table property to ‘true’. The Is Root Table property must be ‘false’. To explicitly define a relation between the component’s root table and its referential integrity table is not required.

Do not map attribute implementations to referential integrity table columns.

Other guidelines

BII names

Usually, your BII must have the same name as the BID to which the BII corresponds.

If your business interface implementation has a name other than the business interface definition, the Business Interface Implementation name is used as the BDE name in ERP LN. In that case, your BDE is a protected BDE, because the BDE cannot be accessed from the outside through the interface as specified in the BID. For details, refer to “To use multiple implementations” in the “To Use Hooks for Infor ERP LN” chapter.

Hooks

The “To use Hooks for Infor ERP LN” chapter describes how to implement hooks for ERP LN.

Modules and procedures

ERP LN does not support the use of implementation modules and implementation procedures. From the Integration Studio, you can only generate the standard public/protected libraries in ERP LN (called ‘modules’ in the Integration Studio). You cannot generate other libraries. Consequently, the Implementation Module and Implementation Procedure properties for method implementations are not used.

You can implement methods using an existing module/procedure by importing the module from ERP LN and linking this module to the method implementation. Alternatively, you can invoke the procedure from a hook (see "To use Hooks for Infor ERP LN" chapter).


Alternative Business Interface Implementations

The use of alternative Business Interface Implementations is unsupported for ERP LN.

Traversal by Association

For ERP LN, all attributes from associated BDEs must be modeled explicitly in the BID and the BII. You cannot select attributes from associated BDEs at runtime.

Tables of type Form

The use of From type tables is unsupported in ERP LN.

Name lengths

BDE (BI or BII) names cannot be greater than 40 characters in length for ERP LN. Other names cannot exceed 50 characters in length.

To generate BDE runtime

Prerequisites

BID and BII

First, make sure the BID and BII are correct. Solve any problems reported by the Integration Studio. In some cases, you must rebuild to view the actual list of problems. To rebuild, click Project Build Project.

In addition, the BII must meet the guidelines described previously for ERP LN.

Authorizations

You can only generate the BDE runtime if you have development authorizations. In other words, you can only create a BDE runtime from the Integration Studio if you can also create libraries in ERP LN.

BusComponent

Before you use the ERP LN BDE Implementation Generator, specify the BusComponent for the runtime repository in the SSA Connectivity


preferences. To do so, on the Window menu, click Preferences SSA Connectivity.

In the BusComponent field on the Runtime Repository page, specify a BusComponent that refers to company 000 of the ERP LN environment that must contain the BDE runtime. Make sure the BusComponent is installed and running before you use the generator.

Implementation identifier

The BII you want to generate must have an implementation identifier set. This code is a property of the BII that consists of eight characters: two for the package code, three for the module code, and three digits.

Example

ppmmm123.

Important: After generation, the implementation identifier and BDE name are inseparable. If the environment already contains another BDE with the same implementation identifier, or if the environment already contains the same BDE name with another implementation identifier, the generation fails. The generation also fails if that other BDE runtime is stored in another VRC.

To change the implementation identifier or name for an existing BDE, you must first delete the existing BDE in any version in which the BDE exists in the Business Objects (ttadv7500m000) session.

Version

Before you generate the BDE runtime code, you must specify the version in which the BDE runtime must be created. You can set the version on the Preferences page of the ERP LN BDE Implementation Generator:

On the Window menu, click Preferences SSA Integration Studio Generators ERP LN BDE Implementation Generator.

The Major Version, Minor Version, and optional Subordinate Version refer to what is called the Base VRC in ERP LN. To view the available base VRCs, you can use the Base VRCs (ttpmc0110m000) session.

If no base VRC exists that corresponds to the VRC in which you must generate the BDE runtime, you must create a base VRC in ERP LN.

The ERP LN BDE Implementation Generator determines the actual package VRC that is used as follows:


The package is taken from the implementation identifier, as described previously.

The VRC is taken from the Export VRC, as defined in the Base VRCs (ttpmc0110m000) session.

Important: You must have sufficient authorizations to develop in the resulting package VRC. In Infor development, the VRC to be used is a VRC that is open for development or maintenance. In a customer environment, the VRC is a customization VRC, such as B61C_a_cust.

To generate the runtime

To generate the BDE implementation for ERP LN, right-click the BII and, on the shortcut menu, click Implementation Generator ERP LN BDE Implementation.

During generation, the ERP LN Implementation Generator can report violations of LN-specific constraints. Constraint violations often result in errors during generation or errors at runtime when you invoke the BDE in ERP LN.


If you generate BDE runtime, in Infor ERP LN, the following actions take place:

Two libraries are generated: The library code is derived from the BII’s implementation identifier.

A lookup entry is created: This entry is used at runtime to route the invocation of a BDE method to the library that implements the public interface for that BDE.

Compilation errors in the generated libraries are reported. In most cases, these compilation errors only occur for the hooks you included in your BII, or as a result of constraint violations or problems reported by the Integration Studio. However, not all problems are reported directly to the user. Therefore, in some cases, the compilation error is the only feedback you receive on a problem.

To delete or expire BDE Runtime

To delete an implementation

In Integration Studio, you cannot remove a BDE runtime. In ERP LN, to remove BDE runtime, you must use the Business Objects (ttadv7500m000) session. In addition, you must delete the libraries generated for the BDE. The library code is derived from the implementation identifier (business object code). For example, for ppmmm999 the generated libraries will be ppmmmbl999sb00 and ppmmmbl999st00.

The metadata (BI file) is an ‘additional file’ that is linked to the lookup entry. When you delete a lookup entry from the Business Object session, this associated ‘additional file’ is automatically deleted as well.

Important: Be careful when you delete software components. Do not accidentally delete Business Objects or libraries that are not generated from the Integration Studio.

To expire an Implementation

When you expire a BDE runtime, you must expire the complete set of components. So when expiring business object ppmmm999, also expire the ppmmmbl999sb00 and ppmmmbl999st00 libraries and the ppmmmbl999bi.xml additional file. The latter can be expired through the Additional Files (ttadv2570m000) session.

Important: Do not expire a business object without expiring the corresponding libraries or 'additional file' or vice versa. Also do not copy a business object generated from the Integration Studio or one of the business object's libraries or additional file to another VRC. Instead, regenerate the


business object from the Integration Studio if you must include the implementation in another VRC.

Notes

To publish application events

If the PublishEvent method is available, and if this method must publish application, BDE-specific, events, the generation of those events must be implemented in the application, as described in the "To Generate Events from the Application" chapter.

To test BDE runtime

General notes

Testing the BDE runtime for ERP LN is comparable to testing the BDE runtime for any application server. You can use the Integration Studio test tool, use a test client, or use the application with which you plan to integrate.

For information on how to test BDE runtime, refer to the Integration Studio online Help.

The following sections provide several notes on how to test aspects specific to ERP LN.

To test a changed Implementation

Important: If you test a regenerated BDE runtime, make sure that the previous BDE runtime is no longer in memory.

Example

Generate an implementation for a BDE.

Use the tmbdeserver to start a BusComponent for the ERP LN application company to test the BDE runtime.

Make changes to the BDE in the Integration Studio and then regenerate the implementation.

Now, if you want to use the same running BusComponent to test the changed BDE runtime, you actually test the previous implementation, because tmbdeserver still has the previous library objects in memory. As a


result, you must stop and restart the BusComponent after you regenerate the BDE runtime.

Event publishing

Tracing

Event publishing refers to various actions that are carried out invisibly. Therefore, if no event arrives and no error is reported, you do not know what actions were performed. Did the application generate the event correctly? Did the event action match the subscription? Did the application skip the event due to the filter or selection used? For that reason, if you test event publishing, Infor advises you to use the tracing facility. For more details, refer to the “Event Publishing Deployment” chapter.

The trace file also includes the Show request that is used to get the component instances and attribute values for an event. In case the Show fails or gives unexpected results, you can use that request to test the Show method using the same selection and filter. For example, by using the test tool from the Integration Studio or the tlbct3232m000 session, as described below.

To test from the Integration Studio

To use SubscribeEvent and PublishEvent or ShowAndPublishEvent to test ERP LN as an event producer, take the following steps:

1 Producer: Start BW.

2 Producer: Start tmbdeserver for a BusComponent.

3 Consumer (test client): Start the listener for event destination.

You can use the Integration Studio as the event consumer, but, if the BDE has an OnEvent method implemented, you can also use another company of the same ERP LN environment as the event consumer.

4 Consumer: Send SubscribeEvent to the producer's BusComponent.

5 Producer: Restart the bshell, including tmbdeserver, if you subscribe to one or more standard events, such as:

Create

Change

Delete

6 Producer: Run the transaction that generates an event. For example, to send an event on Item_Infor, use the General Item Data (tcibd0501m000) session to create a record.


7 Consumer: Check whether the event was received and processed.

If no event is received, check the following:

The error handler, as specified for the client's BusComponent in the LDAP

The Open Architecture log-on consumer and producer

$BSE/log/log.tlpublishevent on the producer

The publisher's trace file on the producer.

8 Consumer: Unsubscribe after testing.

For details, refer to the Integration Studio online Help.

Note that the procedure is comparable to the one described in the following section, “To test locally in ERP LN,” with the following exceptions:

BusComponents must be available for both the ERP LN Application Server and the Integration Studio client.

You must specify the Integration Studio client in the Bus Component for Event Listener field on the Preferences page of the BDE Test Tool: On the Window menu, click Preferences SSA Integration Studio BDE Test Tool.

The request file is created and sent from the Integration Studio test tool, and the events are returned to, and displayed by, the Integration Studio.

If you subscribe to standard events, such as create, change, or delete, be sure to remember to restart the bshell, including the tmbdeserver, after you subscribe.

To test locally in ERP LN

The specific procedure to test locally in ERP LN, without using Adapter or event consumer, consists of the following steps:

1 Start BW and preferably switch on tracing.

2 Create a file that contains the SubscribeEvent request. Use the following destination: TestUsingOutputFile:<file name>.

Example

<SubscribeEventRequest>

<ControlArea>

<eventAction>create</eventAction>

<eventAction>change</eventAction>

<eventAction>delete</eventAction>

<eventAction>approve</eventAction>


<eventConsumer>thisIsMe</eventConsumer>

<destination>

TestUsingOutputFile:/home/user/events.xml

</destination>

</ControlArea>

</SubscribeEventRequest>

3 Run the tlbct3232m000 session for the BDE and SubscribeEvent method and use the name of the request file as input.

4 Restart BW if you subscribed to one or more standard events, such as create, change, or delete. You must restart BW to use the changed audit settings.

5 Run a transaction that generates an event. For example, to send an event on an Item BDE, create a record in the Items (tcibd0501m000) session.

6 Check the output file to view the events. If no event is available, check $BSE/log/log.tlpublishevent or the publisher's trace file.

7 Unsubscribe after testing, using the tlbct3232m000 session. To do so, you can either create a new request file, or reuse the request file from the SubscribeEvent.

Regenerating BDE Implementations

When you regenerate a BDE implementation for which a publisher is running, you must first pause or unsubscribe the publisher. If you do not pause or unsubscribe the publisher, the regenerated BDE meta data will not match the loaded DLL objects (public/protected library).

Troubleshooting

Overview

This section provides an overview of the Implementation in ERP LN. To perform troubleshooting, knowing what actually happens in ERP LN is helpful. In addition, this section describes the most common issues that can occur during generation.

For information on how to perform troubleshooting during event publishing method testing, refer to the “Troubleshooting” chapter of the Event Publishing Deployment Guide.


Overview of the implementation in ERP LN

When you generate an ERP LN Business Interface Implementation, the following actions take place in the application server.

The BDE is registered in ERP LN to enable the application to find the implementation when a BDE method is invoked at runtime. The registered BDE is visible in the Business Objects (ttadv7500m000) session. BDEs generated from the Integration Studio are marked as such.

Two libraries are generated. The code of these libraries is derived from the implementation identifier. For example, for ppmmm999, the generated libraries are Public Interface (ppmmmbl999sb00) and Protected Interface (ppmmmbl999st00). The libraries are visible in the Program Scripts / Libraries (ttadv2530m000) session.

The library objects will contain a number of identifications. These identifications can help to check which BID/BII and which generator version was used to generate the runtime.

Important: Do not change the generated BDE or libraries in ERP LN, because your change will be overwritten during regeneration.

Generation issues

If the generation fails, the problem is reported to the user. If a problem occurs during BDE runtime generation, the problem is likely one of the following types:

Problems in the connection to the application server In this case, check that the BusComponent is set up correctly. Refer to “To generate the runtime” in this chapter.

Problems in processing the template This type of problem can arise due to an incorrect model. Check whether the Integration Studio reported any problems and whether the constraints are met, as specified in the section “To model the Business Interface Implementation” in this chapter.

Problems in registering the BDE in the application server, such as insufficient authorizations or an incorrect implementation identifier Refer to the section “To generate the Runtime on prerequisites for the ERP LN application server” in this chapter.

Compilation errors in the generated libraries This type of error can be due to:

Errors in the hooks, as described in the “To Use Hooks for Infor ERP LN” chapter


Problems reported by the Integration Studio

Violation of constraints, as described in “To model the Business Interface Implementation” in this chapter.

To examine the compilation errors more closely, you can run the Program Scripts / Libraries (ttadv2530m000) session in ERP LN to compile or view the libraries. You can also view the generated source in the output folder of the Integration Studio project.

3 Chapter 3 To Use Hooks for Infor ERP LN

You can use hooks to implement specific behavior in a Business Interface Implementation.

For all hooks in a BII for ERP LN, coding is performed in the language as used in ERP LN (Enterprise Server 8), scripts, and libraries.

Each hook contains a function body and, therefore, does not include a function header or { }.

Each hook must:

Return (0), if successful.

Use dal.set.error.message(…) and return DALHOOKERROR if an error occurs.

To use Libraries (DLLs)

To reuse existing business logic from ERP LN, you can use libraries, which are called modules in Integration Studio. If you invoke a library, the hook must include a declaration of the library.

Example #pragma used dll oppmmm1234 status = ppmmm1234.translate.status(internalStatus) return(0)

To use Includes

You can also use includes, which are called functions in ERP LN:

#include “ippmmm1234”

3-2 | To Use Hooks for Infor ERP LN

However, if an include contains any functions, you cannot use the include. For more information, refer to “To use subfunctions” later in this chapter.

If the include used in a hook contains variable declarations, those variables will become local variables. When including the same file in multiple hooks, variables are only declared for the first hook, because technically the file is included only once in the generated library. Take this into account when you use included defines that make use of variables from the include.

To use subfunctions

Functions cannot be declared in hooks. For example, you cannot do the following in an on set hook or on get hook for an attribute implementation:

function long calculate.number(long i.number) { return(i.number + 1) } if number1 > 9 then number2 = calculate.number(0) else number2 = calculate.number(number1) endif return(0) | OK

Work around 1

In ERP LN, create a library that contains the required function. For example, if the library code is ppmmm1234 and the function in that library is named ppmmm1234.calculate.number, the hook contains the following:

#pragma used dll oppmmm1234 if number1 > 9 then number2 = ppmmm1234.calculate.number(0) else number2 = ppmmm1234.calculate.number(number1) endif return(0) | OK

Work around 2

Use a define instead of a function:

#define calculate.number(i.number) i.number + 1 if number1 > 9 then number2 = calculate.number(0) else number2 = calculate.number(number1) endif return(0) | OK

To Use Hooks for Infor ERP LN | 3-3

To use global variables

Important: Do not use any global variables. You cannot declare global variables in your own hook code. In addition, never use variables that are created and used in the code as generated by the ERP LN implementation generator. These variables are subject to change, and compatibility is never guaranteed.

You can use static variables. However, if the same hook is used in multiple locations, such as multiple attribute implementations, each hook can have the hook’s unique function generated. Therefore, the value of these types of static variables cannot be shared across attribute implementations. In addition, the use of static variables for optimization can be limited, because a new process can be started for a new request (method invocation) coming in.

Transactions

Do not set retry points or run a commit or abort in any hook.

Attribute hooks

The following table specifies the availability for attribute hooks in ERP LN:

Integration Studio ERP LN Implementation

before get hook Refer to “Before/after get/set hooks”

on get hook Refer to “On get/set hooks”

conversion get hook Refer to “Conversion hooks”

after get hook Refer to “Before/after get/set hooks”

before set hook Refer to “Before/after get/set hooks”

on set hook Refer to “On get/set hooks”

conversion set hook Refer to “Conversion hooks”

after set hook Refer to “Before/after get/set hooks”

default value hook Refer to “Default value hooks”

Note: The hooks are included in the so-called protected layer, because no calculations or hooks are modeled in the Integration Studio in the public layer.


Guidelines

In the Integration Studio, you can use a hook for multiple attribute implementations in multiple BIIs. As a result, the names of the involved attribute implementations are not known in the hook code.

In attribute hooks, you can set or use attribute (implementation) values by means of input and output parameters.

Available parameters

You can use the following parameters:

On get/set hooks always have one output parameter and zero or more input parameters. The output parameter is the attribute implementations being get/set. The input parameters are the used attributes as specified for the attribute implementations being get/set.

Before get/set hooks have one output parameter ioCancel, and zero or more input parameters for the used attributes.

After get/set hooks only have input parameters, which are the used attributes.

Conversion get/set hooks have one input parameter and one output parameter. For a conversion get hook, the input parameter is the value from the attribute implementation, and the output parameter is the value for the corresponding attribute. For a conversion set hook, the input parameter is the value for the attribute, and the output parameter is the value for the corresponding attribute implementation.


The parameters are named as follows:

Hook Description Variable Names

before/on/after get/set

Input parameters for used attributes

i.hookAttribute1, i.hookAttribute2, etc. (number is equal to the position in the used attributes)

on get/set Output parameter for attribute being get/set

o.hookAttribute

before get/set Input/output parameter for cancel

io.cancel

default value Input/output parameter for attribute implementation, and input parameters for used attributes

For example:

io.hookAttribute

i.hookAttribute1

i.hookAttribute2

The number is equal to the position in the used attributes.

conversion get Input parameter for attribute implementation; output parameter for corresponding attribute

i.hookAttribute

o.hookAttribute

conversion set Input parameter for attribute; output parameter for corresponding attribute implementation

i.hookAttribute

o.hookAttribute

filter Output parameter for filter

o.hookFilter

The data type of the parameters is the same as the data type of the attribute implementations involved. In other words, if the same hook is used in two places, the data types can differ.

For example, if you use the on get hook Concatenate for a string with length 6, the o.hookAttribute is a string(6); whereas if this hook is used for a string of length 8, the o.hookAttribute is a string(8).

Important: To avoid errors, never use or set global variables directly from a hook. The implementation generator for ERP LN ensures that the used


values are available, but will not ensure that all other attribute values are available in all cases.

To use speaking names

Note that the parameters do not have speaking names, because hooks can be generic. To use speaking names, you can either use defines or variables.

For example, if an on get hook is created to calculate an amount from an internalAmount and a discountPercentage then the hook can contain:

#define internalAmount i.hookAttribute1 #define discountPercentage i.hookAttribute2 #define amount o.hookAttribute if calculateAmount(internalAmount, discountPercentage, amount) then return(0) | OK else dal.set.error.message(…) return(DALHOOKERROR) endif

The define names can be any speaking name. The names need not match the attribute implementation names as listed in the used attributes.

The use of defines is efficient, but has a drawback during debugging. You cannot see the value directly by clicking the name in the debugger. Instead, you can use local variables as follows:

Example domain ppmmm.amnt internalAmount domain ppmmm.perc discountPercentage domain ppmmm.amnt amount internalAmount = i.hookAttribute1 discountPercentage = i.hookAttribute2 if calculateAmount(internalAmount, discountPercentage, amount) then o.hookAttribute = amount return(0) | OK else o.hookAttribute = 0.0 dal.set.error.message(…) return(DALHOOKERROR) endif Important: If an attribute implementation has fewer used attributes listed than are actually used in the hook, the generation in ERP LN will fail.

If an attribute implementation has more used attributes listed than are actually used in a hook, the user must be sure to use the appropriate attribute implementations. If three used attributes are listed, the first attribute


in the before get hook and the other two in the on get hook, the hooks contain the following:

Before get hook #define itemType i.hookAttribute1 | #define unusedProject i.hookAttribute2 | #define unusedMaterial i.hookAttribute3

On get hook: | #define unusedItemType i.hookAttribute1 #define project i.hookAttribute2 #define material i.hookAttribute3 #define itemCode o.hookAttribute

On get/set hooks

Important: In on get/set hooks for an attribute implementation, you must only use attributes that are modeled as used attributes for that attribute implementation.

Note that you cannot have both an on set hook and an on get hook on the same attribute implementation.

You can only fill or change an attribute implementation value in the following cases:

In an on set hook, if the attribute implementation is the attribute implementation that contains the on set hook.

In an on get hook, if the attribute implementation is the attribute implementation that contains the on get hook.


You can only use an attribute implementation value in the following cases:

In an on set hook, if the attribute implementation is one of the attribute implementations listed in the used attributes of the attribute implementation containing the on set hook.

In an on get hook, if the attribute implementation is one of the attribute implementations listed in the used attributes of the attribute implementation that contains the on get hook.

Examples:

The following figure illustrates one-to-one, one-to-many, and a many-to-one relationships for attributes and table columns.

Table ColumnsAttributes

anAmount

amountColumn2

aString

amountColumn1

code1

codeColumn

stringColumn

code2

Attribute Implementations and Hooks

amountColumn2

amountColumn1

codeColumn

stringColumn

code2

code2

anAmount

aString

On Get Hook

On Get Hook

On Get Hook

On Get Hook

On Set Hook

On Set Hook

On Set Hook

On Set Hook

Important: In the ERP LN Business Object Repository, the predecessor of the on set hook was not linked to the attribute being set, but to the attribute that also had the on get hook. This situation is now remedied.


The following table lists the mapping between the attributes and table columns:

Set Get

stringColumn = aString(4) aString = “ERP_” & stringColumn

calculateInternalAmountColumn1 (anAmount, amountColumn1); calculateInternalAmountColumn2 (anAmount, amountColumn2)

calculateExternalAmount (amountColumn1, amountColumn2, anAmount)

determineInternalCode (code1, code2, codeColumn)

determineExternalCode1 (codeColumn, code1); determineExternalCode2 (codeColumn, code2)

Because you have two separate on set hooks for amountColumn1 and amountColumn2, the reuse of existing library functions has a drawback. For example, assume you have the following existing function:

calculateInternalAmounts

anAmount

amountColumn1

amountColumn2

You can use this function from both the amountColumn1 on set hook and the amountColumn2 on set hook. Note, however, that the hooks are run twice if anAmount is set and, as a result, amountColumn1 and amountColumn2 are set. For the example in the previous figure, the hooks are as follows:

On Get hook for aString: #define value_aString o.hookAttribute #define value_stringColumn i.hookAttribute1 | add prefix “ERP_” value_aString= “ERP_” & value_stringColumn return(0) | OK

Note that checking whether or not stringColumn is set is unnecessary. If the model is correct, stringColumn is listed as a used attribute for the calculation, and therefore the standard mechanism ensures that the required attribute is set, which is also the case for the following hooks:

On Set hook for stringColumn #define value_aString i.hookAttribute1 #define value_aString(…) i.hookAttribute1(…) #define value_stringColumn o.hookAttribute


| remove prefix “…_”, e.g. “ERP_”; prefix will always be 3 characters plus underscore if len(strip$(value_aString) < 4 then dal.set.error.message(“ppmmms1234.01”, value_aString) |* Component.aString %s does not have the required prefix (such as “ERP_”) return(DALHOOKERROR) else value_stringColumn = value_aString(4) return(0) | OK endif

On Get hook for anAmount #define value_amountColumn1 i.hookAttribute1 #define value_amountColumn2 i.hookAttribute2 #define value_anAmount o.hookAttribute #pragma used dll oppmmmamounts | library ppmmmamount contains: | function long ppmmmamount.calculateExternalAmount( | double i.amountColumn1, | double i.amountColumn2, | ref double o.anAmount) long retl | return value to be checked retl = ppmmmamount.calculateExternalAmount( value_amountColumn1, value_amountColumn2, value_anAmount) if retl <> 0 then dal.set.error.message(“ppmmms1234.02”, value_amountColumn1, value_amountColumn2) |* Cannot calculate Component.anAmount for amountColumn1 = %f and amountColumn2 = %f return(DALHOOKERROR) else return(0) | OK endif

As described in the section “Guidelines,” the position of the input arguments in the used attributes determines the sequence of the input arguments. In this case, the first used attribute is amountColumn1 and the second is amountColumn2.

On Set hook for amountColumn1 #define value_anAmount i.hookAttribute1 #define value_amountColumn1 o.hookAttribute #pragma used dll oppmmmamounts | library ppmmmamount contains: | function long ppmmmamount.calculateInternalAmountamountColumn1( | double i.anAmount, | ref double o.amountColumn1) long retl | return value to be checked


retl = ppmmmamount.calculateInternalAmountamountColumn1(value_anAmount, value_amountColumn1) if retl <> 0 then dal.set.error.message(“ppmmms1234.03”, value_anAmount) |* Cannot calculate Component.amountColumn1 for anAmount = %f return(DALHOOKERROR) else return(0) | OK endif

On Set hook for amountColumn2 #define value_anAmount i.hookAttribute1 #define value_amountColumn2 o.hookAttribute #pragma used dll oppmmmamounts | library ppmmmamount contains: | function long ppmmmamount.calculateInternalAmountamountColumn2( | double i.anAmount, | ref double o.amountColumn2) long retl | return value to be checked retl = ppmmmamount.calculateInternalAmountamountColumn2(value_anAmount, value_amountColumn2) if retl <> 0 then dal.set.error.message(“ppmmms1234.04”, value_anAmount) |* Cannot calculate Component.amountColumn2 for anAmount = %f return(DALHOOKERROR) else return(0) | OK endif


On Get hook for code1 #define value_codeColumn i.hookAttribute1 #define value_code1 o.hookAttribute #pragma used dll oppmmmcoding long retl | return value to be checked retl = ppmmmcoding.determineExternalCode1(value_codeColumn, value_code1) if retl <> 0 then dal.set.error.message(“ppmmms1234.05”, value_codeColumn) |* Cannot determine Component.code1 for codeColumn = %s return(DALHOOKERROR) else return(0) | OK endif

On Get hook for code2 #define value_codeColumn i.hookAttribute1 #define value_code2 o.hookAttribute #pragma used dll oppmmmcoding long retl | return value to be checked retl = ppmmmcoding.determineExternalCode2(value_codeColumn, value_code2) if retl <> 0 then dal.set.error.message(“ppmmms1234.06”, value_codeColumn) |* Cannot determine Component.code2 for codeColumn = %s return(DALHOOKERROR) else return(0) | OK endif

On Set hook for codeColumn #define value_code1 i.hookAttribute1 #define value_code2 i.hookAttribute2 #define value_codeColumn o.hookAttribute #pragma used dll oppmmmcoding long retl | return value to be checked retl = ppmmmcoding.determineInternalCode(value_code1, value_code2, value_codeColumn) if retl <> 0 then dal.set.error.message(“ppmmms1234.07”, value_code1, value_code2) |* Cannot determine Component.codeColumn for code1 = %s and 4 = %s return(DALHOOKERROR) else return(0) | OK endif

As described in the “Guidelines” section, the position of the input arguments in the used attributes determines the position of the input arguments in the


sequence. In this case, the first used attribute is code1 and the second is code2.

Conversion hooks

You can only use conversion hooks to convert a value from the data type used in an attribute to the data type used in the corresponding attribute implementation, and vice versa.

Only one input parameter and one output parameter are used. Other attribute implementations or table columns must not be used in a conversion hook. The parameter that represents the attribute is always a string. The parameter that represents the corresponding attribute implementation is declared on the parameter’s domain.

Important: Standard data type conversions, as discussed in the following section "Standard Conversions, "must not be implemented in a hook. If you define a conversion hook for a UTC, enumerate, or text, the standard data type conversion does not run.

The actual conversion is carried out in the public layer. As a result, if you use the protected interface in ERP LN, only the domains as specified for the attribute implementations are used.

Example:

A conversion get hook for an itemCode attribute can contain the following:

#define itemCodeImplementation i.hookAttribute #define itemCodeAttribute o.hookAttribute itemCodeAttribute = toupper$(itemCodeImplementation) return(0) | OK

In addition, the corresponding conversion set hook can contain:

#define itemCodeAttribute i.hookAttribute #define itemCodeImplementation o.hookAttribute itemCodeImplementation = tolower$(itemCodeAttribute) return(0) | OK


Standard Conversions

Overview

Some data types that are internally used in ERP LN can differ from the standard formats as used in the BIDs. In a number of cases, these data types are converted automatically, to avoid programming efforts and risks of errors.

Standard data type conversions are available for:

Boolean

UTC date/time and date

Enumerate

Text

Number to string and vice versa

Doubles

XML

Each of these is explained below. No other standard conversions are available.

Important: Standard conversions can be overruled by implementing a conversion hook. So when defining a conversion hook, the standard data type conversion is not executed.

Just like calculations, conversion hooks influence performance, because a filter on a calculated value cannot be delegated to the DBMS. Instead too much data is read from the database, and ‘post-filtering’ is done after calculating the public attribute value, which is an expensive process. So if possible, avoid conversion hooks, especially on enumerate values.

Boolean conversions

A standard Boolean conversion is performed if:

the attribute is a Boolean, but the corresponding attribute implementation has primitive data type ‘long’

the attribute is a Boolean, but the corresponding attribute implementation is a ‘boolean enumerate’, i.e. a string data type having two enumeration facets: “yes”/“no” or “Yes”/“No” or “true”/“false” or “True”/“False”.


UTC and Date conversions

UTC date/time values are automatically converted if the attribute implementation that is linked to the attribute has primitive data type ‘time’ or ‘dateTime’. The corresponding attribute implementation is then assumed to have a UTC date/time domain as its native data type.

From outside to inside, a string according to the ISO 8601 format is converted to a UTC date/time according to the internal ERP LN representation. From inside to outside, the internal ERP LN representation is converted to an ISO 8601 string. In the latter case, the used ISO 8601 format is any of the following:

yyyy-mm-ddThh:mm:ssZ

yyyy-mm-ddThh:mm:ss+hh:mm

yyyy-mm-ddThh:mm:ss-hh:mm

Automatic conversion for date values is done if the attribute implementation that is linked to the attribute has primitive data type ‘date’. The corresponding attribute implementation is then assumed to have a date domain as its native data type.

From outside to inside, a string according to the yyyy-mm-dd format is converted to a date in the internal ERP LN representation. From inside to outside, the internal ERPLN representation is converted to a date string with the yyyy-mm-dd format.

Enumerate conversions

Enumerate values are automatically converted if the attribute has primitive data type ‘string’ and one or more enumeration facets. The corresponding attribute implementation is then assumed to have a matching enumerate domain as its native data type.

Note

The standard enumerate conversion (based on the enumerate constants as defined in the ERP LN domain) uses lower case. So if possible, use lower-case enumerate values in your BID, matching the definition of the enumerate domain.

Text conversions

To convert text data types, a default conversion is available from the text number data type as used in ERP LN to the string data type (text contents) as used in the public attributes. However, the generator in the Integration Studio does not have all native domain information from ERP LN available in


the data types. As a consequence, the generator makes an assumption regarding which data type is actually a text.

To identify text data types, the generator uses the following rule: a datatype is assumed to represent a text if the data type’s native data type, which contains the domain, corresponds to one of the following string values (where ‘?’ can be any character):

?????.text

??text

?????.txtn

??txtn

?????.txta

??txta

This means that domains that do not conform to this rule will be handled incorrectly and will result in failure at runtime or when generating the ERP LN implementation. For example, if a domain is used that matches one of the patterns (e.g. pptext) but is not a text domain, or if a text domain is used that does not match one of the patterns (e.g. ppmytext).

To solve such a problem, use another domain as the native data type.

Number/String conversions

Automatic conversion between numeric values and string values is done if:

the attribute is a string, but the corresponding attribute implementation is numeric (long, double or float)

the attribute is numeric (long, double or float), but the corresponding attribute implementation is a string.

In the previous conditions, the various data types mean:

string primitive data type in {"string", "anyURI", "duration", "Name"}

long primitive data type in {"byte", "int", "integer", "negativeInteger", "nonNegativeInteger", "nonPositiveInteger", "normalizedString", "positiveInteger", "short", "unsignedByte", "unsignedInt", "unsignedLong", "unsignedShort", "long"}

float primitive data type in {"float"}

double primitive data type in {"decimal", "double"}


Double values

If both the attribute and the attribute implementation have primitive data type ‘double’, no conversion is required. However, double values are discussed here because they can have multiple formats. The following table specifies which values are accepted as input:

<validDouble> ::= [whiteSpace]<significand>[<exponent>][whiteSpace]

<significand> ::= [<sign>]<unsignedSignificand>

<unsignedSignificand> ::= <number> | “.”<number> | <number>“.”<number>

<exponent> ::= “e”|“E” [<sign>]<number>

<sign> ::= “+”|“-”

<number> ::= <digit> | <digit><number>

<digit> ::= “0”|“1”|“2”|“3”|“4”|“5”|“6”|“7”|“8”|“9”

<whiteSpace> ::= “ ” | “ ”<whiteSpace>

As specified above, leading and trailing spaces are accepted. Spaces inside significand or exponent or between significand and exponent are not allowed.

Examples of valid doubles are: "12", "12.3", "0.3", ".3", "+12", "+12.3", "+.3", "-12", "-12.3", "-.3", "012", "012.0". Each of these values can be followed by an exponent. So other valid doubles are for example: "12.3e1", ".3E2", "+12.3e+12", ".3e-12", "-12E+12", "1E-12".

Examples of invalid doubles: "12,3", "1,000", "1.000,25", "100e", "12.", ".", "e3", "12 e3" (contains a space), "12e0.5"

Note

The "INF" value (Infinite) is valid according to W3C, but is not supported by ERP LN and the Integration Studio.

For more information about the 'double' data type, see also http://www.w3.org.

XML Conversions

An attribute is automatically converted to XML if this attribute has primitive data type ‘anyType’. The corresponding attribute implementation is then assumed to have a ‘long’ domain as its native data type, which refers to an in-memory XML structure.

http://www.w3.org/


Default value hooks

A default value hook is comparable to an on set hook.

In a default value hook, you must set the attribute to which the default value hook is linked. This variable is not declared in the hook code. You can only set one attribute implementation in a default value hook.

The attribute implementation’s used attributes can be used to determine the default value.

A default value hook can be used if the default value is not a constant value. For example, if the default value hook is based on used attributes or on a parameter value from the database. In other cases, a simple default value can be linked to the attribute implementation.

Note that an attribute implementation can have both a default value and a default value hook. In that case, the default value hook has precedence over the default value. The default value is only used if the default value hook does not overwrite the default value.

Example: #define defaultOrderType io.hookAttribute #define value_customer i.hookAttribute1 #pragma used dll oppmmmparam long retl | return value to be checked domain ppmmm.opar order.parameter retl = ppmmmparam.get.order.parameter(value_customer, order.parameter) if retl <> 0 then dal.set.error.message(“ppmmms1234.11”, value_customer) |* Order parameter is not set for customer %s return(DALHOOKERROR) else if order.parameter = ppmmm.opar.operational then defaultOrderType = ppmmm.otyp.production else defaultOrderType = ppmmm.otyp.virtual endif return(0) | OK endif

If a default value is linked to the attribute, that default is set before you run the default value hook. As a result, for example, if the default value is 1, the default value hook can contain:

#define myAttribute io.hookAttribute if some.condition() then myAttribute = 2 | else


| default value linked to attribute implementation (i.e. 1) is used endif return(0) | OK

Before/after get/set hooks

You can use the same attributes in before and after get/set hooks that are input for on get/set hooks. For information on how to use get/set hooks, refer to the section “On get/set hooks.”

Before and after get/set hooks have not output, with the exception of an io.cancel in the before get/set hook. You cannot change BDE attributes, or the corresponding persistent data in the database, in a before/after get/set hook.

Only use io.cancel if the fact that the attribute is not skipped is not a problem, and if the client application does not need to be informed of this fact. In case of an exception, do not use io.cancel, but instead set an error message and return DALHOOKERROR.

Examples:

The following two examples are hypothetical examples of before/after set hooks for a price attribute.

Before set hook | before set hook for attribute price; only set this attribute if status and type allow this #define value_status i.hookAttribute1 #define value_type i.hookAttribute2 #define value_order i.hookAttribute3 | unused here #define value_price i.hookAttribute4 | unused here long retl | return value to be checked if value_type = ppmmm.type.external and value_status = ppmmm.stat.confirmed then | do not set price attribute io.cancel = true endif return(0) | OK

After set hook | after set hook for attribute price; only set this attribute if status and type allow this #define value_status i.hookAttribute1 | unused here #define value_type i.hookAttribute2 | unused here #define value_order i.hookAttribute3 #define value_price i.hookAttribute4 #pragma used dll oppmmmsox


if value_price > 999999.0 then ppmmmsox.report.high.price(value_order) endif return(0) | OK

Filter hooks

Important: The filter hook content for ERP LN is not compliant to the BI standard.

A filter hook usually consists of the following two parts:

Assignment of the output parameter o.hookFilter, which is the actual filter A string expression is assigned, which is a query extension that uses any columns from any of the tables listed in the component’s ComponentImplementationTable elements.

A return at the end A filter hook usually does not return an error value.

Examples:

If a component has at least two tables defined, the filter hook can contain the following:

o.hookFilter = “ppabc001.col1 <> 0 and ppabc002.col2 <> ppabc.stat.canceled” return(0) | OK

The following is a real-life example:

| do not include canceled orders o.hookFilter = “tdsls400.clyn <> tcyesno.yes” return(0) | OK

Method hooks

The following table lists the hooks supported for ERP LN:

Method Before execute hook

On execute hook

After execute hook

Create Supported Supported Supported

Change Supported Supported Supported

Delete Supported Supported Supported


List - - -

Show - - -

SubscribeEvent Supported Supported Supported

UnsubscribeEvent Supported Supported Supported

PublishEvent Supported Supported Supported

OnEvent Supported Supported Supported

SubscribeList - - -

SupportsReferentialIntegrity - - -

CreateRef - - -

DeleteRef - - -

SupportsProcessingScope - - -

Any specific method Supported Supported Supported

The List and Show methods do note use a method implementation in ERP LN. As a result, before hooks, on hooks, and after hooks are also unused.

Note that, according to the BI specifications, a Read method is used to implement List and Show. In practice, you can implement the Show method in the Integration Studio to implement this Read. However, for ERP LN, List, Show, and Read method implementations are not used. A read method is generated automatically for each BDE that generates a Business Interface Implementation.

General Guidelines

The guidelines described at the beginning of this chapter also apply to method hooks.

To use method arguments for top-down and bottom-up methods

Attribute implementation values input, output, or both are listed as method arguments for a method.

You can use attribute implementations in the same way as for attribute hooks work. For more information, refer to the section “Guidelines to use or set attribute implementation values.” The position in the method arguments determine the position number. Note that input, output, and input/output arguments can be mixed up, for example:


Position 1: input i.hookAttribute1

Position 2: input/output io.hookAttribute2

Position 3: output o.hookAttribute3

Position 4: input i.hookAttribute4

Position 5: input/output io.hookAttribute5

Position 6: output o.hookAttribute6

Position numbers are always sequential, starting at 1 and incrementing by 1.

Important: For ERP LN, you cannot use controlling attributes as method arguments.

The following table lists the attribute implementations that you can use in before hooks, on hooks, and after execute hooks for a method.

Hook Input arguments for the method

Output arguments for the method

before execute

Can be used, but in read-only format:

i.hookAttribute1

io.hookAttribute2

i.hookAttribute4

io.hookAttribute5

Cannot be used.

Technically, parameters such as i.hookAttribute3 can be available, but these parameters will not be filled.

on execute Can be used, but in read-only format, unless arguments are input/output:

i.hookAttribute1

io.hookAttribute2

i.hookAttribute4

io.hookAttribute5

Must be filled:

io.hookAttribute2

o.hookAttribute3

io.hookAttribute5

o.hookAttribute6

after execute Can be used, but in read-only format:

i.hookAttribute1

i.hookAttribute2

i.hookAttribute4

i.hookAttribute5

Can be used, but in read-only format:

i.hookAttribute2

i.hookAttribute3

i.hookAttribute5

i.hookAttribute6


Note that this implies that only the attribute implementations specified as input parameters are used. Other attribute implementation values or table columns cannot be used, even if the values or columns are linked to the used attribute implementations.

You cannot change any attribute implementation values in a before or after execute hook.

Important: A batch method does not have the attribute values available as parameters. For more details, refer to the section “To use hooks for batch methods.”

To use standard control data

Standard control data is not explicitly defined as input or output for a method.

Controlling attributes, namely standard controlling attributes, are not passed on as parameters for hooks. Instead, you can use control data by means of the following helper method:

function boolean getControlAttribute( const string i.name, ref string o.value)

The return value is true if the attribute was retrieved successfully. In that case, oValue is set. The return value is false if the attribute does not exist or if another error occurred.

Example string batchString(12) long batchNumber if not getControlAttribute(“batch”, batchString) then batchNumber = 0 else batchNumber = lval(batchString) endif do.something(batchNumber) return(0) | OK

The control data is available in the before/on/after execute hooks for each method and for each component. Both standard control data and non-standard control data, for specific methods, can be used.

You cannot update control data in a hook.

Important: For ERP LN, you cannot use controlling attributes as method arguments. As a result, controlling attributes also cannot be output for a method implementation. You cannot set controlling attributes. The exception is if you use specific methods with processing order batch, in which case you


must build up the entire response in the on execute hook. For more information, refer to the section “To use hooks for batch methods.” In that case, however, note that the control area is used for the request/response as a whole, and therefore no controlling attributes can be determined for each object instance.

Before execute method

If the method has processing order batch, the on execute hook is linked to the top-level component, which is the BDE level. In that case, you must use the entire request. In other cases, you can only use the attribute values from the current component and identifying attributes from the parent components, if any.

In a before execute hook, you cannot change the object instance being processed; either the object instance’s attribute values or the object instance’s persistent data in the database.

You can set output parameter io.cancel, which is a boolean that indicates whether the method execution must be cancelled. If the method execution is not set, the default value is false.

If a BDE consists of multiple components, the cancel is handled as shown in the following figure:


1

1.1 1.2

1.1.1 1.1.2

CancelTop-down

CancelBottom-up

In case of a bottom-up method, such as Delete, if a cancel occurs on a component instance, the method is not carried out for that component and the component’s parents. A cancel on 1.1 results in skipping the method for 1.1 and 1, and 1.2 is processed.

In case of a top-down method, such as Create, if a cancel occurs on a component instance, the method is not carried out for that component and the component’s children. A cancel on 1.1 results in skipping the method for 1.1, 1.1.1, and 1.1.2.

These rules apply to standard and specific methods.

In case of a Change method, the situation is unclear, because a change combines the top-down and the bottom-up approach. A change can include create or delete actions on subcomponents. A cancel on a delete for a child does not impact the change on the header. The following figure illustrates three cancel situations:


Create

Create Create

Change

Delete

Delete Delete

Change

Create Change Delete

DeleteCanceled implicitly, because the delete on the parent is skipped.

Example #define orderDirection i.hookAttribute15 if orderDirection = ppmmm.stat.inbound then io.cancel = true | skip inbound orders in this method endif return(0) | OK

On execute method

If the method has processing order batch, the on execute hook is linked to the top-level component, which is the BDE level. In that case, the entire request must be used. In other cases, you can only use attribute values from the current component and identifying attributes from the parent components, if any.

From an on execute hook for a standard method, you can fall back to the default behavior. To do so, set the output parameter io.default to true and return the OK value (0).

Example:

For on execute hook for Create with processing order top-down:

#pragma used dll oppmmmorderline | my own order line implementation #define orderNumber i.hookAttribute1 #define lineNumber o.hookAttribute2 #define item i.hookAttribute3 #define quantity i.hookAttribute4 #define price i.hookAttribute5


return( ppmmmorder.create.order.line(orderNumber, item, quantity, price, lineNumber) )

After execute method

The after execute hook is comparable to the before execute hook, except:

No io.cancel is available.

The values for output (and input/output) attribute implementations are now set, because the method is executed, and therefore these values can be used in the after execute hook.

For the before execute hook guidelines, refer to the section “Before execute method.”

Example: | after execute hook for method Approve #pragma used dll oppmmmlogging #define orderNumber i.hookAttribute1 | order number of current order instance #define orderType i.hookAttribute4 | type of current order instance long retl | return value to be checked if ppmmmlogging.must.do.logging(orderType) then retl = ppmmmlogging.log.order.approval(orderNumber) if retl <> 0 then dal.set.error.message(“ppmmms1234.21”) |* Logging failed return(DALHOOKERROR) endif endif return(0) | OK

To use hooks for batch methods

Input and output

Methods that have processing order batch do not have the method arguments available as parameters. Instead, the entire request is available as an input parameter for the hook. If required, you can forward the entire request to another BDE method or DLL.

The following table lists the parameters that can be used in method hooks for batch methods:

Hook Request Response Result


before execute i.request

Read only

- -

on execute i.request

Read only

o.response o.result

after execute i.request

Read only

i.response

Read-only

-

In addition, as in method hooks for top-down and bottom-up methods, the before execute method provides an io.cancel, as described in the section “Before execute method,” and the on execute method provides an io.default parameter, as described in the “On execute method.”

To use the request

You can iterate through the instances in the request as follows:

#define getFirstInstance(request) xmlFindFirstMatch(sprintf$(“<%sRequest>.<DataArea>.<%s>”, “OnEvent”, | use the method name here “SalesOrder” | use the BDE name here request) #define getNextInstance(prev_instance) xmlGetRightSibling(prev_instance) long current.instance current.instance = getFirstInstance(i.request) while current.instance <> 0 … current.instance = getNextInstance(current.instance) endwhile

Alternatively, you can forward the request to another method of the same BDE or another BDE.

Note: For a class method, such as SubscribeEvent, no instances are available in the data area.

To use control data

Control data is included in i.request and can be added to o.response. You can use the controlling attributes in the before, on, and after execute hooks. You can set the controlling attributes in the on execute hook.

In addition, you can use the helper function getControlAttribute(), as described in the section “Method hooks.”


To use the response

You can use the o.response output parameter for a response that is built up in the on execute hook, or for a response that is received from another BDE method invoked from the on execute hook.

Make sure that the contents of o.response matches the definition of the BDE method to which the on execute hook is linked.

Do not fill o.response if io.default is set to true.

Error handling

If you forward the request to, or create a specific request for, another method or BDE, you receive a response or result. If you receive a result, use o.result. The result is included in the message details of the final method result.

In that case, you must return DALHOOKERROR. You are not required to use dal.set.error.message(), however, the use of dal.set.error.message() is not forbidden, either.

If an error occurred and you return DALHOOKERROR but without o.result being filled, you must use dal.set.error.message().

If you fill o.result, set io.default to true and return the OK value (0). The result is handled as follows:

If the default process succeeds, the messages from the result are included in the response information area.

If the default process fails, the messages from the result are included in the method’s result.

In a before or after execute hook for a batch method, you cannot return a result XML. However, you can set a DAL error message and return DALHOOKERROR.

If you set a DAL error message in a before/on/after execute hook, but return 0 (OK), the message is regarded as a warning.

Examples:

The following is an example of an on execute hook for the OnEvent() method that illustrates the switch between using your own implementation and using the default behavior:

#pragma used dll oppmmmonevent | my own on event handler string eventAction(50) if not getControlAttribute(“eventAction”, eventAction) then


dal.set.error.message(…) return(DALHOOKERROR) else on case eventAction case “myEvent1”: case “myEvent2”: | invoke my own event implementation return( ppmmmonevent.myEventHandler(i.request, o.response, o.result) ) default: | use the default behavior io.default = true o.response = 0 o.result = 0 return(0) | OK endcase endif

The following is an example of an on execute hook for the OnEvent() method, to illustrate how to forward a request to another BDE or method:

#pragma used dll oppmmmbl987sb00 | public interface of another BDE string eventAction(50) if not getControlAttribute(“eventAction”, eventAction) then dal.set.error.message(…) return(DALHOOKERROR) else on case eventAction case “approve”: | use change method of the same BDE … | at this point the control in i.request are must be changed to match the change method return( ppmmmbl123sb00.Change(i.request, o.response, o.result) ) case “plan”: | send plan event to another BDE … | at this point the BDE must be renamed in i.request return( ppmmmbl987sb00.OnEvent(i.request, o.response, o.result) ) default: | use the default behavior io.default = true o.response = 0 o.result = 0 return(0) | OK endcase endif

Batch List and Show methods

You can use processing order 'batch' and an on execute hook for the List and Show methods. This functionality can be used for BIIs where all or some components do not map to tables, and for BIDs with multiple implementations (so-called 'chameleons').

Limitations are: (1) Both methods must be implemented in the same way, so either both are batch methods having an on execute hook, or both are using


the standard implementation. (2) It is not possible to use on execute hooks for top-down List or Show implementations.

To use multiple implementations

You can create multiple business interface implementations for a single business interface definition in one ERP LN environment and within the same version.

Example: Three BIIs are defined for a BID X:

A public X A protected Y A protected Z

The X implementation is simply an interface that forwards requests to Y and Z. Depending on the value of an attribute X.type, either the Y or the Z implementation is used.

In ERP LN, a single BDE name exists for each BDE, which is usually the BID name. The BDE name is used in the lookup and is the top-level node in the data area. However, if a protected BDE is generated, the BII name is used as the BDE name, which enables you to use multiple implementations of the same BID.

Note: In that case, the user must make sure that the BII name is unique and does not conflict with an existing BID name.

How to model

The following figure illustrates how most methods are handled:


Lookup

Request

X

Y

Z

DLLsImplementing

Y

DLLsImplementing

X

DLLsImplementing

Z

DefaultImplementation


Create, Change, Delete,List, Show,

(Un)SubscribeEvent,OnEvent

BIIs Y and Z do have look-up entries, but are not invoked from the outside, because their names do not match existing BID names. Requests for X are forwarded to Y or Z, or both, depending on the method.

Y uses the BII name Y as a BDE name, and also uses this name as a top-level component. Therefore, the Y BII does not use the name X, as defined in the BID. In the same way, Z uses Z as a name, a not X.


The following figure illustrates the flow for the PublishEvent() and ShowAndPublishEvent() methods:

DLLsImplementing

Y

DLLsImplementing

X

DLLsImplementing

Z


PublishEvent (from application),PublishEvent (from Publisher),

ShowAndPublishEvent

The essential idea for event handling is as follows:

Application events are handled in X. As a result, X also contains the subscription for application events. The application can use the PublishEvent or ShowAndPublishEvent from Y or Z, however, in that case Y and Z do nothing other than forward the event to X. The application can also use the PublishEvent from X directly. In this case, however, the ShowAndPublishEvent for X usually will not work, because the business interface implementation for X does not have a mapping to tables.

Standard events, such as create, change, and delete, are handled in Y and Z, which is necessary because the publisher uses the mapping to tables and columns to detect the events.

Example for Event Publishing

The following Event Publishing example uses a public BDE implementation X and a protected BDE implementation Y. Note that multiple protected implementations can exist, but all are handled in the same way.


The following figure illustrates how the subscription is handled:

Y

X

SubscribeEventfor {create, approve} Default

ImplementationX

SubscribeEventfor {approve}

SubscribeEventfor {create, approve} Subscription

X, {approve}


Y

SubscriptionY, {create, approve}

The following figure illustrates how Event Publishing works, based on the subscriptions shown in the previous figure. The figure includes the following flows:

A The publisher for standard events. For standard events, in this case, create, a publisher is running for Y. This service uses the Show()and PublishEvent() methods from Y.

B PublishEvent from the application on Y.

C ShowAndPublishEvent from the application on Y.

D PublishEvent from the application on X.

Note that ShowAndPublishEvent() is only available for Y, and not for X, which does not have an implementation, in other words, mapping to tables.


Y

X

D-1PublishEvent(approve)

Post-filter &Selection

for XA-1

Detected create on Y

SubscriptionX, {approve}

SubscriptionY, {create, approve}

Publisherfor Y

A-3PublishEvent

(create)

Application

ApplicationC-1

ShowAndPublishEvent(approve)

C-2Show (includingfilter/selection)

A-5, B-4, C-4, D-3Published event messages

B-3, D-2

B-2, C-3PublishEvent(approve)

A-4PublishEvent(create)

Application B-1PublishEvent

(approve)

A-2Show (includingfilter/selection)

The solution works because for specific events from ShowAndPublishEvent() and standard events from the publisher. No filtering and selection is carried out in X. The event is simply published, because the filtering and selection are already carried out and the destination is already determined.

For Y, the post-filtering is unused. Instead, the filter and selection from the subscription are included in the show request as used by the publisher and the ShowAndPublishEvent implementation.

Required method hooks

The following sections describe the required logic for on execute hooks.

Important: To keep the basic logic clear, error handling is limited in the example code. For this reason, subfunctions are used. Note that these subfunctions are non-standard functions that you can only use if the functions are implemented in a library, or a define inside the hook.

Helper methods

To be able to forward a request easily to another BDE, the following assisting methods are available.

long replaceBdeNameInRequest( long i.request, const string i.newBdeName,


ref long o.newRequest)

This function replaces the BDE name wherever the name occurs in the request. You can use this function when you forward a request from one BDE to another. The earlier BDE name is the name of the current BDE that contains the hook. If the request belongs to another BDE, the method fails.

The BDE name is replaced, for example:

In the selection If you select attributes or an asterisk in the top-level component

In the filter If you filter on attributes from the top-level component

In the children of the DataArea node If the data area contains any instances

In the eventEntity controlling attribute for the OnEvent method

The limitations are that only the data area and the standard controlling attributes are handled, and therefore specific controlling attributes are not renamed if the attributes contain the BDE name.

Input i.request

Request XML

i.newBdeName New BDE name to be used

Output o.newRequest:

Duplicate of an i.request, in which the BDE name is replaced.

Note: Remember that you must clean up this XML after use.

return value 0 (OK) or an error value

long replaceBdeNameInResponse( long i.request, const string i.oldBdeName, ref long o.newResponse)

This function replaces the BDE name wherever the name occurs in the response. You can use the BDE name after you forward a request from one BDE to another. The new BDE name will be the name of the current BDE that contains the hook.


The limitation is that only the data area and the standard controlling attributes are handled, and therefore specific controlling attributes are not renamed if the attributes contain the BDE name.

Input i.response:

The response XML

i.oldBdeName: The former BDE name to be replaced

Output o.newResponse:

The duplicate of i.response, in which the BDE name is replaced

Note: Remember that you must clean up this XML after use.

return value 0 (OK) or an error value.

long removeStandardEventsFromRequest( long io.request, ref boolean o.anyEventActionLeft) This function removes the standard event actions from a SubscribeEvent request.

Input io.request

SubscribeEvent request XML

Output io.request

The request after you remove eventAction elements for standard events: create, change, or delete

o.anyEventActionLeft

True At least one, specific event action is to remain in the control area.

False Event actions are no longer listed.

This output parameter is required, because when you forward a request that has no event actions specified, this setting is interpreted as a request for all standard events.


return value 0 (OK) or an error value

long getRequest()

You can use this function if the request must be forwarded to another BDE, but the method is not a batch method.

Do not use this function for batch methods, because in that case the request is available as an input parameter. Do not change the request or the contents of the request. Instead, use replaceBdeNameInRequest()or duplicate the request before you make changes.

Input

None.

Output return value

Reference to the request XML. 0 in case of error.

SubscribeEvent

The on execute hook for the SubscribeEvent of BII X contains the following code:

#pragma used dll oppmmmbl002sb00 | BDE Y #pragma used dll oppmmmbl003sb00 | BDE Z #define CHECK_RET(retval, ...) ^ if retval <> 0 then ^ dal.set.error.message(…) ^ return(DALHOOKERROR) ^ endif long requestY | request xml for Y long requestZ | request xml for Z long responseY | response xml from Y long responseZ | response xml from Z long resultY | result xml from Y long resultZ | result xml from Z boolean anyEventActionLeft | whether request contains any non-standard events long retl | return value to be checked long duml | dummy variable | forward request to Y retl = replaceBdeNameInRequest(i.request, “Y”, requestY) CHECK_RET(retl) retl = ppmmm.bl002sb00.SubscribeEvent(requestY, responseY, resultY) duml = xmlDelete(requestY) if retl = 0 then duml = xmlDelete(responseY) else


o.result = resultY o.response = 0 dal.set.error.message(…) |* Failed to execute SubscribeEvent for Y which implements X return(DALHOOKERROR) endif | forward request to Z retl = replaceBdeNameInRequest(i.request, “Z”, requestZ) CHECK_RET(retl) retl = ppmmm.bl003sb00.SubscribeEvent(requestZ, responseZ, resultZ) duml = xmlDelete(requestZ) if retl = 0 then duml = xmlDelete(responseZ) else | limitation: the request for Y already succeeded; we should merge resultZ into | the response information area instead? o.result = resultZ o.response = 0 dal.set.error.message(…) |* Failed to execute SubscribeEvent for Z which implements X return(DALHOOKERROR) endif | determine request for default handling of X retl = removeStandardEventsFromRequest(i.request, anyEventActionLeft) | note: strictly speaking we are not allowed to change input parameter i.request, | but we cannot avoid this here CHECK_RET(retl) if anyEventActionLeft then | note: must not do this if no event actions left, because then we would get a | subscription for all standard event actions on X, which is incorrect! io.default = true | to make sure a subscription is created for X for specific events else | we are ready o.response = xmlNewNode(“SubscribeEventResponse”) endif return(0) | OK Y and Z receive the default implementation for SubscribeEvent().

UnsubscribeEvent

The implementation for the UnsubscribeEvent() is comparable to the implementation for SubscribeEvent(), but a bit simpler. The on execute hook for the UnsubscribeEvent of X contains the following code:

#pragma used dll oppmmmbl002sb00 | BDE Y #pragma used dll oppmmmbl003sb00 | BDE Z long retl | return value to be checked long duml | dummy variable


retl = ppmmm.bl002sb00.SubscribeEvent(i.request, responseY, resultY) retl = ppmmm.bl003sb00.SubscribeEvent(i.request, responseZ, resultZ) duml = xmlDelete(responseY) duml = xmlDelete(responseZ) if resultY <> 0 or resultZ <> 0 then o.result = combine.results(resultY, resultZ) | to be defined; unavailable in standard duml = xmlDelete(resultY) duml = xmlDelete(resultZ) dal.set.error.message(…) return(DALHOOKERROR) else o.result = 0 io.default = true | to make sure the subscription is removed for X! | Limitation: if no subscription was created for X (because | the subscription didn’t contain any specific events), a result | will be returned even through the method succeeded return(0) | OK endif Y and Z receive the default implementation for UnubscribeEvent().

PublishEvent

X receives the default implementation for PublishEvent().

The on execute hook for the PublishEvent in Y contains the following code:

#define CHECK_RET(retval, ...) ^ if retval <> 0 then ^ dal.set.error.message(…) ^ return(DALHOOKERROR) ^ endif long request | PublishEvent request for BDE X long retl | return value to be checked long duml | dummy variable (PublishEvent does not return an error value) retl = replaceBdeNameInRequest(i.request, “X”, request) CHECK_RET(retl, ...) retl = exec_dll_function(“oppmmmbl001sb00”, “ppmmm.bl001sb00.PublishEvent”, duml, request, o.response, o.result) | We must dynamically invoke this method, because Y is generated | from the Integration Studio before generating X, so a direct invocation | of X from Y would not compile | Note: PublishEvent never returns an error value (instead it publishes an error message if needed) | so we only need to check whether the load and exec was successful CHECK_RET(retl, ...) duml = xmlDelete(request) return(0) | OK The implementation for Z is comparable to the implementation for Y.


OnEvent

The OnEvent implementation for X is as follows:

#pragma used dll oppmmmbl002sb00 | BDE Y #pragma used dll oppmmmbl003sb00 | BDE Z #define CHECK_RET(retval, ...) ^ if retval <> 0 then ^ dal.set.error.message(…) ^ return(DALHOOKERROR) ^ endif | implementation is incomplete; see note below long request | OnEvent request for BDE Y or Z long retl | return value to be checked long duml | dummy variable (PublishEvent does not return an error value) type = getTypeFromRequest(i.request) on case type case “type1”: retl = replaceBdeNameInRequest(i.request, “Y”, request) CHECK_RET(retl, ...) retl = ppmmm.bl002sb00.OnEvent(request, o.response, o.result) duml = xmlDelete(request) CHECK_RET(retl, ...) return(0) | OK | no break because of return case “type2”: retl = replaceBdeNameInRequest(i.request, “Z”, request) CHECK_RET(retl, ...) retl = ppmmm.bl003sb00.OnEvent(request, o.response, o.result) duml = xmlDelete(request) CHECK_RET(retl, ...) return(0) | OK | no break because of return default: o.response = 0 o.result = 0 dal.set.error.message(…) return(DALHOOKERROR) endcase Note: The OnEvent has the same issue as the Change method, in case the type is changed or unavailable. For more information, refer to the section “Other methods,” later in this chapter.

The OnEvent implementation for Y and Z can be the default implementation.

Other methods

For Create, Change, Delete, and comparable specific methods, the implementation for X is comparable to OnEvent(). Note, however, that those


methods do not process scope batch methods, and therefore the request is not an input parameter for the on execute hook, but must be retrieved by means of getRequest().

Issue for change

If the type is changed, the change request is sent to the incorrect implementation, which is the implementation that does not yet contain the object instance.

Solution

Try to change Y. If that fails, do the following:

1 Show Z

2 Merge the Show response and Change request.

3 Send the result of the merger as a create to Y.

Issue for change

The type might not be included in the request, in other words, the type might not occur in practice if the type is in the top-level component, because all attributes must always be available for the top level.

Issue for delete

You never know the type from the request.

Solution

Try both and at least one usually fails.

You can also use the ‘batch’ processing scope for the List and Show methods. For List, Show and specific comparable methods, both Y and Z must be invoked. For List, both responses must be merged, but for Show, only one BDE will return a response; that response can be used. Additionally, for both methods, you must perform a replaceBdeNameResponse(response, “X”, o.response).

4 Chapter 4 To Generate Events from the Application

If you subscribe to one or more standard events, such as create, change, or delete, a publisher starts in ERP LN that detects the events based on the audit trail and publishes the corresponding event messages.

If you subscribe to specific events, the subscription is stored in ERP LN, but is passive. You must create the event from the application.

The following methods are available to create the event in this way:

Use the standard PublishEvent method. As a result, the application is responsible for building the request (XML) in accordance with the BDE definition.

Use the ShowAndPublishEvent method. In this case, the application can simply specify the values for the identifying table columns to initiate the event at BDE or component level. The BDE runtime collects the required data, builds the request XML, and invokes the PublishEvent method to perform the actual publishing. For more information, refer to “ShowAndPublishEvent” in this chapter.

Use the ShowAndPublishStandardEvent method. This method publishes standard events from the application in addition to, or instead of, publishing them based on the audit trail. This method is comparable to ShowAndPublishEvent, but cannot be used for application-specific events, but for standard events (create, change, or delete) only. Note that you can also use the PublishEvent method to publish standard events.

In theory, you can invoke the PublishEvent, ShowAndPublishEvent or ShowAndPublishStandardEvent from any script or library in the application. Logical places to implement the invocation include, for example:

Data access layer For events related to database changes or execution of a business method

4-2 | To Generate Events from the Application

User interface script For events linked, for example, to a specific form command.

Note: You cannot generate standard events, such as create, change, or delete, from the application.

Transactional Event Publishing

Publishing from the ERP LN application is transactional. This means the publishing is done within a database transaction. The actual publishing is postponed until the end of the transaction. If the transaction is committed, the event is published. If the transaction is aborted, the event will not be published.

When you invoke PublishEvent or ShowAndPublish(Standard)Event from the application, first the subscription is checked. If a subscription exists for the specified BDE and eventAction, the request is stored in a queue. The enqueuing will only be effective if the transaction is committed by the application. In case of an abort, nothing is published.

A publisher process is not only running in case of a SubscribeEvent on standard event actions, but for all event actions (also when the standard publishing process is suppressed in an on execute hook for SubscribeEvent). The publisher does not only check for standard events as logged in the audit trail, but also for application events from the queue. The events from both sources are sequenced correctly. Technically, the audit trail facility is reused for the application events, so the time each application event gets a commit time and a transaction ID.

This approach has a number of advantages:

When publishing inside a transaction, the event will not be published if the application’s database transaction is aborted.

All events (from PublishEvent, from ShowAndPublish(Standard)Events and from the standard audit trail entries) are sequenced correctly.

The performance impact for the application is limited, because the aggregation and publishing of events is done ‘offline’.

Important: This means that you must always invoke PublishEvent, ShowAndPublishEvent and ShowAndPublishStandardEvent from the application inside a database transaction. So, you must set a retry point before publishing and you must perform a commit or abort afterwards. This must be the same application transaction that actually initiates the event. For example, if an Order row is changed and an event is published because of that, the change of the row and the publication of the event must be in the

To Generate Events from the Application | 4-3

same transaction scope. In this way, an event is only published if the corresponding database change succeeds.

Testing

For testing and troubleshooting an event publishing implementation, refer to the following section "Publish Event".

PublishEvent

If you use the PublishEvent method, include the complete BDE instance where possible. From the application perspective, simply including an identifier, such as an order number, can suffice. However, in this case, you cannot apply filtering on any other attributes or components.

Public method

The PublishEvent method is available in the public library. The method name is <prefix>.PublishEvent.

The input/output for this method is:

Input request (long): xml containing the PublishEvent request. Include the control attributes and data area in accordance with the BDE standard. In the data area, include the complete BDE instance where possible. From the application point of view only including an identifier (such as an order number) will be sufficient. However, if you omit all attributes and components except the identifying attributes, you cannot apply filtering on these non-primary key attributes or components.

Output response (long): xml containing the response. Because the error is handled inside the PublishEvent method, the response will only contain a single ‘PublishEventResponse’ node. After invoking the method, you must clean up the used XML structure with xmlDelete().

Output result (long): xml containing the result. Because the error is handled inside the PublishEvent method, the result will always be empty.

The return value will always be 0.

Example

If the public library of a BDE is ppmmmbl999sb00, the interface for the PublishEvent function in that library is as follows:

long ppmmm.bl999sb00.PublishEvent(long i.request, long o.response, long o.result)


Specifications

When invoking the PublishEvent() method, the following happens:

If no subscription exists for the BDE, nothing happens.

If a subscription does exist, the following steps are executed:

The request is enqueued.

The transaction is committed.

After committing the transaction, a publisher process picks up the request and publishes the event, if the event matches the subscription filter.

Notes:

You can use PublishEvent for both standard events (such as create, change or delete) and application-specific events. For more information, refer to the following section "ShowAndPublishStandardEvent".

The method must be called from within a database transaction, as described in following section "Transactional Event Publishing".

After invoking the method, you must clean up the request xml and response xml using xmlDelete().


If an on execute hook is linked to the PublishEvent, this hook is executed immediately within the user transaction (so without enqueuing first). If io.default is set to 'true', the event is enqueued after executing the hook. For that event, the hook is not executed twice.

The background for this procedure is that you cannot check the subscription and enqueue the event first, because the code of the hook is still unknown. For example, the hook can write to a table, thus requiring a database transaction context (which the publisher process does not have). Or the hook can change the contents of the event before executing the default process, so you cannot check the subscription before invoking the hook. Or the hook can contain subscription-independent actions, so again you cannot check the subscription before invoking the hook.

This implies that a PublishEvent hook is not always executed at the same moment:

If the application invokes PublishEvent directly, the hook is executed inside the application transaction. No queuing is carried out.

If the application invokes ShowAndPublish(Standard)Event, the event is first queued, so the PublishEvent is carried out asynchronously, outside the application transaction and application context.


ShowAndPublishEvent and ShowAndPublishStandardEvent also publish their events through PublishEvent. However, in that case the event is immediately published and is not enqueued first.

ShowAndPublishEvent

Note: You cannot use the ShowAndPublishEvent method to generate standard events (create, change, delete). Use ShowAndPublishStandardEvent instead.

Protected method

To publish application events, the following method is available in the protected library:

<prefix>.<component>.ShowAndPublishEvent()

The first argument of this method is a string that indicates the event action, for example, approve or cancel. The other arguments, of which at least one exists, contain the values for the attribute implementations that represent the root table’s key columns.

Example:

Assume that an order BDE exists. The protected layer is implemented in library ppmmmbl999st00. The root component maps to table ppmmm999.

The primary key of the table ppmmm999 is otyp, orno. The BDE has two attribute implementations for these columns:

orderType

orderNumber

The public identifier is orderID, which is calculated from orderType and orderNumber.

In this case, the method is:

ppmmm.bl999st00.Order.ShowAndPublishEvent( const string i.eventAction, domain ppmmm.otyp i.orderType, domain ppmmm.orno i.orderNumber)

The i.eventAction can be any string, as long as it matches the BDE standard for event actions, except one of the reserved keywords for standard event


actions, such as “create’, “change”, or “delete”. The i.eventAction must always be filled.

The implementation of this method first determines the value for the order ID based on the final two input parameters. Next, the implementation builds and publishes the corresponding event.

If you invoke the method as follows:

ppmmm.bl999st00.Order.ShowAndPublishEvent( "cancel", ppmmm.otyp.purchase, "123")

then the following event, for example, is published:

<EventMessage> <ControlArea> <eventEntity>Order</eventEntity> <eventAction>cancel</eventAction> <eventTimeStamp>2007-01-16T10:56:38Z</eventTimeStamp> <eventSupplier>ERP LN 6.1 Company 590</eventSupplier> </ControlArea> <DataArea> <Order> <orderID>PUR_00123</orderID> <orderDate>2007-01-10T10:56:38Z</ orderDate > <Line> <orderLineNumber>1</orderLineNumber> <item>100</item> <quantity>12</quantity> <price>9.99</price> <orderedQuantityValue>100</orderedQuantityValue> </Line> <Line> <orderLineNumber>2</orderLineNumber> <item>200</item> <quantity>1</quantity> <price>39.95</price> </Line> </Order> </DataArea> </EventMessage>

Specifications

If you invoke the ShowAndPublishEvent() method, the results are as follows:

1 If no subscription exists for the BDE no further actions occur. Otherwise, the following steps are carried out.

2 The request is enqueued. After committing the transaction, a publisher process picks up the request and executes the following steps.

3 The public identifying attribute values are determined, based on the protected identifier.


4 The Show method is invoked to retrieve the object instance. The filter and selection, as specified in the subscription from the event consumer, are used. If the object instance does not match the filter, nothing is published.

5 The PublishEvent() method is invoked to perform the actual publishing, depending on the existing subscription.

Notes:

Error handling The method does not fail and consequently does not return an error. Instead, if an error occurred, the message is published to the error handler linked to the destination, for example, if the specified identifying values cannot be translated to a valid public identifier, or if the Show invocation failed.

If the environment or package combination does not contain an Infor Integration Adapter, or if the environment contains a version that does not support event publishing, a log entry is written in the $BSE/log directory.

Transaction handling You can call this method either from within a database transaction or outside a database transaction. If you call the method from within a database transaction, and the publishing succeeded but the transaction was stopped, the publishing is not undone.

Every BDE that has a PublishEvent() method also has a ShowAndPublishEvent() method. The ShowAndPublishEvent() must not be modeled in the Integration Studio and cannot be customized. You cannot, for example, define method hooks.

To use ShowAndPublishEvent for subcomponents

You can use a ShowAndPublishEvent() method for subcomponents, for example:

ppmmm.bl999st00.OrderLine.ShowAndPublishEvent( const string i.eventAction, domain ppmmm.otyp i.orderType, domain ppmmm.orno i.orderNumber, domain ppmmm.line i.lineNumber)

If you invoke ShowAndPublishEvent() for a subcomponent, the following component instances are included in the event message:

The specified component instance

All of the specified component instance’s children, grandchildren, and so on

All the component instance’s parents, grandparents, and so on.


Note: Siblings of the specified components and of the component’s parents are not included.

The following is an example of a BDE that consists of three levels:

ShowAndPublishEvent on order X Include orders X, all order lines of X, and all sublines of those order lines, depending on the selection and filter.

ShowAndPublishEvent on order X line 1 Include order X and order line 1 and all sublines of order line 1, depending on the selection and filter. Therefore, order line 2 and so on are not included.

ShowAndPublishEvent on order X line 1, subline 3 Include order X, order line 1, and subline 3, depending on the selection and filter. Therefore, order line 2 and so on are not included, and sublines 1, 2, and 4 of order line 1 are also not included.

ShowAndPublishStandardEvent

Introduction

You can publish standard events (create, change, or delete) from the ERP LN application. Generally, when receiving a SubscribeEvent request that includes one or more standard event actions (create, change, or delete), auditing is switched on for the BDE’s database tables. The audit trail is automatically populated, so standard events do not need to be published from the ERP LN application. A running publisher picks up the database changes (from the audit trail) and publishes the corresponding events.

However, database changes cannot always be detected from the audit trail. For example, because the BDE or some of its subcomponents are not directly related to ERP LN tables. In such situations, you can suppress a standard publisher that is based on the audit trail for the BDE tables by configuring the BII. More specifically, you can suppress this audit-based publisher in the on execute hook for the SubscribeEvent method.

Some examples:

If the BII specifies that no standard publisher must be started for any standard events, the subscription is simply stored and the publisher will wait only for application events to arrive. Consequently, all standard events must be generated from the ERP LN application.

If the BII specifies that no standard publisher must be started for the standard ‘change’ event, and that when a subscription arrives for ‘create’,


‘change’ and ‘delete’ events, a standard publisher must be started for the ‘create’ and ‘delete’ events. Only the ‘change’ event must be published from the ERP LN application.

This section explains how you must configure (program) this BDE behavior. The next paragraphs explain how to model the business interface implementation in the Integration Studio, and how to implement the publishing of standard events in the application.

How to model the BII to publish standard events from the application

Specifications

In the implementation of the SubscribeEvent method, you can indicate if standard events originate from the application instead of from the audit trail. This is done through a helper method called suppressStandardPublisher(), which you can apply in the on execute hook for the SubscribeEvent method.

The suppressStandardPublisher() can be called without parameters or with one or more strings containing standard event actions (“create”, “change” or “delete”). The sequence of the arguments does not matter.

For example:

If you specify suppressStandardPublisher() without arguments, all events are published from the ERP LN application. The publisher will not pick up standard events from the audit trail.

If you specify suppressStandardPublisher("change", "delete"), events that involve eventAction ‘change’ or ‘delete’ are sent from the ERPLN application. A standard publisher process deals with the standard ‘create’ event, which means that a standard publisher only reads changes from the audit trail that concern subscription requests containing the ‘create’ eventAction.

Specifying suppressStandardPublisher("create", "change", "delete") has the same effect as specifying suppressStandardPublisher().

To use suppressStandardPublisher() in the on execute hook for SubscribeEvent is only useful if io.default is set to 'true'. If io.default is 'false', the default process is not executed, so no publisher is started either.


Example

The following code gives an example of an on execute hook that suppresses the standard publisher process for ‘change’ events. The standard, audit trail-based publisher will still be used for ‘create' and 'delete' events:

suppressStandardPublisher(“change”) io.default = true return(0) | OK You can use this hook, for example, if the top-level component of the BDE is linked to an ERP LN database table, but the subcomponents of this BDE are not.

How to adapt the application to publish standard events

To use PublishEvent

When publishing standard events through PublishEvent, make sure the event message conforms to the BDE standards. For example:

For eventAction 'create': the event message must contain all involved component instances, and for each component, all attributes must be included.

For eventAction 'change': the event message must contain the changed (or created or deleted) component instances together with their parents. For each component, the message must include all attributes. If a component is created, deleted, or unchanged, the actionType attribute must be set accordingly.

For eventAction 'delete': the event message only includes the top-level component and only contains identifying attributes.

For more information on filtering, refer to the Filtering Notes below.

To use ShowAndPublishStandardEvent

The interface for publishing standard events from the application is the protected ShowAndPublishStandardEvent() method. This method is similar to the ShowAndPublishEvent() method, with the exception that the event action is not specified. The action type at component level is specified instead.

The interface is as follows:

ppmmm.bl999st00.OrderLine.ShowAndPublishStandardEvent( const string i.actionType, domain ppmmm.otyp i.orderType, domain ppmmm.orno i.orderNumber, domain ppmmm.line i.lineNumber)


The action type argument defines the action for the component and must always be filled. The allowed values for action type are “create”, “change” and “delete”. The event action is not specified explicitly and is derived from the action type. In this case, because OrderLine is a subcomponent, action type create, change or delete will result in an event having eventAction ‘change'. For a top-level component, the event action will automatically be the same as the action type.

Important: Be aware that a ‘create’ or ‘delete’ on a non-root table row must be published as a ‘change’ on the component. An action on a non-root table does not create or delete the component instance, because the corresponding row on the root table is not created or deleted.

In case of a delete action, only the specified component instance and its parent(s) are published. No deleted child components are published.

Note: To read and add children using action type 'delete' is not logical, because this would make the delete event inconsistent with the Show response.

In case of a change action, only the specified component instance and its unchanged parent(s) are published. No unchanged (or changed) child components are published.

In case of a create action, any subcomponents of the specified component instance having action type 'create' are also published.

Limitation: you cannot publish changes on multiple component instances in a single event message (for example, a change of two order lines, or a create on order line 1 and a delete on order line 2).

Important: You cannot use the ShowAndPublishStandardEvent() method for specific events (such as ‘approve’) and you cannot use the ShowAndPublishEvent() method for standard events (‘create’, ‘change’ or ‘delete’).

For more information on filtering, refer to the Filtering Notes below.

Filtering Notes

At runtime, event messages can be filtered with a filter that is specified in the SubscribeEvent request. However, in case of standard events, filtering can lead to problems for two reasons:

In case of change or delete events, the event that is sent does not contain the complete object including its subcomponents. For delete events, only the identifying attributes from the top-level component are included. For


change events, only changed (or created or deleted) components instances and their parents (if any) are included.

In case of delete events, the corresponding object or component instance is not available, so filtering cannot be done unless only identifying attributes are involved.

For example, when filtering on OrderLine.item = “X”, you cannot apply the filter for a delete or change on the Order (header).

For PublishEvent and ShowAndPublishStandardEvent, a specified filter is implemented as follows:

For eventAction ‘delete’, no filter is applied.

For eventAction ‘change’:

For PublishEvent no filter is applied.

For ShowAndPublishStandardEvent, no filter is applied if actionType ‘delete’ is used on any component instance. If actionType ‘delete’ is not used, the filter is applied.

For eventAction ‘create’, the filter is always applied.

If the filter is not applied and an appropriate subscription exists, the event is always published and the event consumer can receive irrelevant events (events that not comply with the filter conditions).

5 Chapter 5 To Import from BOR Repository

Introduction

The Business Object Repository (BOR) in ERP LN contains BDE definitions. Before ERP LN FP2, the BOR was used to develop BDEs for ERP LN. In FP3, the Integration Studio is used instead.

The Business Object Repository is available in FP3 to enable maintenance on Business Objects developed in previous versions or Feature Packs.

Important: You must not use the Business Object Repository to develop new BDEs.

You can partially migrate BDE definitions to the Integration Studio by means of the Import from BOR feature of Integration Studio.

The Import from BOR feature, however, is not designed to generate proxies or WSDL. You can use the feature for this purpose, but in that case note the following:

Only BDEs that were created in the BOR can be imported;

Import from BOR imports both the BII and the BID, while only the BID is required to generate proxies or WSDLs.

Prerequisites

You can only use the Import from BOR feature of Integration Studio if you have development authorizations. In other words, you can only import BDEs

5-2 | To Import from BOR Repository

if you can also view the corresponding definitions in the Business Objects (ttadv7500m000) session.

Before you use Import from BOR, set the SSA Connectivity preferences to specify the BusComponent for the runtime repository:

On the Window menu, click Preferences SSA Connectivity.

In the BusComponent field on the Runtime Repository page, specify a BusComponent that refers to company 000 of the ERP LN environment that contains the BDEs to be imported.

Make sure the BusComponent is installed and running before you use the Import from BOR feature.

Finally, an interface project must be available or created into which to import the BDE.

To import from BOR

To import from BOR, take the following steps:

1 Right-click the project that must contain the imported definitions and, on the shortcut menu, click Import….

2 Click the SSA ERPLN BOR option and click Next.

If the connection to the ERP LN environment is set up correctly, as described in “Prerequisites” in this chapter, you see a list of all the BDEs in the BOR. The same BDE name can occur multiple times if multiple versions of the BDE exist.

3 Select the BDE you want to import. You can select multiple BDEs, however, to avoid overwrites, do not select multiple versions of the same BDE.

4 Click Finish to start the import.

Post-import

Important: The imported definition is merely a starting point for remodeling the BID and BII.

The import from BOR does not import all aspects for a BDE as modeled in the BOR. The reason for this is due to the differences between the model as used in the BOR and the model as used in the Integration Studio.

To Import from BOR Repository | 5-3

The following basic aspects are imported:

The complete BID, including the used data types

The tables used in the BDE, as defined in the BOR

The BII, including the attribute implementations for the attributes and the attribute implementations that map directly to table columns. For calculated attribute implementations, the mapping is set to Not Applicable.

Examples of limitations include:

Complex mappings, using calculations, are not imported. In addition, used attributes are not defined. Attribute implementations for calculated attributes receive type notApplicable.

A number of constructions permitted in the BOR cannot be used in the Integration Studio, for example:

BDEs previously could be modeled without a component.

The name of the main component could differ from the BDE name.

The structure of components and attributes could differ for each method.

A BID is usually independent of the implementation. Therefore, for example, the data types used in the BID does not have a native data type specified. The data types used in the BII must have a native data type.

The imported definition does not always follow the naming conventions used when you define a business interface in the Integration Studio from scratch.

As a result, after you import, you must adapt the BID as required, complete the BII, and solve problems (warnings or errors) as reported.

Compatibility at runtime

In general, the Business Object Layer (BOL), which is the BDE runtime based on the BOR, is compatible with the BDE runtime as generated from the Integration Studio. You can use the BOL in combination with ERP LN FP3 and Open Architecture 6.0 or 6.1.

However, you cannot always perform migration to the Integration Studio without impact on the interface at runtime.

5-4 | To Import from BOR Repository

Examples:

As described in the section “After the import,” you cannot define some of the interfaces permitted in the BOR by means of the Integration Studio.

Event publishing functions have changed. In FP2, PublishChanges, UnpublishChanges, and PublishList were used. While you can still use these functions, if you migrate the BDE from the BOR to the Integration Studio, you must use the new functions, which are:

SubscribeEvent

UnsubscribeEvent

SubscribeList

PublishEvent

6 Chapter 6 Event Publishing Deployment

This document does not contain a great deal of information on the behavior and management of ERP LN BDEs at runtime. For information on the runtime aspects of event publishing methods, refer to the Event Publishing Deployment Guide (U8780A US) of the ERP LN FP2 release.

If you refer to the FP2 documentation, you must bear in mind that several methods have changed:

The methods PublishChanges, UnpublishChanges, and PublishList are replaced by SubscribeEvent, UnsubscribeEvent, and SubscribeList.

The following sections provide notes specific to the Event Publishing solution, as available in ERP LN FP3.

What happens in ERP LN

If you use ERP LN as an event consumer, ERP LN behaves like any BDE-compliant application server. The OnEvent method runs, which in turn can invoke other methods, depending on the method’s implementation. By default, a ‘create’ event will be processed, for example, by invoking the ‘Create’ method and an ‘approve’ event will be processed by invoking the ‘Approve’ method.

However, if you use ERP LN as an event producer, some persistent data is retained for each subscription.

If you invoke the SubscribeEvent method, the following actions are carried out in ERP LN:

A subscription is stored.

6-2 | Event Publishing Deployment

An audit profile is created to detect the database changes and application events for the BDE, and a publisher process is started to pick up the changes and publish the corresponding event messages.

User interface

To view the subscription, including the publisher settings and status, run the Event Subscriptions (tlbct5500m000) session.

To view the audit profiles, run the Audit Profiles (ttaud3110m000) session.

Detecting and publishing events

The audit is comparable to the procedure described in the Event Publishing Deployment Guide from the FP2 release. You must take the same precautions described in that document.

Note that after you subscribe to one or more standard events, such as create, change, or delete, you must restart all the bshells to make sure that the required change events are written correctly to the audit trail.

To pick up the relevant changes from the audit trail, a process will be running. This type of publisher process runs in a separate bshell to enable you to close your BW without interrupting the publishing process, and to enable the publishing process to use the correct audit settings.

By default, one bshell is used for each ERP LN company, and one process is used for each destination in that bshell: the event consumer BusComponent. As a result, the sequencing of events is guaranteed for each destination.

If you pause or interrupt a process, you can continue the process. To do so, you must resend the SubscribeEvent, if the user did not pause the process, or run the Event Subscriptions (tlbct5500m000) session.

The process always starts at the point at which the process stopped, unless an UnsubscribeEvent request is received. However, you can send duplicate events if the process stopped between the moment at which the event was published and the moment at which the process actually updated the event’s status. In addition, the risk of failure to publish and event increases as the backlog increases, because the likelihood that the BDE instance is no longer the same as at the moment the event occurred also increases.

A new subscription cannot take effect for ‘old’ events that are not yet processed, so those events are skipped. Old events can occur if a

Event Publishing Deployment | 6-3

subscription exists but the process is not running when new SubscribeEvent request arrives, and the destination (Bus Component) is changed or the selection or filter of the new request requires more database table columns to be monitored.

In other cases, if you want to make a fresh start, first unsubscribe before sending the new SubscribeEvent request.

To publish application events

If you subscribe to an application-specific event, make sure the application can actually publish that event. For details, refer to the “To Generate Events from the Application” chapter.


Transaction event publishing has some impact on deployment.

For application events, the audit trail is reused in combination with the tlbct520 table. You must create this table in all companies where event publishing is required. (In general, this is automatically done during the installation.) So, this table does not only exits in company 000.

The table itself will not take much space, because it will only contain temporary data, which is immediately deleted again. Auditing for the tlbct520 table is set up automatically in the publisher’s audit profile. Sufficient space must be available for the audit trail on the tlbct520 table. You must purge the audit data when you do not need the data anymore. If all publishers are running and the events are received by the event consumer successfully, the corresponding audit data can be purged rather quickly. Purging can be done automatically by running the Purge Audit Files (ttaad4261m000) session in a job.

Limitations on associated data

When publishing events, data from other (associated) BDEs can be included. For example, the itemDescription will be added to the OrderLine component.

However, if you use SubscribeEvent, associated data can only be included successfully if the involved attribute value is completely static. The fact is that changes on instances of the associated object are not detected as changes on the object for which events are published. For example, changes on the item description of an Item BDE will not be detected automatically when publishing events for a SalesOrder BDE. Consequently, clients that receive changes on sales orders will not be notified if the item description is changed. If these clients want to be informed about changes on the item, they must

6-4 | Event Publishing Deployment

issue another SubscribeEvent request for the Item BDE (and consequently, the order object does not require the item description anymore).

The previous constraints also apply if you select a calculated attribute that uses data from tables outside the BDE's scope, but without modelling a BDE relation,

Troubleshooting

If Event Publishing does not work as expected, check the following:

Is the subscription available in ERP LN? To check if the subscription is available in ERP LN, run the Event Subscriptions (tlbct5500m000) session.

Is an error logged? By default, the error is sent to the error handling BusComponent linked to the event consumer BusComponent, as specified in the SubscribeEvent request. If that error handler could not be reached, the error is visible in the Infor Integration log on ERP LN, or in the $BSE/log/tlpublishevent file.

Does the ERP LN company match the company to which the subscription was sent?

Was the event suppressed due to the selection or filter specified in the SubscribeEvent request?

In case of standard events, such as create, change, or delete, check the following:

Is the publisher running? To check this, run the Event Subscriptions (tlbct5500m000) session.

Is the audit profile available and was the bshell restarted before you initiated the event?

In case of application-specific events, check the following:

Can the application publish the event?

Were the correct actions carried out to initiate the event?

To perform tracing

To check whether an event is picked up and processed correctly, you can use the tracing facility. In this way, you can check the publishing activity on ERP LN. The file contents indicate any publisher activity and any events being processed or sent. You can also use the tracing facility to see if an

Event Publishing Deployment | 6-5

event message does not match the event actions, filter, or selection from the subscription.

Add the following setting in your BW configuration:

-set BOL_PUBLISHER_TRACE=/tmp/trace_publisher

After the equal symbol (=), specify the file to which you want the trace to be written. Make sure you have sufficient permissions to write a file in that location.

To trace the detection of standard events and the publishing of all events, you must specify this setting in the BW in which you start the tmbdeserver that receives the SubscribeEvent request. To trace application-specific events, you must also specify this setting in the BW in which you run the application process that publishes the event. You can use two different file names.

Important: The trace file as listed in the tlbct5500m000 session is the trace file as specified at the moment the SubscribeEvent was received. The actual tracing and trace location can be different in two situations. The first situation occurs if a bshell is already running for a BDE and a SubscribeEvent request is received for the same company and destination Bus Component. The publishing for the second BDE will then get the same trace settings as the first one, because the publishing is done by the same bshell. The second situation occurs if all publishers for a company are stopped and a user reactivates them through the tlbct5500m000 session. In that case, the trace setting from that user’s BW configuration will be used.

Note: You can change the trace settings without re-subscribing by simply starting the BW with the desired trace setting, then stop all publishers for a company through the tlbct5500m000 session and then reactivate them again (see previous "Important" remark). To stop the bshell, you must stop all publishers for a company before reactivating them again. After reactivating the publishers from the appropriate BW, the user’s trace settings are applied.

Developer's Guide for BDEs for Infor ERP LN · About this Guide This document is a Developer’s...

Documents

Transcript of Developer's Guide for BDEs for Infor ERP LN · About this Guide This document is a Developer’s...