B1 I FW02 Scen Dev

Integration framework for SAP Business One 02 Scenario Development
Integration framework
for SAP Business One
Guide 02
Scenarios Development
Author: Heinz Pauly Version: 1.0 Date: June 21, 2010
-1-
Content
1. Concepts of the Scenario Development.......................................................3 2. Create a Scenario Package .........................................................................5 2.1 Variables ................................................................................................6 2.2 Properties (not yet supported) ................................................................8 3. Develop a Scenario Step .............................................................................9 3.1 Scenario Step Inbound......................................................................11 3.1.1 Scenario Step Inbound Channel ..............................................12 3.1.2 Scenario Step Inbound Retrieval .............................................17 3.1.3 Scenario Step Inbound Formatting ..........................................21 3.2 Scenario Step Outbound ...................................................................22 3.3 Scenario Step Processing .................................................................29 3.3.1 The Processing Flow .....................................................................29 3.3.2 The B1i Message Format...............................................................29 3.3.3 The Bizflow Language (Design).....................................................30 3.3.3.1 Start/End .................................................................................31 3.3.3.2 Conditional Processing............................................................31 3.3.3.3 For Each Processing ...............................................................33 3.3.3.4 Transformation (xform and final) .............................................35 3.3.3.5 Call SQL..................................................................................39 3.3.3.6 Call B1 Object .........................................................................42 3.3.3.7 Call B1 Service........................................................................46 3.3.3.8 Call RFC..................................................................................46 3.3.3.9 Call SQL..................................................................................46 3.3.3.10 Call any Java Class...............................................................46 3.3.3.11 Conversion XML to JSON .....................................................46 3.3.3.12 Conversion Binary to XML.....................................................46 3.3.3.13 Generate Crystal Report .......................................................46 3.3.3.14 Retrieve File from Filesystem................................................46 3.3.3.15 Persist Douments/Groups .....................................................47 3.3.3.16 Put Message to Queue..........................................................47 3.3.4 XSL Development..........................................................................47 3.3.4.1 Some very basics about XSL ..................................................47 3.3.4.2 The B1i XSL Library ................................................................49 3.3.5 Test Environment and Debug Mode ..............................................52 4. Develop a user defined Authentication ......................................................52 Appendix A. Table of Inbound Channels........................................................53 Appendix B. Table of Outbound Channels.....................................................55 Appendix C. Table of Process Steps .............................................................56 Copyrights, Trademarks, and Disclaimers .....................................................59
-2-
1. Concepts of the Scenario Development

The SAP B1i Framework is an Integration Server, which allows to process integration scenarios. These integration scenarios are delivered by SAP, by SAP partners and can be developed by the customer based on the individual requirements for a concrete project. Integration scenarios in the B1i Framework are called Scenario Package. Short form inside the B1i Framework is vPac. Each Scenario Package is owned by a particular vendor (SAP or SAP partner) or by the customer himself. The Scenario Package Identifier is built following the rule <ns>.<id> and the maximum length of the total identifier is 20 characters. <ns> stands for the vendor namespace abbreviation (e.g. sap for SAP) <id> is the name of the Scenario Package
A Scenario Package covers one or multiple Scenario Steps. A Scenario Step is covering a concrete integration flow. This integration flow can be an asynchronous flow between a sender and a receiver system type or a synchronous flow, triggered by a particular caller. Short form for a Scenario Step inside the B1i Framework is vBIU where BIU stands for Business Integration Unit. Examples for a Scenario Step Sending a sales order from SAP Business 8.8, triggered by an event to the file system in a particular DSV format. A Web Service which is responding a requested list of Business Partner from an ERP 6.0 system. A timer triggered process, which picks up data in a particular database, calling a web service for calculation and handing over the data to an FTP server. One Scenario Package can cover all kind of different Scenario Steps. A Scenario Step belongs uniquely to one Scenario Package.
-3-
A Scenario Package can have three different states design setup active Design Status In the design status, you can fully develop and modify (based on your authorization rights) all documents, related to the Scenario Package and all included Scenario Steps. The Scenario Steps are not active and even if the appropriate events are triggered, nothing will happen. New created and imported Scenario Packages are in design mode by default. Setup Status Typically you are using the administration console of the B1i Framework (Scenarios Scenario Package Setup) to setup a Scenario Package. There is also an option for predefined automatic setup during the import of a Scenario Package. During the setup you select the involved Scenario Steps, you assign the involved systems from the SLD (System Landscape Directory, please refer to B1i Framework reference 03 - Operations), you specify publishing and subscriber filter and if required scheduler settings. After setup, modification is no longer allowed. The selected Scenario Steps are still not active. This gives you an easy way to switch on/off the processes. Active Status Typically you are using the administration console of the B1i Framework (Scenarios Scenario Package Setup) to activate a Scenario Package. There is also an option for predefined automatic activation during the import of a Scenario Package. Prerequisite for activation is that the Scenario Package is in status setup. After activation, modification is no longer allowed. The selected Scenario Steps are active and will run based on the related trigger.
-4-
2. Create a Scenario Package

Please use the administration console of the B1i Framework to create a Scenario Package.
Scenarios Scenario Package Design
Scenario Package Identifier Here you specify the identifier for the Scenario Package. If you are using this screen to modify a Scenario Package, please select it from the list via the button. In case you create a new Scenario Package, just type in the identifier. Automatically, the namespace abbreviation is added. The abbreviation depends on the settings of the development environment (please refer to B1i Framework reference 01 Development Environment). Maximum length of the identifier is 20 characters. Allowed are all letters, numbers, point and hyphen. Authentication In case a Scenario Package has at least one Scenario Step which is triggered by an HTTP or Service call, you have to specify the authentication method. Here you can choose No Authentication, Basic Authentication, Basic -5-
Secure Authentication (enforce HTTPS) and optional a special user defined authentication. With the button, you will get a list of all available authentication methods. In case you selected a special authentication, please refer to chapter 4. Status This field is read-only. It displays the current status of the Scenario Package. Vendor Here you specify the vendor information for the Scenario Package. This information depends on the settings of the development environment (please refer to B1i Framework reference 01 Development Environment) and is automatically inserted and you can overwrite it. Version Here you specify the version number of your Scenario Package. In case you create new Scenario Package, the version 1.0.0 is automatically set. Timestamp This field is read-only. It displays the timestamp of the last modification in the Scenario Package. Modifications I n related Scenario Steps are not covered. Description Here you can describe your Scenario Package in a nutshell. Scenario Steps This field is read-only. It displays the Scenario Steps, linked to this Scenario Package. Please notify that not the Scenario Package is defining its steps, but the Scenario Steps are linked to a particular Scenario Package. This avoids, that Scenario Steps can be linked at the same time to different Scenario Packages. [Save] Click this button to save the configuration.
2.1 Variables
There are two types of variables available in the B1i Framework: Global Variables Local Variables
Whereas the global variables can be shared by all Scenario Steps, independent on the Scenario Package, the scope of local variables is the Scenario Package. All Scenario Steps, linked to this package can use the defined local variables.
-6-
Variables are used in the design and the setup phase of Scenario Steps to specify variable values, depending on the concrete inbound message. Examples: In a Scenario Step processing, you specify data retrieval by a sql statement and in the where-clause you need to specify the value of the primary key for which entry you want to retrieve the data and the data is on a particular place in the inbound message. During the setup, you want to specify filter criteria for the receiver system based on a concrete value of the incoming message. You use the variables inside xpath statements or other processing instructions, like sql statements with a leading $, similar to the usage of variables in xslt. The following global variables are available $msg the inbound payload, sent by the sender system/call $userid identifier of the user (in case of an HTTP based call) $username name of the user (in case of a n SAP B1 user) $b1task task (insert/update/delete) od the incoming transaction $today date of today $now current timestamp $sender identifier of the sender system You can add, modify or delete your local variables by clicking the [Variables] button in the Scenario Package Design, but also context related during the design of the processing flow for a particular Scenario Step.
The value of a variable is always defined by an xpath statement. Here you can use also existing global and local variables to define new variables. In this case please make sure that the new variable (in our example TotalS) is in alphabetical order behind the variable, which are used (Total1 and Total2). -7-
2.2 Properties (not yet supported)

The scope of properties is the Scenario Package. All Scenario Steps, linked to this package can use the defined properties. Properties are used in the design inside the processing flows for specifications, similar to the variables, but also inside the XSLT transformations whenever the design is depending on a particular setting not known at the design time. Examples: In a Scenario Step processing, you specify data retrieval by a sql statement and in the where-clause you specify the access based on a customer setting. In an XSLT transformation you want to implement conditional logic, depended on a value, specified by the customer. Properties are defined during design time where you also specify the default values. During the setup, the customer can use the defaults or overwrite the values based on his requirements.
You can add, modify or delete your properties by clicking the [Properties] button in the Scenario Package Design.
-8-
3. Develop a Scenario Step

Please use the administration console of the B1i Framework to create a Scenario Step.
Scenarios Scenario Step Design
Scenario Step Identifier Here you specify the identifier for the Scenario Step. In case you want to create a new Scenario Step, please enter the name of your choice. When you leave the field, automatically the namespace prefix is added. The prefix is dependent on your settings (Maintenance Config Dev Environment). In case you want to modify an existing Scenario Package, please click the corresponding button to open a drop-down list with all available Scenario Steps and select it from the list. In case you want to create a new Scenario Package, just type in the identifier. Automatically, the namespace abbreviation is added. The abbreviation depends on the settings of the development environment (please refer to B1i Framework reference 01 Development Environment). Maximum length of the identifier is 20 characters. Allowed are all letters, numbers, point and hyphen.
-9-
Scenario Package Identifier Each Scenario Step belongs to exactly one Scenario Package. Please click the corresponding button to open a drop-down list with all available Scenario Packages and select the package you want. The leading flags in brackets are indicating the current mode of the Scenario Package. You can associate your step to the package only if the package is currently in design mode (D). Its also possible to change the assignment from one package to another one. In this case automatically, the no more valid assignment will be removed and the new assignment will be set up. Inbound, Processing, Outbound These fields are read-only and display basic information of the inbound, processing and outbound definition. To define these processing instructions, please use the appropriate buttons and refer to the following chapters. Inbound, Processing and Outbound are the main processing phases, which are running in both supported integration pattern, synchronous requestresponse and asynchronous, sender-receiver message processing.
[Save] Please click the [Save] button to save the settings you made. [Info] Please click the [Info] button to open an overview window, displaying all settings of the Scenario Step. [Delete] Please click the [Delete] button to remove the Scenario Step. The step will be completely removed including the association the Scenario Package. - 10 -
3.1 Scenario Step Inbound

When you click the [Inbound] button from the Scenario Step Definition screen, the Inbound definition screen will open in a new window.
The inbound processing is covering the following aspects of the Scenario Step: Definition of the inbound channel Definition of data retrieval Definition of formatting Inbound Channel (IPO) This field is read-only and displays the selected inbound channel. The channel is covering the initiator system type, the trigger, the processing type and the identification method. The identifier of the inbound channel is compiled automatically based on definitions. Data Retrieval This field is read-only and displays the way how the inbound data is reaching the Scenario Step. It depends on the inbound channel if the data retrieval is required. No data retrieval is needed for all incoming calls, which are handing over data, whereas you have to specify particular data retrieval in case the incoming trigger (e.g. an SAP Business One event) does not handover the relevant business data. Formatting This field is read-only and is typically set to dynamic. In case you have to process a special formatting, based on external instructions during the inbound phase, you can use this option to specify the formatting control document. An example is an incoming text file, where you want to control the conversion to XML by offset definitions or regular expressions. - 11 -
3.1.1 Scenario Step Inbound Channel

When you click the [Channel] button from the Scenario Step Inbound Definition screen, a new window will open. Here you specify the aspects of your inbound processing and the Integration framework for SAP Business One will automatically generate the relevant Channel.
The Integration framework for SAP Business One is supporting the different types of business processes by so called Channels. It structures the various aspects in the following categories: Initiator System Type Processing Mode Trigger Identification
- 12 -
All relevant combinations of these four aspects are covered by one particular channel. The name of the channel contains abbreviations of the aspect values, e.g. the channel INB_HT_CALL_SYNC_XPT indicates an inbound channel for HTTP (HT), where the call is triggering the process (CALL), the processing will be handled synchronously (SYNC) and the identification of the call will be detected by an xpath statement (XPT). All supported channels are listed in the appendix A (Table of Inbound Channels). In general, you can choose all values which are not set in brackets as brackets are indicating not yet supported values. These values will come with one of the next patches.
Inbound Type The inbound type specifies the initiator system or system type. Please click the corresponding button to open a drop-down list with all available inbound types. The following inbound types are available: SAP Business One Web Service Call HTTP Call Flat File Predecessor (result process of another Scenario Step) Internal Queue (internal explicit triggering by another Scenario Step) Database Email (POP3) Email (IMAP) FTP Call SAP ERP (RFC passive)
Process Mode The process mode specifies how the processing will happen inside the Integration framework. The supported mode depend on the selected Inbound Type. Please click the corresponding button to open a drop-down list with all relevant values. The mode can be Synchronous or Asynchronous. Please choose Synchronous in case you are calling in, waiting for response. Asynchronous mode is used for message based integration where a message is sent from one system to other systems. Process Trigger The process trigger specifies how the processing is triggered. The supported trigger depend on the selected Inbound Type and the selected Process Mode. Please click the corresponding button to open a drop-down list with all relevant values. In general the following trigger are supported: Call (incoming calls) B1Event (event from SAP Business One) Timer (scheduler based) File Exist (existence of a file) - 13 -
Queue (message in an internal queue) IDOC (incoming IDOC from SAP ALE)
Identification Method The Integration framework for SAP Business One is supporting the inbound channels in a generic way. Different to other state-of-the-art integration solutions, the huge benefit is that there is no need to setup inbound processes per business object or method by extensive proxy generating. The Integration framework for SAP Business One can support e.g. all incoming Web Service calls or all incoming events from a particular SAP Business One with one generic channel. Therefore you have to identify the Business Object or the required method based on the inbound data. E.g. the Scenario Step which you are designing is interested in all Business Partner from SAP Business One. In this case the Identification Method is B1Event. Another example is an incoming http call where your Scenario Step is interested in all calls, which are handing over an xml message with a particular name of the root-tag. In the case the Identification Method is Root Tag. The supported methods depend on the selected Inbound Type, the selected Process Mode and the selected Process Trigger. Please click the corresponding button to open a drop-down list with all relevant values. In general the following Identification Methods are supported: B1 Logic (incoming xml file, following the syntax of SAP B1 XML) B1 HTTP (special format for an incoming HTTP call from SAP B1) B1Event (incoming event from SAP Business One) File Name (name of an incoming flat file) First Line (first line of an incoming text file) Fix Value (always a fix value) Queue/Stream (name of internal queue and stream) Root Tag (name of the root tag of the inbound message) vBIU Name (name of the predecessor Scenario Step) xPath (any xpath statement to be processed on the inbound message) Identification Parameter This is an optional parameter, depending on the selected Identification Method. If you selected File Name as the Identification Method, you can optionally specify the start position and the length of the file name which is relevant for identification. The format is x,y which is calculated as substring(filename,x,y). E.g. if your incoming file name is always different because the timestamp is added to the file name, you can use the feature to do the identification only by comparing the fix parts of the file name. If you selected xPath as the Identification Method, you have to specify the xpath expression here. Please use the variable $msg for the incoming message. Identifier This is the concrete identifier of the incoming Business Object or called method where the Scenario Step is subscribed to. The inserted string will be compared via the selected Identification Method against the value based on the incoming message.
- 14 -
Identification Namespace This is an optional parameter. If the processing of the incoming message requires the declaration of xml namespaces, you can specify the xml namespaces here. The xml namespaces will be generated automatically into all documents, relevant for the processing. Please follow the syntax xmlns:ns=nsdef xmlns:ns=nsdef [Save] Please click the [Save] button to save the settings you made.
[Timer] This button is relevant only if the Process Trigger is Timer. Here you specify the default scheduler settings for the Scenario Step. During setup of the Scenario Package, the customer can overwrite these settings. By clicking the button, a new window opens to specify the timer settings.
The scheduler definition is following the CRON syntax, typically known from job scheduler in unix-like computer operating systems. A CRON entry has six fields for specifying day, date and time. The Scenario Step will be triggered always when all entries are true. The entries are interpreted in the system time zone setting under which the Integration framework itself is running.
- 15 -
Scheduler (minute) Here you specify the value for the minute part of the time. The value can have a * or a list of elements separated by commas. An element is either a number in the range 0 to 59 or two numbers in the range separated by a hyphen (meaning an inclusive range). Scheduler (hour) Here you specify the value for the hour part of the time. The value can have a * or a list of elements separated by commas. An element is either a number in the range 0 to 23 or two numbers in the range separated by a hyphen (meaning an inclusive range). Scheduler (day) Here you specify the value for the day part of the date. The value can have a * or a list of elements separated by commas. An element is either a number in the range 1 to 31 or two numbers in the range separated by a hyphen (meaning an inclusive range). Scheduler (month) Here you specify the value for the month part of the date. The value can have a * or a list of elements separated by commas. An element is either a number in the range 1 to 12 or two numbers in the range separated by a hyphen (meaning an inclusive range). Scheduler (day of wek) Here you specify the value for the day of the week. The value can have a * or a list of elements separated by commas. An element is either a number in the range 0 to 6 (Sunday = 0) or two numbers in the range separated by a hyphen (meaning an inclusive range). Scheduler (year) Here you specify the value for the year part of the date. The value can have a * or a list of elements separated by commas. An element is either a number, specifying a year (e.g. 2010) or two numbers in the range separated by a hyphen (meaning an inclusive range).
[Save] Please click the [Save] button to save the settings you made.
- 16 -
3.1.2 Scenario Step Inbound Retrieval

When you click the [Retrieval] button from the Scenario Step Inbound Definition screen, a new window will open. Here you specify how the inbound data is sent to the Integration framework. The field Retrieval Method is set automatically when you open the screen and indicates if the retrieval definition is required or not. If the inbound trigger is an incoming call, the retrieval definition is not required and the retrieval method is set to the value Handover, otherwise the value is set to Retrieval.
Retrieval Adapter Here you specify the adapter which is used to retrieve the inbound data. The valid values are depending on the selected Inbound Channel. Please click the corresponding button to open a drop-down list with all relevant values. The following values are supported: DI API (Data interface of SAP Business One) JDBC (Database request) Crystal (Crystal report) Multiple (Multiple calls, defined via a control document) WSAS (Web Services Solicit Response) HTTA (HTTP call) FILI (File inbound) RFCA (Remote Function Call to an SAP R/3 based system) FTPI (FTP inbound) POP3 (incoming email retrieval via POP3 protocol) IMAP (incoming email retrieval via IMAP protocol) - 17 -
Retrieval Type Here you specify the protocol type for the data retrieval. The valid values are depending on the selected Retrieval Adapter. Please click the corresponding button to open a drop-down list with all relevant values. The following values are supported: Object (Object call, Retrieval Adapter = DI API) Service (Service call, Retrieval Adapter = DI API) SQL (SQL statement, Retrieval Adapter= JDBC) Report (report processing, Retrieval Adapter = Crystal) Multiple (multiple calls, Retrieval Adapter = Multiple) BAPI Call (Retrieval Adapter = RFCA) Call (Retrieval Adapter = FILI, FTPI, POP3, IMAP, WSAS, HTTA) Retrieval Control Document This value is relevant only for retrieval Adapter Crystal and Multiple. Here you select the control document which is describing the data retrieval. In case of Crystal, please insert the name of the crystal report, in case of Multiple, please insert the name of the retrieval control document. The document has to be available in the BizStore base directory of the Scenario Step. Please refer to the reference guide 01 how to import the control document into this place. For design of a crystal report, please refer to the crystal designtime documentation. The format for the retrieval control document you can find in the Integration framework guide 05.
[Save] Please save your settings by clicking the [Save] button.
[Details] Depending on the selected Retrieval Adapter and Retrieval Type, some details are required. Please click the [Details] button to define these details. Details are required for the following retrievals: Retrieval Type = Service Retrieval Type = SQL Retrieval Type = BAPI Call These details are required to perform the call to retrieve the inbound data from the sender system. Please notify that there are no details necessary for a DI API object call whereas a DI API service call requires the specification of the service call details. Please notify that the data retrieval here is only the retrieval of then inbound data. In case you have to retrieve additional data or information from the sender system or from other external system, you should do these calls not during the inbound phase, but during the Scenario Step Processing phase (chapter 3.3).
- 18 -
Details for a JDBC call
SQL statement Please define the sql statement to retrieve the data. You can use $key as a variable to be replaced by the Integration framework with the key value, handed over by the B1 event.
Details for a DI API Service call
- 19 -
Service Identifier Please define the service identifier of the SAP Business one service, you want to call. Details youll find in the DI API help. Service Method Type Data retrieval is supported by two main service types, the Get method and the GetList method. Please select the one you require. Request Method Please define the name of the request method. Details youll find in the DI API help. Request Structure Please define the name of the request structure. Details youll find in the DI API help. Request Keys Please define the key names of the request method. As typically the name of the key in the request structure is different to the key name in the event, both values are required. Please define the keys in the format requestkey(eventkey). Details youll find in the DI API help.
Details for an RFC call
BAPI Name Please define the name of your function module in R/3. It can be an own function or a function provided by the R/3 standard. Before you can call the
- 20 -
Function, you need to make sure that it is enabled for remote access. Parameter x Optional here you can specify up to five parameters in the format name = value. can use $key as a variable to be replaced by the Integration framework with the key value.
3.1.3 Scenario Step Inbound Formatting

When you click the [Formatting] button from the Scenario Step Inbound Definition screen, a new window will open. This definition is required only in case the formatting is calculated base on an external control document. It is relevant for incoming flat files which are transformed to xml based on regular expressions or a file with field-offset definitions.
Format Control Document Here you specify the name of the control document. The document has to be available in the BizStore base directory of the Scenario Step. Please refer to the Integration framework reference guide 01 how to import the control document to this place. The format for the control document you can find in the Integration framework reference guide 05. For incoming flat files, please notify that the technical inbound formatting settings (encoding, delimiter, wrapchar and payload type), you have to specify in the System Landscape Directory (SLD) for the concrete system. The information n how to set up a file system, please refer to the Integration framework reference guide 04, chapter 3.3.
- 21 -
3.2 Scenario Step Outbound

When you click the [Outbound] button from the Scenario Step Definition screen, the Outbound definition screen will open in a new window.
Outbound Channel Here you specify the technical adapter to handover the data in the outbound phase. Please click the corresponding button to open a drop-down list with all relevant values. The following values are supported: Database (data handover via sql) Email (data is sent via email SMTP protocol) Flat File (data is stored in a flat file in the file system) FTP (data is stored in a flat file via FTP) HTTP (data is handed over to an HTTP call) SAP Business One (data is inserted via DI API or via sql) SAP ERP (data is handed over via a remote function call) Void (no data handover) Web Service (data is handed over via a web service call) Outbound Format Here you specify the outbound format. The valid values are depending on the selected Outbound Channel. Please click the corresponding button to open a drop-down list with all relevant values. The following values are supported: file (for Outbound Channel Flat File)
- 22 -
jdbc (for Outbound Channel Database) ws (for Outbound Channel Web Service) DI Object, DI Service, SQL, B1i SQL, Multiple (for Outbound Channel SAP Business One)
The format that is selected, is corresponding to the message that is created by the Scenario Step processing. Please refer to the correct outbound schemas, described in the Integration framework reference guide 05. Details This is a read-only field, displaying the detailed settings. The detailed settings, you specify by clicking the [Details] button. Successor The Integration framework allows you, to set up another Scenario Step which is called after finishing of a Scenario Step. This can be used e.g. to send back result information to the sender system. You cannot explicitly write a name of another Scenario Step, but you can select one of the drop-down list. In the list you will see only the Scenario Steps, which are linked to the same Scenario Package and which have the Inbound Type Predecessor. Successor Mode This is relevant only in case you are triggering another Scenario Step when this Scenario Step is finished. Here you define which information you are interested in. You have the following options: status information only status information and Payload status information and complete Message
[Save] Please save your settings by clicking the [Save] button.
[Details] Depending on the selected Outbound Channel and Outbound Format, some details are required. Please click the [Details] button to define these details. Details are required for the following outbounds: Outbound Channel = Flat File Outbound Channel = Web Service Outbound Format = DI Object Outbound Format = DI Service Outbound Format = SQL Outbound Channel = Database
- 23 -
Details for Outbound Channel Flat File
Outbound Format Here you specify the outgoing format of the flat file. Please click the corresponding button to open a drop-down list with all relevant values. The following values are supported: xml (xml representation) dsv (delimiter separated value) txt (offset defined values) Character Encoding Optional character encoding is needed to apply the technical representation of the characters according to the country or system specific needs. The following entries are available: ISO 8859-1, ISO 8859-2, ISO 8859-3, ISO 8859-4, ISO 8859-5, ISO 8859-6, ISO 8859-7, ISO 8859-8, ISO 8859-9, ISO 8859-11, ISO 8859-13, ISO 8859-14, ISO 8859-15, ISO 8859-16, US-ASCII, EBCDIC, Shift-JIS, EUC-JP, ISO-2022, GB2312, EUC-KR, Big5, Unicode UTF-7, Unicode UTF-8, Unicode UTF-16, ISO-10646-UCS2, ISO-10646UCS4. Please choose the required one from the list. ISO-8859-1 is the default. Format Control Document This parameter is relevant only if you selected Outbound Format txt. In this case, you specify here the name of the control document. The document has to be available in the BizStore base directory of the Scenario Step. Please - 24 -
refer to the Integration framework reference guide 01 how to import the control document to this place. The format for the control document you can find in the Integration framework reference guide 05. DSV Field Delimiter This parameter is relevant only if you selected Outbound Format dsv. In this case, you specify here the delimiter character. The default is a comma. DSV Field Wrapper This parameter is relevant only if you selected Outbound Format dsv. In this case, you specify here the wrapper character. The default is a empty. The field wrapper is optional and only used to avoid that a field delimiter character inside a value will be misinterpreted as a field delimiter.
Details for Outbound Format DI Object
Method Here you specify the method to be used for handing over the data to the SAP Business One system. Please click the corresponding button to open a drop-down list with all relevant values. The following values are supported: Synchronous Insert Synchronous Insert with fallback to Update Synchronous Update Synchronous Update with fallback to Insert Synchronous Delete
- 25 -
Object Identifier Here you define the identifier of the SAP Business One object. You can use the corresponding button to open a drop-down list with all available business objects. Please also refer to the SAP Business One DI help. Key Name Here you define the name of the primary key. In case of multiple keys, please list the keys separated by comma. Please also refer to the SAP Business One DI help.
Details for Outbound Format DI Service
Service Identifier Please define the service identifier of the SAP Business One service, you want to call. You can use the corresponding button to open a drop-down list with available service calls. Details youll find in the DI API help. Service Method Type Please select the method you want to call to handover data to SAP Business One. Please click the button to open a drop-down list with supported methods: - 26 -
Add method Update method Remove method
Service Method Identifier Please define the name of the method call. Details youll find in the DI API help. Get Method Identifier Please define the name of the get method call. This is required because each data handover will be performed by a select with a following data merge and storage. Details youll find in the DI API help. Request Structure Please define the name of the request structure. Details youll find in the DI API help. Request Keys Please define the key names of the request method.. Details youll find in the DI API help.
Details for Outbound Channel Web Service
SOAP Action Per default B1i hands over an empty SOAP action. Whereas this serves most of the cases, there are some older web services that need the definition of the called method via the SOAP action. For this purpose you can define the SOAP action in the outbound definition.
- 27 -
Details for Outbound Format SQL or Outbound Channel Database
SQL Processing Mode This setting is relevant for multiple sql calls only. The default setting is multiple. Please click the button to open a drop-down list with the supported processing options: single (concatenates all sql statements with a semicolon to one sql statement. Only one sql statement is handed over to the database system. Some RDBMS, e.g. DB2 are not supporting this feature). multiple (processing of each sql statement one after the other).
- 28 -
3.3 Scenario Step Processing

During the processing phase the Integration framework will transform the sender message to the receiver format by calling the processing flow, defined by the particular Scenario Step.
3.3.1 The Processing Flow

The processing is done via a processing flow. The Integration framework hands over a message to this flow. The incoming message is running through multiple steps and at the end the message is handed over back to the Integration framework for further processing. The complete processing flow is one transaction.
Inside this processing flow the outbound message of a particular step is handed over as the inbound message to the next step. The steps are so called Bizatoms (please refer to chapter 3.3.3). The Bizatoms guarantee that the message format will always endure. When you enter first time the processing screen, the Integration framework will automatically generate a simple flow, consisting out of one final transformation step. Especially for asynchronous interaction between a sender and a receiver system, this is quite often sufficient. In this case the only development step is the adjustment of the generated xsl to your needs. By default the automatically generated xsl will copy the message 1:1.
3.3.2 The B1i Message Format

The xml message is always a well formed B1i message. It consists out of a Header and a Body section. Whereas the Header is covering process control information, the Body is containing the payload. Inside the Body there are different Payload sections. The main Payload sections are the following: Payload/@Role=T Payload/@Role=S Payload/@Role=R containing the trigger information (e.g. the B1 event) section containing the sender message containing the receiver message
- 29 -
The Receiver section is not existent during the processing flow. The result of the processing flow will be written into this section by a special step, called Final Bizatom at the end of the processing flow. The B1i message of the Integration framework is defined in the xml namespace xmlns:vpf="urn:com.sap.b1i.vplatform:entity".
<vpf:Msg MessageId="100518083505971270420A140FBBB876" > <vpf:Header> <vpf:IPO Id="..."/> <vpf:Sender Id="0010000101" ObjId="infile"/> <vpf:Receiver Id="0010000102"/> <vpf:vBIU Id="sap.Tutor-FileToDB" SId="sap.B1iFW-Test" filter=""/> <vpf:Identification Ident="File Name" IdPar=""/> <vpf:nsList/> <vpf:Variables> ... </vpf:Variables> <vpf:VarProperties> ... </vpf:VarProperties> </vpf:Header> <vpf:Body> <vpf:Payload Role="T" Type="xxx"> Trigger Message </vpf:Payload> <vpf:Payload Role="S"> Sender Message </vpf:Payload> <vpf:Payload Role="R"> Receiver Message </vpf:Payload> </vpf:Body> </vpf:Msg>
Each processing step (so called Bizatoms) will add an additional Payload section in the Body, to be identified by the atom id. The access to a concrete Payload section is always with the absolute path and by id. So e.g. /vpf:Msg/vpf:Body/vpf:Payload[./@id=atom1]/ . This allows you to add or remove processing steps without disrupting the existing processing logic.
<vpf:Payload Role="X" Id="atom1"> Result from step with id=atom1 </vpf:Payload>
3.3.3 The Bizflow Language (Design)

The flow definition is done by the graphical SAP flow language called Bizflow, which is especially made for model-driven integration of business applications. Inside the Bizflow you assemble so called Bizatoms to a processing flow. This language and the Bizatoms are covering the typical used integration pattern, needed to do integration of business applications in an easy, declarative way. Bizatoms can be control structures, transformations or calls.
- 30 -
3.3.3.1 Start/End These two atoms are generated automatically. They are indicating the start and the end point of a processing flow.
The start atom contains the name of the Bizflow (extension is bfd). The Refresh icon allows you to refresh the graphic of the complete BizFlow. The Add icon allows you to add a new Bizatom at this place and the View icon opens a browser window, showing you the Bizflow in xml format. The graphical language is an abstraction of the bfd language. If you are familiar with the Bizflow syntax, you can also maintain the bfd document directly via your xml editor. Further details regarding the bfd and the BizProcessor you will find in Control Center Development BPC Reference
3.3.3.2 Conditional Processing The conditional processing allows you different processing, based on conditions in the message, specified by an xpath expression.
You can have multiple path atoms and one otherwise atom. All path for which the condition is true, will be processed. The unbranch atom will continue processing when all path are processed. Please notify that this is different to the xsl:switch which is processing the first true condition only. As B1i is typically working in parallel mode, the processing order of different path is at random. The Status icon ( or ) denotes if the atom design is consistent or if some parameter are missing. The Info icon opens a window with the defined parameters. Clicking the Edit icon allows you to maintain the atom parameter, whereas the Delete icon will delete the particular atom, the complete path or the complete branch. Please use the Add icon to add a new Bizatom on the right. With Add icon you add a new path to the branch.
- 31 -
The otherwise path will be processed in case no one of the existing path conditions is true. If you click the radio button, the otherwise path will always be processed. This is used to bypass the original message in case the original message will be lost inside the path processing.
BIU This read-only field displays the name of the current Scenario Step. Branch Identifier This read-only field displays the name of the corresponding Branch atom. This name is generated automatically. Path Identifier This read-only field displays the number of the current Path. Please notify that the number is not indicating the processing order of multiple path constructs. This number is generated automatically. xPath Expression Here you specify which part of the message is handed over to the path processing and the condition to process this path. Please notify that you cannot use variables for this xPath expression, so you have to declare the full path (e.g. /*[/vpf:Msg/vpf:Body/vpf:Payload[./@Role='S']/inbound/flag='true']). In case the expression is too complex, you should run a transformation before (add a Transformation atom before the branch) which will calculate a simple flag that you can check instead. As mentioned before, the Unbranch will consolidate the results of all path processings. To guarantee a wellformed xml document, the Unbranch will add an artificial root tag <bfa:unbranch> to cover all results. Please consider this in the first following Transformation atom (refer to chapter 3.3.3.4).
<bfa:unbranch xmlns:bfa="urn:com.sap.b1i.bizprocessor:bizatoms" schemaversion="1.0"> ... </bfa:unbranch>
- 32 -
3.3.3.3 For Each Processing The For-Each processing allows you to run through iterations during the processing flow, typically for all elements of a particular type or name, depending on a condition. You can use this e.g. in order transformation to run through a processing for each position.
The For-Each construct consists out of the start atom for-each and the end atom join. The join atom will continue processing when all iterations are finished. As B1i is typically working in parallel mode, the processing order of different iterations will not necessarily follow the order of the positions and is at random. The Status icon ( or ) denotes if the atom design is consistent or if some parameter are missing. Clicking the Edit icon allows you to maintain the atom parameter, whereas the Delete icon will delete the complete processing between the for-each and the join. Please use the Add icon to add a new Bizatom on the right.
BIU This read-only field displays the name of the current Scenario Step. Identifier This read-only field displays the identifier of the atom. This identifier is generated automatically. Description This field is for your comments.
- 33 -
Expression Here you specify which parts of the message will be handed over to the foreach processing. Please notify that you cannot use variables for this xPath expression, so you have to declare the full path. In case the expression is too complex, you should run a transformation before (add a Transformation atom before the for-each) which will calculate a simple flag that you can check instead. The message inside the processing will have the last element of the defined xpath expression as root tag. E.g. the xpath statement from our example /vpf:Msg/vpf:Body/vpf:Payload[./@id='atom5']/Order/Position[./@status='ok'] will have the root tag <Position>. As mentioned before, the Join will consolidate the results of all iterations. To guarantee a well formed xml document, the Join will add an artificial root tag <bfa:join> to cover all results. Please consider this in the first following Transformation atom (refer to chapter 3.3.3.4).
<bfa:join xmlns:bfa="urn:com.sap.b1i.bizprocessor:bizatoms" schemaversion="1.0"> ... </bfa:join>
Please notify that typically a for-each processing will in-valid your B1i message. Therefore you need to include the for-each in side a path of a conditional processing with otherwise (always=true) to bypass the message.
The next atom following the unbranch atom will receive a message containing the complete processing results and has to consolidate it to a standard B1i message. Please consider this in the first following Transformation atom (refer to chapter 3.3.3.4).The message format will be:
<bfa:unbranch xmlns:bfa="urn:com.sap.b1i.bizprocessor:bizatoms" schemaversion="1.0"> <bfa:join xmlns:bfa="urn:com.sap.b1i.bizprocessor:bizatoms" schemaversion="1.0"> ... </bfa:join> <vpf:Msg xmlns:vpf="urn:com.sap.b1i.vplatform:entity"> ... </vpf:Msg> </bfa:unbranch>
- 34 -
3.3.3.4 Transformation (xform and final) There are two different types of transformations, the xform and the final transformation. The final transformation is always at the end of the processing flow. It occurs exactly once and cannot be deleted. Xform transformation you can have many.
Whereas all other Bizatoms are definitions only, which are located inside the one Bizflow document (vBIU.bfd), each transformation has a corresponding xsl document. This document is generated automatically when you add a new transformation atom to the flow. The name of the xsl document is equal the identifier of the transformation atom with the extension xsl (e.g. atom1.xsl). To avoid unintended deletion of the xsl file, the Integration framework will not delete the xsl file in case the transformation atom will be deleted in the flow definition. Please notify that you have to clean the vBIU base directory in the Bizstore in /com.sap.b1i.vplatform.scenarios.design/vBIU.biuname). Further details how to access the Bizstore youll find in the reference guide 01. With clicking on the atom-box, you open a window to display the xsl. The Status icon ( or ) denotes if the atom design is consistent or if some parameter are missing. Clicking the The Info icon opens a window with the defined parameters. Edit icon allows you to maintain the atom parameter, whereas the Delete icon will delete the transformation atom. Please use the Add icon to add a new Bizatom on the right.
- 35 -
BIU This read-only field displays the name of the current Scenario Step. Identifier This read-only field displays the identifier of the atom. This identifier is generated automatically. XSL Here you specify the name of the xsl stylesheet which is called to do the transformation. By default the name of the automatically generated stylesheet is inserted. You can use the button to open a drop-down list to select another xsl from the BizStore. This could make sense in case you have a generic stylesheet to be called from different places. Even dynamic definition is possible e.g. if you run before a transformation to calculate the name iof the stylesheet to be called, you can specify here an xpath to pick up the calculated name from the incoming message. A leading # indicates an explicit value. Description This field is for your comments. Properties Optional you can handover properties to the xsl stylesheet, e.g. if you are using a generic stylesheet with different mode, you can handover the mode. The parameter supports multiple properties, to be separated by comma. The syntax to define one property is id{value}.
Editing the Stylesheet The stylesheet is located in the base directory of the Scenario Step in the BizStore (/com.sap.b1i.vplatform.scenarios.design/vBIU.name). Please use a usual xml editor to edit this document. SAP strongly recommends to use an xml editor which supports WebDAV. This will allow you to work with a zero-development roundtrip as the change will have immediate effect. For more details please refer to the reference guide 01.
Design of the XSL stylesheet The XSL stylesheet is generated automatically when you create a new transformation atom in the processing flow. The document consists out of a fix part that should not be modified as it guarantees the production of a well formed B1i message and the working area, where you have to implement the logic which is required.
- 36 -
Integration framework for SAP Business One 02 Scenario Development <xsl:stylesheet xmlns: ...> <xsl:output method="xml" encoding="UTF-8" indent="yes"/> <xsl:param name="atom"/> <xsl:param name="sessionid"/> <xsl:variable name="msg" select="/vpf:Msg/vpf:Body/vpf:Payload[./@Role='S']"/> <xsl:variable name="vpSender" select="/vpf:Msg/vpf:Header/vpf:Sender/@Id"/> <xsl:variable name="vpObject" select="/vpf:Msg/vpf:Header/vpf:Sender/@ObjId"/> <xsl:variable name="vpReceiver" select="/vpf:Msg/vpf:Header/vpf:Receiver/@Id"/> <xsl:template match="/"> <Msg xmlns="urn:com.sap.b1i.vplatform:entity"> <xsl:copy-of select="/vpf:Msg/@*"/> <xsl:copy-of select="/vpf:Msg/vpf:Header"/> <Body> <xsl:copy-of select="/vpf:Msg/vpf:Body/*"/> <Payload Role="X" id="{$atom}"> <xsl:call-template name="transform"/> </Payload> </Body> </Msg> </xsl:template> <xsl:template name="transform"> <xsl:copy-of select="$msg/*"/> </xsl:template> </xsl:stylesheet>
Working Area
In the working area, you specify the outbound message based on your requirements. Please remove the automatically generated <xsl:copy-of>. The final outbound message is depending on the receiver system and you have to follow the design specifications. In the reference guide 05, the different outbound schemas are defined.
Multiple Outbound Messages Typically the processing flow will produce one outbound message. In the Integration framework, you also have the option to generate multiple outbound messages by introducing the artificial tag <b1im_multimsg>.
<b1im_multimsg> <b1im_msg> </b1im_msg> <b1im_msg> </b1im_msg> </b1im_multimsg>
If you are using the multi-message feature, you have to create a tag <b1im_msg> for each outbound message. Skip Outbound Message Typically the processing flow will produce one outbound message. In the Integration framework, you also have the option to stop the processing. In this
- 37 -
case no message will be handed over to the receiver system. You initiate the skip by introducing the artificial tag <b1im_skip>.
<b1im_skip info=my info msglog=true>
By default, the skipped message will be shown in the Message Log in the section for the filtered messages. The optional attribute msglog allows you to avoid the display in the Message Log. With the attribute info you can define your individual information to be displayed in the Message Log.
Document Retrieval from the BizStore In case you want to retrieve data from a document, stored in the BizStore, you can use the standard document() function. This function is overlayed by B1i and will allow you very comfortable to retrieve the document from the BizStore but just specifying the full path.
<xsl:variable name="doc" select="document('/com.mycompany/repository/settings.xml')"/>
With a simple <choose> construct you can detect if the document does exist and trigger conditional processing.
<xsl:choose> <xsl:when test="count($doc/bfa:docnotfound)>0"></xsl:when> <xsl:otherwise> document exists ... </xsl:otherwise> </xsl:choose>
Specialties in an XSL stylesheet after a branch and/or for-each atom In case the predecessor atom was an unbranch or a join atom, you have to modify the fix part of the xsl stylesheet to consider the artificial tag <bfa:unbranch> respectively <bfa:join>. Due to the Bizflow debugging functionality the intermediate inter atom messages can be seen during the development. We strongly recommend to use this powerful functionality. The Bizflow debugging functionality is described in chapter 3.3.5.
<xsl:template match="/"> <Msg xmlns="urn:com.sap.b1i.vplatform:entity"> <xsl:copy-of select="/bfa:unbranch/vpf:Msg/@*"/> <xsl:copy-of select="/bfa:unbranch/vpf:Msg/vpf:Header"/> <Body> <xsl:copy-of select="/bfa:unbranch/vpf:Msg/vpf:Body/*"/> <Payload Role="X" id="{$atom}"> <xsl:call-template name="transform"/> </Payload> </Body> </Msg> </xsl:template>
- 38 -
Integration framework for SAP Business One 02 Scenario Development <xsl:template match="/"> <Msg xmlns="urn:com.sap.b1i.vplatform:entity"> <xsl:copy-of select="/bfa:join/vpf:Msg/@*"/> <xsl:copy-of select="/bfa:join/vpf:Msg/vpf:Header"/> <Body> <xsl:copy-of select="/bfa:join/vpf:Msg/vpf:Body/*"/> <Payload Role="X" id="{$atom}"> <xsl:call-template name="transform"/> </Payload> </Body> </Msg> </xsl:template>
The Integration framework will re-generate the namespaces and variables in all related documents frequently, therefore modifications of the variables will be temporary only.
Result The transformation atom will process the xsl stylesheet and will add the result to the Body of the B1i message by adding a new Payload section where the attribute id will have the value of the atom identifier. An xform atom will set the attribute Role=X whereas a final atom will set the attribute Role=R which indicates the final result message to be handed over to the receiver system.
<Payload Role="X" id="atomid"> ... </Payload>
3.3.3.5 Call SQL With the help of this atom you can perform a multiple sql calls to any Database system. Prerequisite is that the system is defined in the System Landscape Directory (SLD). Please refer to reference guide 04, chapter 3.6.
The Status icon ( or ) denotes if the atom design is consistent or if some parameter are missing. Clicking the Info icon opens a window with the defined parameters. The Edit icon allows you to maintain the atom parameter, whereas the Delete icon will delete the atom from the flow. Please use the Add icon to add a new Bizatom on the right.
- 39 -
Scenario Step Identifier This read-only field displays the name of the current Scenario Step. Identifier This read-only field displays the identifier of the atom. This identifier is generated automatically. Description This field is for your comments. SysId Here you specify the logical address (SysId) of the system to call. Please use the button to open a drop-down list with all currently existing systems, relevant for this type of call (B1.*, J.AnySystem). You can choose one of these or you can select the variables B1 System, based on User or Sender System. In case you are using variables, the system gets detected automatically during runtime. In case you are using explicite SysIds from the SLD, you have to make sure that later in the runtime, the system setup will be the same to ensure the same SysId. Prerequisite for using the variable B1 System, based on User is an HTTP based sender system (H.AnySystem, W.AnySystem) for the Scenario Step and a setup of the Scenario Package with authentication and user based session. For scenario setup, please refer to reference guide 04, chapter 1.1. A leading # is indicating an explicit value whereas a missing # will enforce B1i to interpret the string as xpath statement. This allows you to calculate the SysId dynamically in a transformation atom that runs as a predecessor in the flow.
- 40 -
SQL Statement In this field you type in the sql statement that you want to process. In case you want to process multiple sql statements, you can concatenate the single statements, separated by semicolon. Inside the sql statement you can use global and local variables, similar to xsl by typing the name with a leading $ (e.g. $myvar). In addition to these variables it is possible to use directly values from results of predecessor atoms. The syntax is $[atomid/fieldname] (e.g. $[atom9/DocEntry]). Please consider that you have to type the apostrophe in case of a string field ( where code = $var).as the replacement of the variable will just return the pure value. A leading # is indicating an explicit value whereas a missing # will enforce B1i to interpret the string as xpath statement. This allows you to calculate the sql statement(s) dynamically in a transformation atom that runs as a predecessor in the flow. [Variables] As a comfort function you can call the screen to maintain local variables also from here. Please notify that all local variables will be in scope of all Scenario Steps, assigned to the same Scenario Package. Please refer to chapter 2.1 for details. [Save] Save the settings by clicking this button.
Result The atom will process the sql statements and will add the result to the Body of the B1i message by adding a new Payload section where the attribute id will have the value of the atom identifier. Please notify that all tags of the result will be in the xml namespace of jdbc xmlns:jdbc="urn:com.sap.b1i.adapter:jdbcadapter" The attribute system is displaying the logical address (SysId) of the system that was called. The attribute sql is showing the sql statement after replacement of all variables. This gives you all transparency to check whether the used variables and the calculation of the SysId worked as expected.
<Payload Role="C" id="atomid" system="0010000115" sql="sql statement'"> <jdbc:ResultSet rowCount="number"> <jdbc:Row> <jdbc:field1>value</jdbc:field1> ... <jdbc:fieldn>value</jdbc:fieldn> </jdbc:Row> ... </jdbc:ResultSet> </Payload>
- 41 -
In case of multiple sql statements you will have multiple Payload sections where the attribute id will have the value atomidentifier_number (e.g. id=atom1_2) You can also use this atom to call a stored procedure. As the result of a stored procedure could have multiple result sets, the return document is different:
<Payload Role="C" id="atomid" system="0010000115" sql="sql statement'"> <jdbc:ResultSets> <jdbc:ResultSet rowCount="number"> <jdbc:Row> <jdbc:field1>value</jdbc:field1> ... <jdbc:fieldn>value</jdbc:fieldn> </jdbc:Row> ... </jdbc:ResultSet> ... </jdbc:ResultSets> </Payload>
3.3.3.6 Call B1 Object With the help of this atom you can perform a call to an SAP Business One system. Prerequisite is that the system is defined in the System Landscape Directory (SLD). Please refer to reference guide 04, chapter 3.1. The atom supports modifications in SAP Business One (insert, update and delete) and also the retrieval of particular data via the Object method of the SAP Business One DI API.
The Status icon ( or ) denotes if the atom design is consistent or if some parameter are missing. Clicking the Info icon opens a window with the defined parameters. The Edit icon allows you to maintain the atom parameter, whereas the Delete icon will delete the atom from the flow. Please use the Add icon to add a new Bizatom on the right. This atom is one of three atoms that allow you to easily interact with SAP Business One. Other atoms are the B1 Service Call and the possibility to send a message to the SAP Business One inbox. Prerequisite is the knowledge of the application interface of SAP Business One (DI API) as you have to know the schema in case you modify data. For retrieval its sufficient to have knowledge about the object identifier and the primary keys. The Integration framework is supporting you based on the inbuilt repository. However we strongly recommend to consult the SAP Business One DI API help.
- 42 -
Scenario Step Identifier This read-only field displays the name of the current Scenario Step. Atom Identifier This read-only field displays the identifier of the atom. This identifier is generated automatically. Description This field is for your comments. SysId Here you specify the logical address (SysId) of the system to call. Please use the button to open a drop-down list with all currently existing systems, relevant for this type of call (B1.*). You can choose one of these or you can select the variables B1 System, based on User or Sender System. In case you are using variables, the system gets detected automatically during runtime. In case you are using explicite SysIds from the SLD, you have to make sure that later in the runtime, the system setup will be the same to ensure the same SysId. Prerequisite for using the variable B1 System, based on User is an HTTP based sender system (H.AnySystem, W.AnySystem) for the Scenario Step and a setup of the Scenario Package with authentication and user based session. For scenario setup, please refer to reference guide - 43 -
04, chapter 1.1. A leading # is indicating an explicit value whereas a missing # will enforce B1i to interpret the string as xpath statement. This allows you to calculate the SysId dynamically in a transformation atom that runs as a predecessor in the flow. B1 Login Here you define under which login the integration framework should call to the Sap Business One system. Please use the button to open a drop-down list with the available options. You can login as the Technical User or as the Session User. Technical User is the Integration framework itself, typically with the userid B1i. Prerequisite for logging in under the Session User is an HTTP based sender system (H.AnySystem, W.AnySystem) for the Scenario Step and a setup of the Scenario Package with authentication and user based session. For scenario setup, please refer to reference guide 04, chapter 1.1. Due to performance optimization SAP strongly recommends to login as Technical User as this user session is cached by the Integration framework. And log in as the Session User only if required, e.g. because of traceability requirements. Stop processing if fails This switch controls the exception handling in the Integration framework for this call. If you set this switch to false, which is the default setting, the processing will continue in case of an exception. This gives you the possibility for your own error handling in the following transformation atom. If the switch is set to true, an exception will force the processing of your Scenario Step to fail. As a result you will see the message in the Message Log error section. Method Here you select the method, you want to perform in this call. Please use the corresponding button to open a drop-down list with the available options. Synchronous Retrieval Synchronous Insert (exception in case data exists already) Synchronous Insert with fallback to Update Synchronous Update Synchronous Delete Asynchronous Insert (exception in case data exists already) Asynchronous Insert with fallback to Update Asynchronous Update Asynchronous Delete Synchronous calls will wait for the result whereas asynchronous calls will just trigger the call process without waiting for the result. Default should be a synchronous call as typically the result is important for further processing. In case of a synchronous Scenario Step where performance is a critical point and the result is not important for the caller, you can use the asynchronous call method.
- 44 -
Object Identifier Here you specify the object identifier of SAP Business One. This identifier is typically a number (e.g. the identifier for Business Partner is 2). You can use the button to open a drop-down list with the available identifiers. Key Name Here you define the name of the primary key field. In case there are more than one primary key field, please concatenate the values, separated by comma (no space in-between). Key Value Here you define the values for the primary key fields. In case there are more than one primary key field, please concatenate the values (in the same order as the field names), separated by comma (no space in-between). You can use global and local variables, similar to xsl by typing the name with a leading $ (e.g. $myvar). In addition to these variables it is possible to use directly values from results of predecessor atoms. The syntax is $[atomid/fieldname] (e.g. $[atom9/DocEntry]). A leading # is indicating an explicit value whereas a missing # will enforce B1i to interpret the string as xpath statement. This allows you to calculate the key values(s) dynamically in a transformation atom that runs as a predecessor in the flow. Payload Here you specify the name of a predecessor transformation atom. The result of this atom will be handed over as the payload to the Business One DI API. The payload must follow the definitions of the DI API XML interface. Please refer to the appropriate DI API help. This parameter is not needed for data retrieval.
[Variables] As a comfort function you can call the screen to maintain local variables also from here. Please notify that all local variables will be in scope of all Scenario Steps, assigned to the same Scenario Package. Please refer to chapter 2.1 for details. [Save] Save the settings by clicking this button.
Result The atom will process the B1 call and will add the result to the Body of the B1i message by adding a new Payload section where the attribute id will have the value of the atom identifier, the attribute Role=C. Additional values for trouble shooting are available via the following attributes: system: Logical address (SysId) of the SAP Business One system method. Called Method objecttd: Object Identifier - 45 -
keyname: keyvalue: status: DIresult: DImsg:
Name of the primary key(s) Values of the primary key(s) Call status Original DI result (success or failure) Original DI return message (e.g. Record not found!)
<Payload Role="C" id="..." system="..." method="..." objectid="..." keyname="..." keyvalue="..." status="..." DIresult="..." DImsg="..."> <BOM xmlns=""> ... </BOM> </Payload>
3.3.3.7 Call B1 Service
3.3.3.8 Call RFC
3.3.3.9 Call SQL
3.3.3.10 Call any Java Class
3.3.3.11 Conversion XML to JSON
3.3.3.12 Conversion Binary to XML
3.3.3.13 Generate Crystal Report
3.3.3.14 Retrieve File from Filesystem
- 46 -
3.3.3.15 Persist Douments/Groups
3.3.3.16 Put Message to Queue
3.3.4 XSL Development

3.3.4.1 Some very basics about XSL XSLT is a powerful, declarative language to manipulate XML documents in a very efficient way. Although it needs some experiences if you want to use the full power behind XSLT, you can start immediately with just some basics because typically you will need only a small subset of XSLT to fulfill your task. As a working principle you can say, you are in the role of a printer and your task is to print the correct outbound message for the receiver. The information you have is the current inbound message, which is sent from the sender system resp. the predecessor atom. Like a printer you cannot jump from the end to the beginning to add some data. Your development flow is strictly sequential. Your outbound is always an XML document which means it has to follow the XML guidelines. Therefore you have to know that an XML document has to have exactly one root tag. So you start your task by writing the roottag of your outbound message. Each tag consists out of a beginning- and end-tag which can be written in one line or in two lines. Between a beginning- and end-tag, you will have a concrete value or more nested beginning- and endtags. Lets assume you have the following sender message and your task is to create the following receiver message:
- 47 -
The listed XSL will do the transformation.
First you create the root-tag <RCVMsg></RcvMsg> and then you start defining the message. You create the header tags <RcvHeaderFieldA> and <RcvHeaderFieldB>, in-between you insert the value of the sender message. This is done by using the XSL-command <xsl:value-of> which is the most important command. In the select-section of this command, you write the Xpath-statement of the exact location in the sender message where you want to retrieve the value, in our example SNDMsg/Header/Fieldx. Now we introduce a variable with the name linecount, to be done by using the XSLcommand <xsl:variable>. To this variable, we assign the number of lines in the sender message, which is equal the number of tags with the name <Line> in-between the tag <Lines>. We again describe the location with an Xpathstatement count(SNDMsg/Lines/Line). To finish the header information, we create the third tag <LineCount> and place the value which we have already in our variable. You use a variable always with a $, followed by the name of the variable. The next part is to provide the lines of the message. This we want to do only in case there is at least one line in the sender message. The condition in XSL is the command <xsl:if>. Please consider that you have to be
- 48 -
careful with special characters (like <, >, &), in our case instead of > you should use the sequence >. Another very important XSL-command is the command <xsl:for-each> which allows you to run through multiple sections in a message. In our example we run through all lines, again the sections are defined by an Xpath statement. For each these sections we create now the tag <RcvLine> and in-between the attribute pos to which we assign the current position number, using the function position(). Then we create the two needed tags <First> and <Second> and we assign the values from the sender message, again with the XSL-command <xsl:value-of>. Please consider, that you are at this point of time inside the for-each section which means you have to address the location of the value relatively to the section you are in. Means, you need to specify the Xpath with ./LFieldx where . is addressing the current tag. Please check the available tutorials and manuals for further details.
3.3.4.2 The B1i XSL Library The Integration framework provides a library for typical tasks during the field assignment. Library functions are called templates in XSL. To have the templates available for your usage, you need to include the library document by using the include command at the end of your XSL.
<xsl:include href="libraryname"/>
Please use the administration console of the Integration framework to call the XSL Library.
Development
XSLT Library
- 49 -
Currently there are four XSLT libraries available: String operations Date/Time operations System operations SAP Business One The String operations are providing some very helpful functions to manipulate strings, respectively to retrieve some information from them, e.g. to delete leading zeros in a string or to replace substrings with other substrings. The Date/Time operations are providing functions around the date and time. E.g. you can retrieve the current date and time and it allows you to calculate some special dates or to provide formatted output. The System operations are more technical, e.g. to generate a globally unique identifier (GUID). The SAP Business One library is providing some special formatting. The drop-down list displays all available libraries. Please choose the library you are interested in. You can test the XSLT library, available in your B1i installation directly by clicking the Test button. Click the Load Docu button to open the documentation. The documentation displays a list of all existing templates with a short description. All templates are starting with the abbreviation b1ilib., followed by the actual name. At the beginning of the documentation, the exact include command is given. Just copy it from the documentation and paste it to the appropriate place in your XSL stylesheet.
- 50 -
Remark: without this include instruction, the template will not be accessible during the runtime and a runtime error will occurs.
If you are interested in a particular functionality, just click on the name which will position the document to the detailed description. E.g. if you are interested in detailed information about the template b1ilib.today_minus, just click on the name to get information about how to call it, a detailed description, the parameters, the default settings and a usage example. The Usage-Example is very helpful because you can just copy it to paste it directly to your XSL stylesheet.
- 51 -
With Back to Top you navigate back to the overall list.
3.3.5 Test Environment and Debug Mode
4. Develop a user defined Authentication
- 52 -
Appendix A. Table of Inbound Channels

Channel (IPO) INB_WS_CALL_SYNC_XPT INB_HT_CALL_SYNC_XPT INB_B1_HTTP_SYNC_B1H INB_WS_CALL_ASYN_XPT INB_WS_TIMR_ASYN_FIX INB_HT_CALL_ASYN_XPT INB_HT_TIMR_ASYN_FIX INB_B1_EVNT_ASYN_EVT INB_B1_TIMR_ASYN_FIX Syste m ws ws http http B1 ws ws ws http http http B1 B1 file file file file file file file file file file file file R/3 R/3 R/3 vBIU Queue DB FTP FTP FTP FTP FTP FTP FTP Inbound Mode Trigger WSAR Call WSAR Call HTTP Call HTTP Call HTTP Call WSAO Call WSAO Call Timer HTTP Call HTTP Call Timer B1 Event Timer File exist File exist File exist File exist File exist File exist Timer Timer Timer Timer Timer Timer IDOC IDOC Timer Queue Queue Timer File exist File exist File exist File exist File exist File exist Timer Mode SYNC SYNC SYNC SYNC SYNC ASYNC ASYNC ASYNC ASYNC ASYNC ASYNC ASYNC ASYNC ASYNC ASYNC ASYNC ASYNC ASYNC ASYNC ASYNC ASYNC ASYNC ASYNC ASYNC ASYNC ASYNC ASYNC ASYNC ASYNC ASYNC ASYNC ASYNC ASYNC ASYNC ASYNC ASYNC ASYNC ASYNC Identification xPath Root Tag xPath Root Tag B1 HTTP xPath Root Tag Fix Value xPath Root Tag Fix Value B1 Event Fix Value xPath Root Tag B1 Logic File Name Fix Value First Line xPath Root Tag B1 Logic File Name Fix Value First Line xPath Root Tag Fix Value vBIU Name Fix Value Fix Value xPath Root Tag B1 Logic File Name Fix Value First Line xPath
INB_FI_EXST_ASYN_XPT INB_FI_EXST_ASYN_NAM INB_FI_EXST_ASYN_FIX INB_FI_EXST_ASYN_FSL
INB_FI_TIMR_ASYN_XPT INB_FI_TIMR_ASYN_NAM INB_FI_TIMR_ASYN_FIX INB_FI_TIMR_ASYN_FSL INB_R3_IDOC_ASYN_XPT INB_R3_TIMR_ASYN_FIX INB_IQ_INTQ_ASYN_BIU INB_IQ_INTQ_ASYN_QS INB_DB_TIMR_ASYN_FIX
INB_FT_EXST_ASYN_XPT INB_FT_EXST_ASYN_NAM INB_FT_EXST_ASYN_FIX INB_FT_EXST_ASYN_FSL INB_FT_TIMR_ASYN_XPT
- 53 -
INB_FT_TIMR_ASYN_NAM INB_FT_TIMR_ASYN_FIX INB_FT_TIMR_ASYN_FSL INB_P3_TIMR_ASYN_SUB INB_P3_TIMR_ASYN_FSL INB_IM_TIMR_ASYN_SUB INB_IM_TIMR_ASYN_FSL
FTP FTP FTP FTP FTP email email email email
Timer Timer Timer Timer Timer Timer Timer Timer Timer
ASYNC ASYNC ASYNC ASYNC ASYNC ASYNC ASYNC ASYNC ASYNC
Root Tag B1 Logic File Name Fix Value First Line Subject First Line Subject First Line
- 54 -
Appendix B. Table of Outbound Channels

Outbound Mode IPO System Adapter JDBC JDBC JDBC JDBC SMTP FILO FILO FILO FTPO FTPO FTPO HTTA WSAN DIAPI DIAPI DIAPI DIAPI JDBC JDBC JDBC JDBC JDBC JDBC Multiple SQL SQL B1i B1i B1i XML XML XML XML XML XML B1i B1i Object Object Service Service JDBC JDBC JDBC JDBC JDBC JDBC Multiple Format DB DB DB OUT_DB DB OUT_SMTP email file file OUT_FILE file FTP FTP OUT_FTP FTP OUT_HTTP HTTP OUT_WS WS B1 B1 B1 B1 B1 B1 B1 B1 B1 B1 OUT_B1 B1 Details single multiple single multiple Formatting xml xml xml xml xml xml dsv txt xml dsv txt xml xml xml xml xml xml xml xml xml xml xml xml xml yes yes yes yes yes yes Method Ctrl.Doc Frmt Doc Enc.
yes
yes pars pars pars yes
DI reduced DI full DI reduced DI full sql reduced sql reduced sql full sql full B1isql B1isql
single yes multiple single multiple single multiple
- 55 -
Appendix C. Table of Process Steps

vBIU System Type Process Step ID PRC_B1 PRQ_B1 PRC_BH PRQ_BH INB_B1_TIMR_ASYN_FIX PRC_BF SAP Business One PRQ_BF OUT_B1 PRC_R3 PRQ_R3 INB_B1_TIMR_ASYN_FIX PRC_RT PRQ_RT SAP ERP OUT_R3 INB_DB_TIMR_ASYN_FIX PRC_DB PRQ_DB Database OUT_DB INB_FI_EXST_ASYN_XPT PRC_FIx PRQ_FIx PRC_FIn PRQ_FIn INB_FI_EXST_ASYN_FSL PRC_FIf PRQ_FIf INB_FI_EXST_ASYN_FIX PRC_FIi PRQ_FIi INB_FI_TIMR_ASYN_XPT File System PRC_FTx Phase Processing Processing Processing Processing Inbound Processing Processing Outbound Processing Processing Inbound Processing Processing Outbound Inbound Processing Processing Outbound Inbound Processing Processing Processing Processing Inbound Processing Processing Inbound Processing Processing Inbound Processing Task Event triggered Data Retrieval Data Distributor Incoming HTTP call Data Retrieval Data Distributor Timer triggered Data Retrieval Data Distributor Outbound IDOC triggered Data Retrieval Data Distributor Timer triggered Data Retrieval Data Distributor Outbound Timer triggered Data Retrieval Data Distributor Outbound file exist trriggered Data Retrieval Data Distributor file exist trriggered Data Retrieval Data Distributor file exist trriggered Data Retrieval Data Distributor file exist trriggered Data Retrieval Data Distributor timer trriggered Data Retrieval asynchronus asynchronus asynchronus asynchronus asynchronus asynchronus asynchronus asynchronus asynchronus synchronous Processing asynchronus INB_B1_EVNT_ASYN_EVT Inbound
INB_B1_HTTP_SYNC_B1H Inbound
INB_R3_IDOC_ASYN_XPT Inbound
INB_FI_EXST_ASYN_NAM Inbound
- 56 -
PRQ_FTx PRC_FTn PRQ_FTn INB_FI_TIMR_ASYN_FSL PRC_FTi PRQ_FTi INB_FI_TIMR_ASYN_FIX PRC_FTf PRQ_FTf OUT_FILE INB_HT_CALL_SYNC_XPT INB_HT_CALL_ASYN_XPT PRC_HT PRQ_HT INB_HT_TIMR_ASYN_FIX PRC_HR PRQ_HR HTTP OUT_HTTP
Processing Processing Processing Inbound Processing Processing Inbound Processing Processing Outbound Inbound Inbound Processing Processing Inbound Processing Processing Outbound
Data Distributor timer trriggered Data Retrieval Data Distributor timer trriggered Data Retrieval Data Distributor timer trriggered Data Retrieval Data Distributor Outbound Incoming HTTP call Incoming HTTP call Data Retrieval Data Distributor Timer triggered Data Retrieval Data Distributor Outbound Incoming HTTP call Incoming HTTP call Data Retrieval Data Distributor Timer triggered Data Retrieval Data Distributor Outbound Timer triggered, Pop3 Data Retrieval Data Distributor Timer triggerd, Pop3 Data Retrieval Data Distributor Timer triggered, Pop3 Data Retrieval Data Distributor Timer triggerd, Pop3 Data Retrieval Data Distributor asynchronus asynchronus asynchronus asynchronus asynchronus synchronous asynchronus asynchronus synchronous asynchronus asynchronus asynchronus asynchronus
INB_FI_TIMR_ASYN_NAM Inbound
INB_WS_CALL_SYNC_XPT Inbound INB_WS_CALL_ASYN_XPT Inbound PRC_WS PRQ_WS PRC_WT PRQ_WT Web Service OUT_WS PRC_3S PRQ_3S INB_P3_TIMR_ASYN_FSL PRC_3F PRQ_3F PRC_IS PRQ_IS INB_IM_TIMR_ASYN_FSL PRC_IF eMail PRQ_IF Processing Processing Processing Processing Outbound Processing Processing Inbound Processing Processing Processing Processing Inbound Processing Processing
INB_WS_TIMR_ASYN_FIX Inbound
INB_P3_TIMR_ASYN_SUB Inbound
INB_IM_TIMR_ASYN_SUB Inbound
- 57 -
OUT_SMTP INB_FT_EXST_ASYN_XPT PRC_FPx PRQ_FPx INB_FT_EXST_ASYN_NAM PRC_FPn PRQ_FPn INB_FT_EXST_ASYN_FSL PRC_FPf PRQ_FPf INB_FT_EXST_ASYN_FIX PRC_FPi PRQ_FPi INB_FT_TIMR_ASYN_XPT PRC_FRx PRQ_FRx INB_FI_TIMR_ASYN_NAM PRC_FRn PRQ_FRn INB_FI_TIMR_ASYN_FSL PRC_FRi PRQ_FRi INB_FI_TIMR_ASYN_FIX PRC_FRf PRQ_FRf OUT_FTP INB_IQ_INTQ_ASYN_BIU PRQ_IQ INB_WS_CALL_ASYN_XPT PRC_QS PRQ_QS VOID
Outbound Inbound Processing Processing Inbound Processing Processing Inbound Processing Processing Inbound Processing Processing Inbound Processing Processing Inbound Processing Processing Inbound Processing Processing Inbound Processing Processing Outbound Inbound Processing Inbound Processing Processing Outbound
Outbound file exist trriggered Data Retrieval Data Distributor file exist trriggered Data Retrieval Data Distributor file exist trriggered Data Retrieval Data Distributor file exist trriggered Data Retrieval Data Distributor timer trriggered Data Retrieval Data Distributor timer trriggered Data Retrieval Data Distributor timer trriggered Data Retrieval Data Distributor timer trriggered Data Retrieval Data Distributor Outbound vBIU triggered Data Processing Internal Queue triggered Data Retrieval Data Distributor Outbound asynchronus
asynchronus
asynchronus
asynchronus
asynchronus
asynchronus
asynchronus
asynchronus
FTP Predecessor
asynchronus
asynchronus
Internal Queue Void
- 58 -
Copyrights, Trademarks, and Disclaimers

Copyright 2010 SAP AG. All rights reserved. The current version of the copyrights, trademarks, and disclaimers at http://service.sap.com/smb/sbocustomer/documentation is valid for this document.
- 59 -

B1 I FW02 Scen Dev

Uploaded by

Copyright:

Available Formats

B1 I FW02 Scen Dev

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

B1 I FW02 Scen Dev

Uploaded by

Copyright:

Available Formats

Integration framework for SAP Business One 02 Scenario Development

Author: Heinz Pauly Version: 1.0 Date: June 21, 2010

Integration framework for SAP Business One 02 Scenario Development

Integration framework for SAP Business One 02 Scenario Development

1. Concepts of the Scenario Development

Integration framework for SAP Business One 02 Scenario Development

Integration framework for SAP Business One 02 Scenario Development

2. Create a Scenario Package

Scenarios Scenario Package Design

Integration framework for SAP Business One 02 Scenario Development

Integration framework for SAP Business One 02 Scenario Development

Integration framework for SAP Business One 02 Scenario Development

2.2 Properties (not yet supported)

Integration framework for SAP Business One 02 Scenario Development

3. Develop a Scenario Step

Scenarios Scenario Step Design

Integration framework for SAP Business One 02 Scenario Development

Integration framework for SAP Business One 02 Scenario Development

3.1 Scenario Step Inbound

Integration framework for SAP Business One 02 Scenario Development

3.1.1 Scenario Step Inbound Channel

Integration framework for SAP Business One 02 Scenario Development

Integration framework for SAP Business One 02 Scenario Development

Integration framework for SAP Business One 02 Scenario Development

Integration framework for SAP Business One 02 Scenario Development

Integration framework for SAP Business One 02 Scenario Development

3.1.2 Scenario Step Inbound Retrieval

Integration framework for SAP Business One 02 Scenario Development

[Save] Please save your settings by clicking the [Save] button.

Integration framework for SAP Business One 02 Scenario Development

Details for a JDBC call

Details for a DI API Service call

Integration framework for SAP Business One 02 Scenario Development

Details for an RFC call

Integration framework for SAP Business One 02 Scenario Development

3.1.3 Scenario Step Inbound Formatting

Integration framework for SAP Business One 02 Scenario Development

3.2 Scenario Step Outbound

Integration framework for SAP Business One 02 Scenario Development

[Save] Please save your settings by clicking the [Save] button.

Integration framework for SAP Business One 02 Scenario Development

Details for Outbound Channel Flat File

Integration framework for SAP Business One 02 Scenario Development

Details for Outbound Format DI Object

Integration framework for SAP Business One 02 Scenario Development

Details for Outbound Format DI Service

Integration framework for SAP Business One 02 Scenario Development

Add method Update method Remove method

Details for Outbound Channel Web Service

Integration framework for SAP Business One 02 Scenario Development

Details for Outbound Format SQL or Outbound Channel Database

Integration framework for SAP Business One 02 Scenario Development

3.3 Scenario Step Processing

3.3.1 The Processing Flow

3.3.2 The B1i Message Format

Integration framework for SAP Business One 02 Scenario Development

3.3.3 The Bizflow Language (Design)

Integration framework for SAP Business One 02 Scenario Development

Integration framework for SAP Business One 02 Scenario Development