How-To Guide PUBLIC
Integration Framework
Document Version: 1.3 – 2020-02-04
How-To Use the Enhanced DI Adapter
All Countries
Typographic Conventions
Type Style Description
Example Words or characters quoted from the screen. These include field names, screen titles,
pushbuttons labels, menu names, menu paths, and menu options.
Textual cross-references to other documents.
Example Emphasized words or expressions.
EXAMPLE Technical names of system objects. These include report names, program names,
transaction codes, table names, and key concepts of a programming language when they
are surrounded by body text, for example, SELECT and INCLUDE.
Example Output on the screen. This includes file and directory names and their paths, messages,
names of variables and parameters, source text, and names of installation, upgrade and
database tools.
Example Exact user entry. These are words or characters that you enter in the system exactly as
they appear in the documentation.
<Example> Variable user entry. Angle brackets indicate that you replace these words and characters
with appropriate entries to make entries in the system.
EXAMPLE Keys on the keyboard, for example, F 2 or E N T E R .
PUBLIC How-To Use the Enhanced DI Adapter
2 © 2020 SAP SE or an SAP affiliate company. Typographic Conventions
Document History
Version Date Change
1.0 2014-05-19 Release to Customer
1.1 2015-02-23 Correction for proxy groups
1.2 2018-01-09 Screenshots included, recommendations included
1.3 2020-02-04 Added recommendations for SINGLECOMPANY property
How-To Use the Enhanced DI Adapter PUBLIC
Document History © 2020 SAP SE or an SAP affiliate company. 3
Table of Contents
1 Introduction ................................................................................................................................... 5
2 Participating in the Two-Phase Commit Protocol .................................................................... 6
3 Switching On Single Transaction Handling ............................................................................... 7
3.1 Recommendations for Using the Single Transaction Function ...................................................... 8
4 Using New diproxyserver Properties .......................................................................................... 9
5 Using Proxy Groups..................................................................................................................... 10
5.1 Providing Further DI Proxies ......................................................................................................... 10
5.2 Adding Proxy Groups to the DI Adapter Global Configuration ..................................................... 10
5.3 Using Proxy Groups in Integration Framework SLD ......................................................................12
5.4 Recommendations ........................................................................................................................ 13
PUBLIC How-To Use the Enhanced DI Adapter
4 © 2020 SAP SE or an SAP affiliate company. Table of Contents
1 Introduction
The integration framework DI adapter contributes to the two-phase commit protocol of the integration
framework.
Atomic Behavior of Transactions
The protocol ensures the atomic behavior of transactions. Atomic behavior means that if a transaction fails, all
effects it causes are rolled back. That is, either all changes made by a transaction are reflected on the data in the
SAP Business One company database, or none of them.
Exactly-Once Handling
The two-phase commit protocol also ensures that you can repeat transactions at a later point in time without
unwanted side effects. With a scenario step you want to, for example, create a new business partner and
immediately send an update for the business partner. In the integration framework, creating the new business
partner fails at first attempt. Processing only continues, if the creation is finally successful. Only then, processing
updates the business partner information. The exactly once handling ensures that processing does not create any
duplicate records in SAP Business One.
Supporting the two-phase commit protocol in the DI adapter simplifies development tasks, because developers
can rely on the two-phase commit protocol behavior.
Example
You provide a scenario step that inserts a new business partner and then an order with order items for the
business partner. Participating in the two-phase commit protocol ensures that all changes are performed
consistently.
How-To Use the Enhanced DI Adapter PUBLIC
Introduction © 2020 SAP SE or an SAP affiliate company. 5
2 Participating in the Two-Phase Commit
Protocol
Participating in the two-phase commit protocol causes the following effects:
• SAP Business One provides a mechanism for receiving notifications of data-driven events. Customers or
partners add some code to the SBO_SP_TransactionNotification SAP Business One stored procedure. If you
add code to SBO_SP_TransactionNotification to receive notifications for SAP Business One object changes
and act on them accordingly, the notification does not work in conjunction with the integration framework
processing.
The integration framework only commits or rolls back calls at the end of the processing phase, and not after
each call to SAP Business One. If you design your notification in such a way that it rejects changes for a
certain object, is it too late to do so at the end of the processing phase. This leads to an error that cannot be
resolved automatically and complex manual steps are required.
The DI transaction stays in in-doubt status, and the integration framework deactivates the IPO step. The
integration framework recovery function tries to perform the transaction again after some time, but cannot
succeed. If other subsequent steps try to perform their functions, but cannot do so, the integration
framework deactivates them, too. If the integration framework has to handle many deactivated steps, other
internal IPO steps are also affected and the overall performance is getting worse.
• As long as a scenario step processing communicates with SAP Business One using the DI API, the related
records in SAP Business One are locked for other users and processes, and the connection to the DI stays
open. The related resources are occupied. This can have a negative impact on the overall performance.
PUBLIC How-To Use the Enhanced DI Adapter
6 © 2020 SAP SE or an SAP affiliate company. Participating in the Two-Phase Commit Protocol
3 Switching On Single Transaction Handling
To provide an alternative to the two-phase commit handling, a new setting is available in the integration
framework.
For each scenario step, you can choose to continue using the two-phase commit protocol, or to change the
adapter behavior to perform single, or one round-trip transaction.
Setting in Scenario Step Design
To enable the new behavior, in the Scenario Step Design user interface, choose the SAP Business One DI Single
Transaction checkbox. By default, the integration framework continues supporting the two-phase commit
protocol and is therefore backwards compatible.
If you choose the new behavior for your scenario step, the following applies:
• For the scenario step, the changed behavior affects SAP Business One inbound, the SAP Business One
object, service, function, and the message call atoms, and SAP Business One outbound.
• Calls to SAP Business One are self-contained and the effects are immediately persistent after the return of
the call. The behavior is similar to HTTP or synchronous Web service calls.
• Self-contained calls to the SAP Business One company database only lock the database for a very short time.
• Since the adapter no longer participates in the two-phase commit protocol, lengthy retry and rollback
mechanisms no longer happen.
• The deactivation of internal integration framework IPO steps in conjunction with the DI API happens less
often.
How-To Use the Enhanced DI Adapter PUBLIC
Switching On Single Transaction Handling © 2020 SAP SE or an SAP affiliate company. 7
3.1 Recommendations for Using the Single Transaction Function
• If you enable the function, the integration framework does not perform the scenario step as an atomic and
consistent transaction.
If an error occurs in the step, provide suitable compensation to undo changes in SAP Business One that have
happened already. Note that for some objects, undoing changes is even not possible in SAP Business One.
• We recommend using the function, if you only access SAP Business One for reading data.
• Use the function, if you only write data to SAP Business One once, and the call to SAP Business One is the
last in processing.
• To make several calls to SAP Business One for writing data, distribute the calls to several steps.
• Do not use the function, if you perform several calls writing to SAP Business One, if the write operations
depend on each other.
PUBLIC How-To Use the Enhanced DI Adapter
8 © 2020 SAP SE or an SAP affiliate company. Switching On Single Transaction Handling
4 Using New diproxyserver Properties
Currently, the DI API only allows one ongoing transaction sequence for a company database at the same time. If
another integration framework IPO step wants to access the same company database, it must wait until the
previous step has finished its tasks. If the second step waits, it occupies integration framework resources that
could handle other processes instead. This leads to inefficient utilization of integration framework resources. The
more steps are waiting, the more the waiting time increases.
To improve the situation, use the following new [Link] settings:
• SINGLECOMPANY=true/false
The parameter controls access to the company databases. If the parameter exists and is set to false,
connections to the same company database are possible. If the parameter does not exist, or is set to true,
multiple connections to the company database are open at the same time, but only one can be used. Other
connections, even with other users are rejected. This is the new behavior. Before, the other connections have
been waiting occupying integration framework resources that could have performed other activities
otherwise.
We recommend setting the property to true.
• MAXACCESES=<number of accesses>
This parameter is only relevant, if you use the two-phase commit protocol. Define the upper limit of
simultaneous accesses that are allowed at the same time. Exceeding this limit, the adapter rejects the
request. The default is 0. This means that unlimited accesses are possible. Especially, if you must shut down
the proxy and start it again, this can take a very long time, if you have many accesses.
• MAXCONNECTIONS=<number of connections>
To constrain the number of simultaneously open DI connections in the DI proxy, use this parameter.
Exceeding the limit, the adapter closes an idle connection, if a new request comes in.
Before, there was no such limit available and each connection was kept open.
How-To Use the Enhanced DI Adapter PUBLIC
Using New diproxyserver Properties © 2020 SAP SE or an SAP affiliate company. 9
5 Using Proxy Groups
The DI adapter allows defining multiple proxy groups in the global adapter configuration properties. This allows
load balancing by processing requests to multiple proxies. Requests can come from IPO steps that are
independent of each other. If you process a step using a certain proxy, it uses the proxy during the complete step
processing.
Additionally, you find the following information in the proxy log file:
• The proxy logs the processing start and stop with the way how the proxy has been stopped.
• Find a usage statistics summary that allows you to decide whether the proxy suits the processing
requirements or whether it should be enhanced to a proxy group to fulfill the overall requests.
5.1 Providing Further DI Proxies
To use DI Proxy groups, user needs to have multiple instances of DI Proxy. To create multiple instances of DI
Proxy, refer to the steps in SAP Note 1975033.
5.2 Adding Proxy Groups to the DI Adapter Global Configuration
In the integration framework, you have the option to define proxy groups with multiple instances of DI proxies.
Define the proxy groups and proxies in the DI adapter global configuration.
User needs to refer to below mentioned steps:
Global Adapter Configuration in Control Center
Procedure
1. In the integration framework, choose Tools → Control Center → Configuration → Global Adapter Config:
PUBLIC How-To Use the Enhanced DI Adapter
10 © 2020 SAP SE or an SAP affiliate company. Using Proxy Groups
2. In the Global Adapter Configuration Properties user interface, for the B1DI adapter, click the Edit Global
Configuration Properties link.
3. For the diProxyGroupList property, define the proxy groups in the following way:
o [<groupname1> <hostname1>:<port1>,<port2>][<groupname2>
<hostname2>:<port1>,<port2>]
o <groupname1,2> are the proxy group names
o <hostname1,2> are the host names or IP addresses of the proxies
o port1,2 are the port numbers
Global Adapter Configuration
Example
• alpha and beta are proxy group name
• abc is server host name where proxies are installed
• 2099, 2098,2097,2096,3000 are ports where proxies are installed on server abc
[alpha abc:2099,2098,2097][beta abc:2096,3000]
If Proxies are installed on different servers then you could use below mentioned
format:
• 2099 proxy is installed on server abc and 2098 is installed on server def
[alpha abc:2099 def:2098]
How-To Use the Enhanced DI Adapter PUBLIC
Using Proxy Groups © 2020 SAP SE or an SAP affiliate company. 11
5.3 Using Proxy Groups in Integration Framework SLD
In SLD, enter the proxy group definition that you want to use for a certain company database in the diProxyhost
field of the SAP Business One company database entry in the following way, for example: [alpha] and [beta]
If you use a proxy group, leave the diProxyport field empty:
Using alpha Proxy Group
PUBLIC How-To Use the Enhanced DI Adapter
12 © 2020 SAP SE or an SAP affiliate company. Using Proxy Groups
Using beta Proxy Group
5.4 Recommendations
• You can achieve the best performance by deploying one DI Proxy instance for each company database.
• If you run a high amount of transactions for one company database, deploy multiple SAP Business One DI
Proxies and set up a DI Proxy group for the company database.
For more information about performance optimization, see SAP Note 2192737
How-To Use the Enhanced DI Adapter PUBLIC
Using Proxy Groups © 2020 SAP SE or an SAP affiliate company. 13
[Link]/contactsap
© 2020 SAP SE or an SAP affiliate company. 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 SE
or an SAP affiliate company. The information contained herein may
be changed without prior notice.
Some software products marketed by SAP SE and its distributors
contain proprietary software components of other software
vendors. National product specifications may vary.
These materials are provided by SAP SE or an SAP affiliate company
for informational purposes only, without representation or warranty
of any kind, and SAP or its affiliated companies shall not be liable for
errors or omissions with respect to the materials. The only
warranties for SAP or SAP affiliate company products and services
are those that are set forth in the express warranty statements
accompanying such products and services, if any. Nothing herein
should be construed as constituting an additional warranty. SAP and
other SAP products and services mentioned herein as well as their
respective logos are trademarks or registered trademarks of SAP
SE (or an SAP affiliate company) in Germany and other countries.
All other product and service names mentioned are the trademarks
of their respective companies.
Please see [Link]
en/legal/copyright/[Link] for additional trademark information
and notices.