sap business one integration toolkit for mysap business suite -1.5 developers guide

Function Module Development Guide

SAP Business One Integration Toolkit for mySAP Business Suite - 1.5Document Version 1.50 May 15, 2003

SAP AG Neurottstrae 16 69190 Walldorf Germany T +49/18 05/34 34 24 F +49/18 05/34 34 20 www.sap.com

Copyright 2003 SAP AG. All rights reserved. No part of this publication may be reproduced or transmitted in any form or for any purpose without the express permission of SAP AG. The information contained herein may be changed without prior notice.

JAVA is a registered trademark of Sun Microsystems, Inc. JAVASCRIPT is a registered trademark of Sun Microsystems, Inc., used under license for technology invented and implemented by Netscape. MarketSet and Enterprise Buyer are jointly owned trademarks of SAP

Some software products marketed by SAP AG and its distributors contain proprietary software components of other software vendors.

AG and Commerce One. SAP, SAP Logo, R/2, R/3, mySAP, mySAP.com, and other SAP

Microsoft, WINDOWS, NT, EXCEL, Word, PowerPoint and SQL Server are registered trademarks of Microsoft Corporation. IBM, DB2, DB2 Universal Database, OS/2, Parallel Sysplex, MVS/ESA, AIX, S/390, AS/400, OS/390, OS/400, iSeries, pSeries, xSeries, zSeries, z/OS, AFP, Intelligent Miner, WebSphere, Netfinity, Tivoli, Informix and Informix Dynamic ServerTM are trademarks of IBM Corporation in USA and/or other countries. ORACLE is a registered trademark of ORACLE Corporation. UNIX, X/Open, OSF/1, and Motif are registered trademarks of the Open Group. Citrix, the Citrix logo, ICA, Program Neighborhood, MetaFrame, WinFrame, VideoFrame, MultiWin and other Citrix product names referenced herein are trademarks of Citrix Systems, Inc. HTML, DHTML, XML, XHTML are trademarks or registered trademarks of W3C, World Wide Web Consortium, Massachusetts Institute of Technology.

products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP AG in Germany and in several other countries all over the world. All other product and service names mentioned are the trademarks of their respective companies. Disclaimer Some components of this product are based on Java. Any code change in these components may cause unpredictable and severe malfunctions and is therefore expressively prohibited, as is any decompilation of these components. Any Java Source Code delivered with this product is only to be used by SAPs Support Services and may not be modified or altered in any way.

Typographic ConventionsType Style Example Text Represents Words or characters that appear on the screen. These include field names, screen titles, and pushbuttons, as well as menu names, paths, and options. Cross-references to other documentation Example text Emphasized words or phrases in body text, titles of graphics, and tables Names of elements in the system. These include report names, program names, transaction codes, table names, and individual key words of a programming language, when surrounded by body text, for example, SELECT and INCLUDE. Screen output. This includes file and directory names and their paths, messages, names of variables and parameters, source code, as well as names of installation, upgrade, and database tools. Exact user entry. These are words or characters that you enter in the system exactly as they appear in the documentation. Variable user entry. Pointed brackets indicate that you replace these words and characters with appropriate entries. Keys on the keyboard, for example, function keys (such as F2) or the Strg key.

IconsIcon Meaning Caution Example Note Recommendation Syntax

EXAMPLE TEXT

Example text

Example text

EXAMPLE TEXT

Function Module Development Guide: SAP Business One Integration Toolkit for mySAP Business Suite - 1.5

ContentsA: INTRODUCTION .......................................................................................................................................... 5 Target Audience................................................................................................................................................................ 5 Structure............................................................................................................................................................................ 5 Further Reading ............................................................................................................................................................... 5 B: CONCEPTS AND INFRASTRUCTURE....................................................................................................... 6 SAP Business One Data Interface API as COM Objects .............................................................................................. 6 Java Native Interface and Wrappers .............................................................................................................................. 7 Web Service Facilities....................................................................................................................................................... 8 Web Workbench of the SAP Business One Integration Toolkit................................................................................. 11 C: FUNCTION MODULE DEVELOPMENT KIT ............................................................................................. 12 Java Wrappers for DI-API ............................................................................................................................................ 12 Data Object Mapping.................................................................................................................................................... 12 Help Classes ................................................................................................................................................................. 13 Exceptions Class........................................................................................................................................................... 16 Function Module Framework Interfaces...................................................................................................................... 16 Utility Classes.................................................................................................................................................................. 17 D: FIVE STEPS FOR CREATING FUNCTION MODULES............................................................................ 18 Describing the Scenario.................................................................................................................................................. 18 Designing the Data Model and Business Logic............................................................................................................. 18 Identifying Data Objects in DI-API .............................................................................................................................. 18 Implementing Function Modules .................................................................................................................................. 19 Local Test, Deployment, Remote Test........................................................................................................................... 26 Local Test ..................................................................................................................................................................... 26 Deployment .................................................................................................................................................................. 27 Remote Test.................................................................................................................................................................. 29 Continuous Improvement .............................................................................................................................................. 30 E: APPENDIX.................................................................................................................................................. 33 Appendix A SOAP Head Elements ............................................................................................................................ 33 Appendix B SAP Exchange Infrastructure Integration ........................................................................................... 35

May 2003

4


A: IntroductionThe SAP Business One Integration Toolkit for mySAP Business Suite 1.5 (SAP Business One Integration Toolkit) provides an environment for the SAP Business One system to communicate with other systems, especially SAP systems, via web service. This manual explains how to design, implement, test, deploy and continuously enhance the function modules. The examples in this manual are based on a default installation and may differ from your installation.

Target AudienceThis document has been prepared for partners who want to develop their own function modules when implementing the customer SAP Business One integration project. Specifically, the target audience is developers. Developers should have basic Java programming skills as well as knowledge in the related function area of SAP Business One and the target integrated system. For example, developers should have finance knowledge for general accounting integration.

StructureThis manual can be divided into the following sections: Introduction: This section provides an overview of this document. Concepts and infrastructure: This section explains basic concepts as well as the function modules runtime context. Function module development kit: This section describes how to create functions using the development kit. Five steps to creating a function module This section describes the methodology and explains the development process by means oif a sample function module. Appendix A: SOAP head elements: This section covers all supported SOAP head elements for a specific system integration. Appendix B: SAP Exchange Infrastructure Integration: This section provides an overview of special points of the SAP Exchange Infrastructure Integration.

Further ReadingSAP Business One Integration Toolkit for mySAP Business Suite 1.5 Installation Guide SAP Business One Integration Toolkit for mySAP Business Suite 1.5 Administration Guide http://www.w3.org/TR/SOAP - Simple Object Access Protocol (SOAP) 1.1 SAP J2EE Engine 6.20 Installation Guide SAP J2EE Engine 6.20 Administration Guide SAP Business One Data Interface API (DI-API) Installation Guide SAP Business One Data Interface API (DI-API) Help

May 2003

5


B: Concepts and InfrastructureSAP Business One Data Interface API as COM ObjectsThe component object model (COM) is an object model for creating software applications from independent components. COM objects promote encapsulation and object reuse. SAP Business One provides the SAP Business One Data Interface API (DI-API) using COM objects for external systems to access its data model. Different function areas of SAP Business One are published as COM objects in the DI-API. These COM objects provide a convenient way to manipulate business data in SAP Business One. Some COM objects published in the DI-API are listed below. For more information, see the online documentation on the SAP Business One Data Interface API. Attachment Attachments BusinessPartners Company Contacts DataBrowser Document_Lines Documents Field Fields Items Items_Prices JournalEntries JournalEntries_Lines Messages Payments Payments_Accounts Payments_Checks Payments_CreditCards Payments_Invoices ProductTrees ProductTrees_Lines Recipients Recordset SBObob SerialNumbers SpecialPrices StockTaking StockTransfer

6

May 2003

Function Module Development Guide: SAP Business One Integration Toolkit for mySAP Business Suite - 1.5 StockTransfer_Lines UserFields

This document and the related function module development kit are all based on this Application Program Interface (API) release.

Java Native Interface and WrappersThe Java Native Interface (JNI) is the native programming interface for Java that is part of the Java Development Kit (JDK). The JNI allows Java code running in a Java Virtual Machine (VM) to operate with applications and libraries written in other languages (such as C, C++, and Assembly). JNI can be used by Java code to manipulate the DI-API. To use the DI-API in Java, Java wrapper classes internally manipulate the COM objects using basic Java functionality. The wrappers are implemented with Java Native Interface technology. The architecture looks as follows: API Java Wrapper Java Native Interface Data Interface API

Using this architecture, developers of SAP Business One function modules do not need extensive knowledge of C/C++, COM, or JNI. Instead, they can concentrate on the business logic of the function modules. The Java Wrappers for the DI- API provide an easier alternative. The wrappers are standard Java beans that encapsulate the complicated JNI calls to DI-API while providing a simple interface.

May 2003

7


Web Service FacilitiesUsing Web service facilities, function modules are automatically registered as Web services when they are uploaded into the SAP Business One Integration workbench. Web service facilities are based on SAP J2EE Engine Web service SOAP libraries. In the example below, following a simple function module, the workbench generates Web Services Description Language (WSDL):package com.sap.smb.sbo.module.ver1000;

import java.util.*; import java.text.*; import com.sap.smb.sbo.module.*; import com.sap.smb.sbo.module.ver1000.model.*; import com.sap.smb.sbo.module.ver1000.dao.*; import com.sap.smb.sbo.module.ver1000.util.*; import com.sap.smb.sbo.api.*; import com.sap.smb.sbo.util.*;

public class FinanceFunctionModule implements FunctionModuleInterface {

public void profitCenterCreate(ProfitCenterModel model) throws FunctionModuleException { ICompany company = null;

try { company = SBOCOMProxy.getCompany();

StringBuffer sql = new StringBuffer("select PrcCode from OPRC where PrcCode = '"); sql.append(model.getProfitCenterCode()); sql.append("'"); IRecordset recordset = SBOCOMUtil.runRecordsetQuery(company, sql.toString());

if (recordset.getRecordCount().intValue() > 0) { throw new FunctionModuleException("FinanceFunctionModule.profitCenterCreate Exception: profit center code has already exist : " + model.getProfitCenterCode()); } else { sql = new StringBuffer("insert OPRC(PrcCode, PrcName, GrpCode) values('"); sql.append(model.getProfitCenterCode()); sql.append("', '"); sql.append(model.getProfitCenterName()); sql.append("', '");

8

May 2003

Function Module Development Guide: SAP Business One Integration Toolkit for mySAP Business Suite - 1.5sql.append(model.getProfitCenterSortCode()); sql.append("')"); } SBOCOMUtil.runRecordsetQuery(company, sql.toString());

} catch (SBOCOMException sce) { throw new FunctionModuleException("FinanceFunctionModule.profitCenterCreate Exception: sbo com exception", sce); } finally { try { SBOCOMProxy.releaseCompany(company); } catch (SBOCOMException sce) { throw new FunctionModuleException("FinanceFunctionModule.profitCenterCreate Exception: can't release company", sce); } } }

}

May 2003

9


10

May 2003


Web Workbench of the SAP Business One Integration ToolkitUsing Java wrappers and Web Service facilities, developers can easily create their own version of the SAP Business One function modules to be used by external systems using SOAP/HTTP. The Web workbench is another tool that helps deploy the function modules in the SAP Business One Integration Toolkit. After deployment, the function modules are ready to be used by external systems using SOAP/HTTP. The image below is the GUI of the Web workbench used to upload function modules. Function modules should be packed in a standard JAR file. When uploading, you must specify an arbitrary logical name which will be used by the calling function for the function module and the full-class name of the main entry class of the function module. You then browse to the location of the JAR file and choose the Upload pushbutton to finish the upload.

All uploaded function modules are listed in Function Module WSDL. If you select a specific function name, its WSDL will appear in a new browser window, as shown in the example below:

May 2003

11


C: Function Module Development KitThe Function Module Development Kit provides three kinds of help Java classes: Java Wrappers for DI-API: These are Java beans that map the function and properties of the DI-API. Function Module Framework Interfaces: The general interface and exception class of the function module and its data model. Utility Classes: Useful data types and format converting tools.

A complete Java document for each class and interface is available with the development kit.

Java Wrappers for DI-APIData Object MappingJava wrappers first map the thirty COM objects of the DI-API. Each data object maps to a Java interface with an implementation class behind the interface. However, you only need to work with the interfaces. In the following table, the interfaces and their corresponding COM objects are listed. DI-API Data Object Attachment Attachments BusinessPartners Company Contacts DataBrowser Document_Lines Documents Field Fields Items Items_Prices JournalEntries JournalEntries_Lines Messages Payments Payments_Accounts Payments_Checks Payments_CreditCards Payments_Invoices ProductTrees Java.classWrapper Interface IAttachment.class IAttachments.class IBusinessPartners.class ICompany.class IContacts.class IDataBrowser.class IDocument_Lines.class IDocuments.class IField.class IFields.class IItems.class IItems_Prices.class IJournalEntries.class IJournalEntries_Lines.class IMessages.class IPayments.class IPayments_Accounts.class IPayments_Checks.class IPayments_CreditCards.class IPayments_Invoices.class IProductTrees.class

12

May 2003

Function Module Development Guide: SAP Business One Integration Toolkit for mySAP Business Suite - 1.5 ProductTrees_Lines Recipients Recordset SAP Business Onebob SerialNumbers SpecialPrices StockTaking StockTransfer StockTransfer_Lines UserFields IProductTrees_Lines.class IRecipients.class IRecordset.class ISAP Business Onebob.class ISerialNumbers.class ISpecialPrices.class IStockTaking.class IStockTransfer.class IStockTransfer_Lines.class IUserFields.class

The interfaces are in the package com.sap.smb.sbo.api. The name of the interface has the same name as the data object, with the addition of I as a prefix. Inside the wrapper interface, the properties of the data object are mapped to Java bean get/set methods with the same name with the get or set prefix added. The methods of the data object are mapped to Java bean methods with the same name.

Below is an example of how the Company data object, its CompanyDB property, and its Connect method are mapped. Data Interface API Data Object Name Property Method Company CompanyDB Connect Java Wrapper Interface ICompany public String getCompanyDB() public setCompanyDB(String db) public void connect()

For more information on the data object, refer to its help document. Each property and method of a data object can be found in the mapping method of the corresponding wrapper interface.

Help ClassesIn addition to the mapping wrappers of the COM objects, three help classes facilitate development. SBOCOMProxy.class This help class provides several constant value definitions. These constants are used to create instances of the wrappers or set values of the wrappers. For example, this help class defines constants of the object type of the business partner wrapper:

May 2003

13

Function Module Development Guide: SAP Business One Integration Toolkit for mySAP Business Suite - 1.5 BoObjectTypes_oBusinessPartners When creating instances of the business partner object from the getBusinessObject method of the ICompany interface, the constant is used instead of the integer with the value 2.Object component = aCompany.getBusinessObject(SBOCOMProxy.BoObjectTypes_oBusinessPartners); IBusinessPartners obj = new BusinessPartners(component);

This help class maintains a connection pool of company databases to use the SAP Business One company database connection. Because establishing a connection is highly resource consuming, a connection pool of the company database enables the connection to be set up after the application is started. The established connection is then shared between function modules. A Web service framework initializes the connection pool of company databases as follows:SBOCOMProxy.initialize(1, 2, "localhost", "SAP Business OneDemo_US", "manager", "manager", 3, true);

You only need to carry out this task in the test class of your function module. Usually, you use the connection pool of the company database as follows:ICompany company = null;

try { /* get a free instance of with the connection pool of company database */ company = SBOCOMProxy.getCompany();

/* do something with the connection pool of company database */

} catch (SBOCOMException sce) { sce.printStackTrace(); } finally { /* release the connection any way */ try { SBOCOMProxy.releaseCompany(company); } catch (Exception e) { e.printStackTrace(); } }

14

May 2003


In the above code: The connection pool of the company database is initialized outside of the function module. The company database pool is initialized in the Web service framework or your test class. Release the connection after using it. Otherwise, it cannot be used by other function modules. To confirm the initialization, you can use the following method: SBOCOMProxy.assertInitialiezed(); Initializations that have not yet completed throw the SBOCOMException. SBOCOMUtil.class The SBOCOMUtil.class provides a convenient way to create new wrappers of the data object or gets existing wrappers of the data object by key. To create a new business partner wrapper:IBusinessPartners wrapper = SBOCOMUtil.newBusinessPartners(company);

To get a business partner wrapper:IBusinessPartners wrapper = SBOCOMUtil.getBusinessPartners(company, model.getCardCode());

This class has general methods such as the following: Synchronized public static IRecordset runRecordsetQuery(ICompany company, String sql) throws SBOCOMException SBOErrorMessage.class The SBOErrorMessage.class is a data model that holds the errors returned by the DI-API. Normally, it provides more details about why an operation failed. Sample code is provided below.Icompany company = null;

try { /* get a free instance of with the connection pool of company database */ company = SBOCOMProxy.getCompany();

/* do something with the connection pool of company database */ IBusinessPartners wrapper = SBOCOMUtil.newBusinessPartners(company); wrapper.setCardCode(C0001); wrapper.setCardName(Customer 0001); Int result = wrapper.add();

if (result != 0) { SBOErrorMessage sboError = company.getLastError(); System.out.println(Last Error Code : + sboError.getErrorCode()); System.out.println(Last Error Msg } : + sboError.getErrorMessage());

May 2003

15

Function Module Development Guide: SAP Business One Integration Toolkit for mySAP Business Suite - 1.5} catch (SBOCOMException sce) { sce.printStackTrace(); } finally { /* release the connection any way */ try { SBOCOMProxy.releaseCompany(company); } catch (Exception e) { e.printStackTrace(); } }

If an error is to be added, a new customer getLastError method of the ICompany is used to get the SBOErrorMessage, which then provides details about the error.

Exceptions ClassSBOCOMException.class is an exception class. All exceptions in the wrappers are encapsulated in this exception class and then sent to the external code calling the wrappers. You then receive and handle this exception in addition to the other normal Java exceptions.

Function Module Framework InterfacesThe function module framework interfaces are under com.sap.smb.sbo.module. Two interfaces exist: DataModelInterface.class FunctionModuleInterface.class

A general exception class for function modules also exists: FunctionModuleException.class

DataModelInterface.class DataModelInterface.class must be implemented by all data model classes used in the public method of the function modules. It ensures that the data model classes can be serialized. It also requires each data model class to provide a public method to show its version information. FunctionModuleInterface.class FunctionModuleInterface.class must be implemented by all function module classes. It requires each function module class to provide a public method to show its version information. FunctionModuleException.class We recommend that all exceptions in the function modules be encapsulated in this exception class or its subclass.

16

May 2003


Utility ClassesThere are several general utility classes in the package com.sap.smb.sbo.util. ConvertUtil.class ConvertUtil.class provides several data type and data format converting methods. For example, the date get from the wrapper is in IEEE64 double type. Using ConvertUtil. public final static Date Double2Date(double ieee64Date), you can convert it to the familiar java util.Date type. For the complete list of useful methods, see the Java document on ConvertUtil.class. UtilException.class UtilException.class is an exception class. All the exceptions in the ConvertUtil.class are encapsulated in this exception class and thrown out to the external code calling the utility class. When using the ConvertUtil.class, you should therefore catch and handle this exception in addition to other normal Java exceptions. NestingException.class NestingException.class is the super class of all other exception classes in the development kit (that is, SBOCOMException.class, FunctionModuleException, and UtilException.class). It provides a recursive way to find the root cause of the exception. Normally, you do not need to use this class directly.

May 2003

17


D: Five Steps for Creating Function ModulesYou can find all source code under $sdk_root$\src.

Describing the ScenarioYou must first clearly describe the scenario because it explains the detailed requirements of the function module. For consistent material code management, ABC Corporation decides to define all its trading material items information (code, name, sales VAT) at its headquarters. The material master data is distributed to all subsidiaries. Subsidiaries are then able to conduct business using this information.

Designing the Data Model and Business LogicUsing the above scenario, we can design the data model to contain the data: Data Model MaterialMasterModel Property itemCode itemName foreignName salesVATGroup The business logic is as follows: Replicate the material master from headquarters. If the material with the same code already exists, update the information. Otherwise, create a new material entry with this information Type String String String String Description Material code Material name Material foreign name Material sales VAT group code

Identifying Data Objects in DI-APIAccording to the scenario and our design, proper COM objects in the DI-API should be identified to implement the function module. By searching the DI-API Help, the Items data object in SAP Business One was found to be related to the material master. Properties in our data model were mapped to properties in DI-API data object. Property itemCode itemName foreignName salesVATGroup Type String String String String SAP Business One Property ItemCode ItemName ForeigName SalesVATGroup Type String String String String

18

May 2003

Function Module Development Guide: SAP Business One Integration Toolkit for mySAP Business Suite - 1.5 The proper methods in the DI-API data object for creating and updating operations were determined. The methods are: Add Update

Implementing Function ModulesThe design is implemented here by providing code for the data model. This code sample is essentially a standard Java bean with several get/set methods as its properties (for example, the itemCode property).

/** * property itemCode as String */ private String itemCode;

/** * get property itemCode * @return */ public String getItemCode() { return itemCode; } String

/** * set property itemCode * @param */ public void setItemCode(String aItemCode) { itemCode = aItemCode; } aItemCode, String

May 2003

19

Function Module Development Guide: SAP Business One Integration Toolkit for mySAP Business Suite - 1.5 In addition to the get/set for properties, the data model class should implement DataModelInterface and have a method to report its version as follows:

public class MaterialMasterModel implements DataModelInterface {

/**@todo please change the version when change the number or name of the properties */ private final static String DATA_MODEL_VERSION = "20020831";

/** * retrieve version of the MaterialMasterModel class */ public String retrieveDataModelVersion() { return DATA_MODEL_VERSION; }

Most importantly, the data model must have a method to pass its properties to Java wrappers of the DI-API data object. Method saveToWrapper is introduced below.

/** * save properties to * @param */ public void saveToWrapper(IItems itemsWrapper) throws FunctionModuleException { SAP Business One-COM Object Items

itemsWrapper, IItems

/* save property itemCode */ if (itemCode != null) { itemsWrapper.setItemCode(itemCode); }

/* save property itemName */ if (itemName != null) { itemsWrapper.setItemName(itemName); }

/* save property foreignName */ if (foreignName != null) { itemsWrapper.setForeignName(foreignName); }

/* save property salesVATGroup */

20

May 2003

Function Module Development Guide: SAP Business One Integration Toolkit for mySAP Business Suite - 1.5if (salesVATGroup != null) { itemsWrapper.setSalesVATGroup(salesVATGroup); }

}

}

The complete code of MaterialMasterModel is as follows:package sample.model;

import java.util.*; import java.text.*;

import com.sap.smb.sbo.api.*; import com.sap.smb.sbo.module.*; import com.sap.smb.sbo.util.*;

/** * Title: * Description: * * Copyright: * Company: * @author * @version */ Data Model Class MaterialMasterModel Data model of MaterialMasterModel mapping the properties of IItems in SAP Business One-COM API Copyright (c) 2002 SAP Development Center, China Yong Li 1.0

public class MaterialMasterModel implements DataModelInterface {

/**@todo please change the version when change the number or name of the properties */ private final static String DATA_MODEL_VERSION = "20020831";

/** * property itemCode as String */ private String itemCode;

/** * property itemName as String */ private String itemName;

May 2003

21

Function Module Development Guide: SAP Business One Integration Toolkit for mySAP Business Suite - 1.5/** * property foreignName as String */ private String foreignName;

/** * property salesVATGroup as String */ private String salesVATGroup;

/** * constructor of MaterialMasterModel */ public MaterialMasterModel() { }

/** * retrieve version of the MaterialMasterModel class */ public String retrieveDataModelVersion() { return DATA_MODEL_VERSION; }

/** * get property itemCode * @return */ public String getItemCode() { return itemCode; } String

/** * set property itemCode * @param */ public void setItemCode(String aItemCode) { itemCode = aItemCode; } aItemCode, String

/** * get property itemName * @return */ public String getItemName() { return itemName; String

22

May 2003

Function Module Development Guide: SAP Business One Integration Toolkit for mySAP Business Suite - 1.5}

/** * set property itemName * @param */ public void setItemName(String aItemName) { itemName = aItemName; } aItemName, String

/** * get property foreignName * @return */ public String getForeignName() { return foreignName; } String

/** * set property foreignName * @param */ public void setForeignName(String aForeignName) { foreignName = aForeignName; } aForeignName, String

/** * get property salesVATGroup * @return */ public String getSalesVATGroup() { return salesVATGroup; } String

/** * set property salesVATGroup * @param */ public void setSalesVATGroup(String aSalesVATGroup) { salesVATGroup = aSalesVATGroup; } aSalesVATGroup, String

/** * save properties to * @param SAP Business One-COM Object Items

itemsWrapper, IItems

May 2003

23

Function Module Development Guide: SAP Business One Integration Toolkit for mySAP Business Suite - 1.5*/ public void saveToWrapper(IItems itemsWrapper) throws FunctionModuleException {

/* save property itemCode */ if (itemCode != null) { itemsWrapper.setItemCode(itemCode); }

/* save property itemName */ if (itemName != null) { itemsWrapper.setItemName(itemName); }

/* save property foreignName */ if (foreignName != null) { itemsWrapper.setForeignName(foreignName); }

/* save property salesVATGroup */ if (salesVATGroup != null) { itemsWrapper.setSalesVATGroup(salesVATGroup); }

} }

The function module class must be implemented at this point. The main part of it is the public method materialMasterUpdate, which carries out the business logic. It also should implement FunctionModuleInterface and has a method to report its version. The complete code is as follows:package sample;

import com.sap.smb.sbo.module.*; import com.sap.smb.sbo.api.*; import com.sap.smb.sbo.util.*;

import sample.model.*;

public class MaterialFunctionModule implements FunctionModuleInterface { private final static String FUNCTION_MODULE_VERSION = "20020831";

public String retrieveFunctionModuleVersion() { return FUNCTION_MODULE_VERSION; }

24

May 2003

Function Module Development Guide: SAP Business One Integration Toolkit for mySAP Business Suite - 1.5public MaterialFunctionModule() { }

/** * Create or update material master in SAP Business One * @param model, material master data model * @throws FunctionModuleException */ public void materialMasterUpdate(MaterialMasterModel model) throws FunctionModuleException { ICompany company = null;


IItems wrapper = SBOCOMUtil.getItems(company, model.getItemCode()); boolean isCreate = false;

/* no exist material master found, create new one */ if (wrapper == null) { isCreate = true; wrapper = SBOCOMUtil.newItems(company); }

int result; /* copy model properties to wrapper */ model.saveToWrapper(wrapper);

if (isCreate) { result = wrapper.add(); } else { result = wrapper.update(); }

/* check errors */ if (result != 0) { SBOErrorMessage sboError = company.getLastError(); if (sboError.getErrorCode() != SBOCOMProxy.ERROR_CODE_OK) { throw new FunctionModuleException("FinanceFunctionModule.materialMasterUpdate Exception: error code (" + sboError.getErrorCode() + ")\n" + "error message :" + sboError.getErrorMessage()); } } } catch (SBOCOMException sce) { throw new

May 2003

25

Function Module Development Guide: SAP Business One Integration Toolkit for mySAP Business Suite - 1.5FunctionModuleException("FinanceFunctionModule.materialMasterUpdate Exception: sbo com exception", sce); } finally { try { SBOCOMProxy.releaseCompany(company); } catch (SBOCOMException sce) { throw new FunctionModuleException("FinanceFunctionModule.materialMasterUpdate Exception: can't release company", sce); } } } }

In the above code, the function module handles the exception. It encapsulates all detected exceptions into FunctionModuleException and sends it.

Local Test, Deployment, Remote TestLocal TestAfter implementing the function module, you can write a local test stub to debug the function module locally before deploying it to the Web service framework of the SAP Business One Integration Toolkit. The following is an example test stub.package test;

import com.sap.smb.sbo.module.*; import com.sap.smb.sbo.api.*; import com.sap.smb.sbo.util.*;

import sample.*; import sample.model.*;

public class FunctionModuleTester {

public FunctionModuleTester() { }

public void testMaterialMasterUpdate() throws FunctionModuleException { MaterialFunctionModule mfm = new MaterialFunctionModule(); MaterialMasterModel mmm = new MaterialMasterModel(); mmm.setItemCode("A99999"); mmm.setItemName("Test Item Name"); mmm.setForeignName("Test Item Foreign Name"); mmm.setSalesVATGroup("A0");

26

May 2003

Function Module Development Guide: SAP Business One Integration Toolkit for mySAP Business Suite - 1.5mfm.materialMasterUpdate(mmm); }

public static void main(String[] args) { FunctionModuleTester tester = new FunctionModuleTester();

try { SBOCOMProxy.initialize(1, 2, "(local)", "SAP Business OneDemo_US", "manager", "manager", 3, true);

tester.testMaterialMasterUpdate();

} catch (Exception e) { e.printStackTrace(); }

} }

A local test stub initializes a company connection pool and uses it to carry out the test. A local test can focus on the data model and business logic without worrying about network problems.

DeploymentAfter successfully conducting the local test, the function module is ready to be deployed. Deployment of the function module is described below: Pack the compiled result into a standard JAR file. In our example, the JAR file should include sample.model, MaterialMasterModel and sample.MaterialFunctionModule. The SDK libraries do not need to be included because they are already in the Web service framework of the SAP Business One Integration Toolkit. Use the Web workbench of the SAP Business One Integration Toolkit to upload the JAR file. A logical name, the full class name of the entry class, and the path of the JAR file should be entered. In this example, you could use following information: Function Module Name: MaterialFunctionModule Function Module Class: sample.MaterialFunctionModule Function Module Package: C:\temp\materialfunctionmodule.jar

May 2003

27

Function Module Development Guide: SAP Business One Integration Toolkit for mySAP Business Suite - 1.5 After successfully uploading the JAR file, you can see the WSDL of your function module. See the example below.

28

May 2003


Remote TestYou can test the function module with HTTP/SOAP using one of a few methods. For example, you can use a tool to generate the Java client stub according to the WSDL and to run the Java client stub. You can also use a direct method, sending SOAP request XML data and then receiving the response. A remote test validates the function module after it has been exposed as a Web service. The WSDL shows the entry point of the Web service HTTP/SOAP request as http://localhost/SBOWebService/dispatcher. For the above sample function module, the SOAP request XML may appear as follows: A99999 item name foreign name A2

May 2003

29


According to the definition of SOAP 1.1, the HTTP containing a SOAP request should have a head element to indicate the SOAP action. The HTTP request content must be declared as an XML date with Contenttype head element and given the exact size of the XML content. In the example, the HTTP request should have at least three head elements:SOAPAction: "http://sap.com/SBOWebService/MaterialFunctionModule" Content-type: text/xml Content-Length: 859

The Web workbench of the SAP Business One Integration Toolkit provides a GUI to monitor the request and response SOAP XML along with the server logs to support debugging. For more information, see the Administration Guide.

Continuous ImprovementThe function module is continuously improved to meet new requirements. However, the same steps as described above should always be followed: Describe the Scenario Design the Data Model and Business Logic Identify the Data Objects in the DI-API Implement the Function Module Local Test, Deployment, Remote Test

In the above example, if there was a requirement to add a get material information feature, all five steps would have to be taken. Describe the Scenario Headquarters wants to check specific material information by retrieving the data from its subsidiaries with a material ID. All previous replication information should be returned if the ID is valid. Otherwise, return a nil. Design the Data Model and Business Logic Because a new property is not required, the old data model can be reused. The business logical is get the material by ID and return. Identify the Data Objects in the DI-API No new data object is required.

30

May 2003

Function Module Development Guide: SAP Business One Integration Toolkit for mySAP Business Suite - 1.5 Implement the Function Module Add the following code in the sample.MaterialFunctionModel.java: /** * Get material master in SAP Business One * @param key, material master ID * @return MaterialMasterModel, material master data model * @throws FunctionModuleException */ public MaterialMasterModel materialMasterGet(String key) throws FunctionModuleException { MaterialMasterModel model = null; ICompany company = null;


IItems wrapper = SBOCOMUtil.getItems(company, key);

/* material master found, prepare the date to return */ if (wrapper != null) { model = new MaterialMasterModel(); model.loadFromWrapper(wrapper); }

} catch (SBOCOMException sce) { throw new FunctionModuleException("FinanceFunctionModule.materialMasterGet Exception: sbo com exception", sce); } finally { try { SBOCOMProxy.releaseCompany(company); } catch (SBOCOMException sce) { throw new FunctionModuleException("FinanceFunctionModule.materialMasterGet Exception: can't release company", sce); } }

return model; }

May 2003

31

Function Module Development Guide: SAP Business One Integration Toolkit for mySAP Business Suite - 1.5 Local Test, Deployment, Remote Test Add the following code in the previous test stub to carry out the local test: public void testMaterialMasterGet() throws FunctionModuleException { String key = "A99999"; MaterialFunctionModule mfm = new MaterialFunctionModule(); MaterialMasterModel mmm = mfm.materialMasterGet(key); if (mmm != null) { System.out.println("Material Code System.out.println("Material Name : " + mmm.getItemCode()); : " + mmm.getItemName());

System.out.println("Material Foreign Name : " + mmm.getForeignName()); System.out.println("Material Sales VAT Group : " + mmm.getSalesVATGroup()); } else { System.out.println("No material found with ID : " + key); }

}

You then repack the JAR file and deploy it. As a final task, carry out the remote test for the new version of the function module. For the new method, the SOAP request XML may appear as follows: A99999

Similarly, the HTTP request should have at least three head elements:SOAPAction: "http://sap.com/SBOWebService/MaterialFunctionModule" Content-type: text/xml Content-Length: 439

32

May 2003


E: AppendixAppendix A SOAP Head ElementsThe standard Web service supported by the SAP Business One Integration Toolkit accepts headless SOAP messages. The SAP Business One Integration Toolkit uses SOAP head elements as extensions when it communicates with a specific system. The elements in the SOAP head hold the information outside of the business logic (for example, the application name, the function module name, the business sender logical name, and so on). All of the elements are enclosed in: Here is a sample piece of the SOAP head: MaterialFunctionModule 20020831 0123456789 1

This table provides a list of all elements that may appear in the SOAP head: Element Usage Only valid in a SOAP response message. The setting shows the application name. Currently, it is always SBOWebService In a SOAP request, the setting determines which function modules are used. SOAPAction in the HTTP header overrides this setting. In a SOAP response, the setting shows the function module actually used. Only valid in a SOAP response message. The setting shows which operation method of the function module is actually used. Possible value SBOWebService Default value SBOWebServi ce

Any valid function module name

Any valid operation method name in the specified function module

May 2003

33

Function Module Development Guide: SAP Business One Integration Toolkit for mySAP Business Suite - 1.5 In a SOAP request, the setting passes the external number to the Web service. In a SOAP response, the setting sends back the external number of the external system to match the request with the response. Only valid in a SOAP response message. The setting gives an internal number to the external system. The external system uses this number to confirm that the response was received correctly. Only valid in a SOAP response message in asynchronous communication mode. The setting gives an expiration date of the asynchronous response. After the date, the unsent asynchronous response is not sent. Only valid in a SOAP response message. The setting indicates the processing result of the SOAP request. Only valid in a SOAP response message. The setting shows the text of the processing result. In a SOAP request or response, the setting shows the communication mode. In a SOAP request or response of asynchronous communication, the setting shows how to send back the multiple responses. Determined by external system, unique external ID

Max. 20 characters unique id.

In long format, the date complies with Java

Never expired

S = successful E = error occurred

0 = synchronous communication 1 = asynchronous communication 0 = random (that is, there is no order requirement of the responses in the same batch) 1 = in order (that is, there is an order requirement of the responses in the same batch)

0

0

34

May 2003

Function Module Development Guide: SAP Business One Integration Toolkit for mySAP Business Suite - 1.5 Only valid in the response message. The element has two sub elements and . Only valid in the response message. The setting shows the logical name of the SAP Business One Integration Toolkit instance for SAP XI. Only valid in the response message. The setting shows the interface name and interface namespace of the SAP Business One Integration Toolkit instance for SAP XI. Determined by the configuration value

Determined by the configuration value

Determined by the configuration value

Appendix B SAP Exchange Infrastructure IntegrationSOAP head elements are used for the integration between the SAP Business One Integration Toolkit and the SAP Exchange Infrastructure (SAP XI). SAP XI submits SOAP request messages with SOAP head elements and receives SOAP response messages with SOAP head elements. Other than the standard Web service, the entry point to execute the function module with the SAP Exchange Infrastructure using HTTP is http://localhost/SBOWebService/xi. In the SAP Exchange Infrastructure case, the SOAP request XML (for the function module above) may appear as follows: MaterialFunctionModule 20020831 0123456789 1 A99999

May 2003

35

Function Module Development Guide: SAP Business One Integration Toolkit for mySAP Business Suite - 1.5 Because the SOAP head is used to pass on the function module name, it is not necessary to have an HTTP head element to indicate the SOAP action. If one exists, the setting of the SOAP action overrides the setting in the SOAP head. Also, the SAP XI integration only use asynchronous communication mode. Therefore, the setting 1 must always exist. In the SAP Exchange Infrastructure case, the asynchronous SOAP response XML for the function module mentioned above may appear as follows: SBOWebService MaterialFunctionModule materialMasterGet 1 0123456789 0a21b10275fc094c97b3 S Remote procedure call successfully subsidiary1 MaterialFunctionModule__materialMasterGetResponse A2 foreign name item name A99999

In the response, you may notice the element in the SOAP head. It has two sub-elements. The element identifies the SAP Business One Integration Toolkit instance with a logical name for the SAP XI. The element shows the interface namespace and name. You can set the namespace in the SAP XI configure GUI of the SAP Business One Integration Toolkit. The interface name is automatically generated according to the following rule: __Response For example, MaterialFunctionModule__materialMasterDataGetResponse refers to the materialMasterDataGet operation of the MaterialFunctionModule.

36

May 2003