You are on page 1of 16

Integration framework

Processing Atom
Call SQL

Last Modified: August 26, 2014

Table of Contents
1 Parameters ............................................................................................................................. 2
1.1 Recommendations for Special Cases ................................................................................ 5
1.2. Filtering Invalid XML Characters from Database Fields .................................................... 5
2 Functions ................................................................................................................................ 6
3 Single Processing ................................................................................................................... 8
4 Blocked Processing in Compatibility Mode .............................................................................. 9
5 Blocked Processing in Batch Mode ......................................................................................... 9
6 Optimizing the SQL Call for Large SQL Statements ...............................................................12
7 Preventing SQL Injection .......................................................................................................13
Copyrights, Trademarks, and Disclaimers .................................................................................16

Call SQL
In the process flow, use this atom to make SQL calls to a database system.

The functional atom Call SQL is of type simple call. You therefore do not need a predecessor
transformation atom to prepare the data you send to the database system. However, if you need
a predecessor transformation atom to calculate data to hand over as an inbound XML document
to the system, add the transformation atom in front of the Call SQL atom. Use a predecessor
atom to handle large SQL statements.

1 Parameters
Scenario Step Identifier
This field is read-only and displays the name of the scenario step for which you develop the
process flow.

Atom Identifier
This field is read-only and displays the name of the processing atom. The name is unique and
the integration framework automatically generates is when creating the atom. The name follows
the convention atom<no> where <no> is a unique number. This name is important. It is the
identifier for subsequent atoms for accessing data of the atom using the XPath expression for
example /vpf:Msg/vpf:Body/vpf:Payload[./@id=atom2]/*.
Public
2014 SAP SE or an SAP affiliate company.
All rights reserved

Description
The integration framework automatically generates the description for the atom during atom
creation. You can change the description. First and foremost it serves as a comment to describe
the task that the atom executes. In the graphical flow, the integration framework displays this
text as mouse over. You can also use the description to change the default label the integration
framework displays on top of the atom. For introducing an individual label, add the new label in
brackets at the end of your description. The integration framework displays the string this is my
comment[my Label], for example as my Label on top of the atom. Note that your label can only
have ten digits.

SysId
Select the system you want call using SQL.
A leading # indicates an explicit value, for example #0010000105 calls the system that has
SysID 0010000105 in the SLD. If you use an explicit SysId from SLD, make sure that later at
runtime, the system is the same to ensure the same SysId. Using the explicit value (with leading
#), you can also use variables and properties.
For more information, click the

button to open the documentation.

You have the following options:


B1 system based on User
You can only use this option for scenario steps triggered by HTTP or Web Services which
run in a session and if the HTTP channel is associated to a B1 system using the SLD
parameter associatedSrvIP.
Sender System
You make the SQL call to the B1 sender system that you have defined in your inbound
definition as the sender system.
List of systems in your SLD
If you must calculate the SysId at runtime, you do not use an explicit value. Enter the XPath
expression instead. In the XPath expression, you can pick up a value from the payload
generated for example by the predecessor transformation.
An example is /vpf:Msg/vpf:Body/vpf:Payload[./@id=atom2]/@sysid.
Stop processing if fails
With this parameter you can control the behavior of the integration framework, if an exception
occurs during the SQL call. The parameter is read-only.
If you set the value to false, processing continues in case of an exception. This is the default
setting.
This gives you the possibility to introduce your own error handling in the following transformation
atom(s). If you set the value to true, an exception forces the processing of your scenario step to
fail. You can display the message in the message log error section with the complete call stack
of the internal processing. The default error handling of the integration framework is to restart
the scenario step after one minute. The integration framework also allows you to provide your
own error handler as a scenario step inside your scenario package. You can define your own
error handler in the integration framework, selecting ScenariosPackage Design [Definitions]
Error Handling. A prerequisite for this is that you have a scenario step in your scenario
Public
2014 SAP SE or an SAP affiliate company.
All rights reserved

package that is of type queue inbound. In this individual error scenario step, you can define
what you need. You can send an e-mail, a B1 alert, insert a message into a table, and so on.
You can only use explicit values for this parameter. The parameter does not support XPath,
variables and properties.

Method
Select the method how the integration framework identifies the SQL method. The following
options are available:
Automatic detection by key word
The integration framework detects the method by the first statement that you enter in the
Default SQL Statement or in the HANA SQL Statement field.
Query statement
If you want to send a query or queries in your SQL call, select Query statement. The
integration framework sets the Processing Mode to Single Processing and the Blocked
Processing Delimiter to a semicolon. You cannot change the settings.
Update statement
If you want to make an update or updates in the database, select Update statement. The
integration framework sets the Processing Mode to Single Processing and the Blocked
Processing Delimiter to a semicolon. You cannot change the settings.
Processing Mode
Select the method how you want to submit the SQL statements to the database. You have the
following options:
Single Processing
Single processing allows you to submit SQL statements call by call to the database. The
integration framework guaranties the order of SQL statements that it submits to the
database.
Blocked Processing in compatibility mode
This option is available to be compatible with older versions of the SQL Call atom. In older
versions, you have the Blocked Processing checkbox available. If you select the checkbox,
the system has the same behavior when choosing the Blocked Processing in compatibility
mode option.
NOTE
Do not use this mode for new developments.

Blocked Processing in batch mode


With this option, you can group related SQL statements into a batch and submit them in one
call to the database. This option reduces communication overhead and can have a positive
impact on the overall performance.

Blocked Processing Delimiter


Enter the delimiter you use to separate the SQL statements for batch processing. You cannot
use characters that define regular expressions such as <([{\^-=$!|]})?*+.>.
Default SQL Statement
To provide the SQL statement or statements, you have the following options:
Enter the SQL statement or statements for your SQL call directly.
Public
2014 SAP SE or an SAP affiliate company.
All rights reserved

Enter an XPath statement that point to the call.


Enter the name of a transformation atom that contains the SQL statement or statements.
This supports you in processing large SQL statements. For more information, see section 6
of this document

1.1 Recommendations for Special Cases

If values in an XPath statement contain a string that starts with ! (exclamation mark) and
ends with _ (underscore), the integration platform (B1iP) interprets this as a variable and the
SQL statement does not work. In such a case, do not enter the XPath statement but the
transformation atom identifier, where you provide the statement in the <sql> </sql> tag.

If a value in an SQL statement contains a (single quote), for example, 235, the SQL
statement does not interpret this correctly and only considers 23 and the SQL call fails.
Double the single quote to hand over the correct value: 235
If a database contains special characters in tables that are not Latin, but for example
Hebrew, use the N character in the WHERE clause of an SQL statement to include the
special characters.

Example
SELECT T2.E_MAIL as FromEmail FROM OUSR as T2 WHERE
T2.USER_CODE=N'$userid'
To avoid out of memory errors at integration framework runtime, the integration framework in
general reduces SQL statements to 1000 characters in the return payload.

1.2. Filtering Invalid XML Characters from Database Fields


Invalid XML characters in database fields cause exceptions at integration framework runtime.
To avoid such errors, prepare your SQL statement not in the user interface, but in an XSL
transformation atom. In the XSL transformation atom, you can use the
filterInvalXMLChar=true attribute to filter invalid XML characters.

Procedure
1. Create an XSL Transformation atom in from of the Call SQL atom.
2. In the BizStore, in the XSL document, provide the attribute in the following way:
<sql filterInvalXMLChar=true occ="1">select * from table</sql>
3. In the SQL call atom, in the Default SQL Statement field, enter #atom<number> to
reference the XSL transformation atom.
<number> is the number of the XSL transformation atom that contains the SQL statement.

Public
2014 SAP SE or an SAP affiliate company.
All rights reserved

2 Functions
To open documentation, describing the concepts of variables and properties and how to use
them in the context of the process development, click this button.

The integration framework provides context-based documentation. If documentation is available,


the integration framework displays the documentation icon. The greyed out icon indicates still
missing documentation. To open documentation, click the icon.
[Save]
To save the current parameter definitions of the processing atom, click the [Save] button. The
integration framework stores all settings directly in the process flow definition document
(vBIU.bfd). To open the document, click the
icon on the start atom of your flow.
[VarL]
To add, change or delete local variables, click the button. Local variables are only relevant for
the scenario step they are defined in. In the scenario step all atoms can use them. You can
assign fixed literals or an XPath which runs against the incoming message at runtime before the
system calls the process flow. In the process flow the value is fixed and you cannot change it.
You can use local variables in your XSL coding or in the parameter definition for atoms. For
more information, click the
button

[VarG]
To add, change or delete global variables, click the [VarG] button. Global variables are valid for
all scenario steps of a scenario package. In the scenario steps all atoms can use them. You can
assign fixed literals or an XPath which run against the incoming message at runtime before the
system calls the process flow. Inside the process flow the value is fixed and you cannot change
it. You can use the global variables in your XSL coding or in the parameter definition for atoms.
For more information, click the
button
[HANA]
If you want to make the call to a SAP HANA database, click the [HANA] button.
HANA SQL Statement
Enter the SQL statement or statements for the SAP HANA database.
Note that if a HANA SQL statement contains the table field name, and the table field name
contains lower case characters, enclose the table field name in double quotation marks.
Example:
Default SQL Statement: SELECT ItemName FROM OITM WHERE ItemCode=A0001
HANA SQL Statement: SELECT ItemName FROM OITM WHERE ItemCode=A0001
If a database contains special characters in its tables that are not Latin, but for example
Hebrew, use the N character in the WHERE clause of an SQL statement to include the special
characters.
Public
2014 SAP SE or an SAP affiliate company.
All rights reserved

Example
SELECT T2.E_MAIL as FromEmail FROM OUSR as T2 WHERE
T2.USER_CODE=N'$userid'
For more information about SAP HANA, in the internet select http://help.sap.com/hana.

[Close]
To close the user interface of the atom, click the [Close] button.

Public
2014 SAP SE or an SAP affiliate company.
All rights reserved

3 Single Processing
If you select the Single Processing mode, the integration framework separately submits each
SQL statement you have entered in a transaction to the JDBC adapter, which hands them over
call by call to the database. In this case the integration framework guarantees that it hands over
the SQL statements and submits them to the database in the same order as you have entered
them.
You find each call in a separate payload.
Example
SQL statements:
#select * from tbl1 where [key]='1';select * from tblA;select * from
tblB;update tbl1 set F1='X' where [key]='1';update tbl set F1='Y'
where [key]='2'
The fifth statement leads to an error. <Payload

Role="C" id="atom5_5" system="

Result:
<?xml version="1.0" encoding="UTF-8"?>
<Msg>
<Header> ...</Header>
<Body>
...
<Payload Role="C" id="atom5_1" system="0010000108" mode="single" method="Automatic detection
by key word(Automatic detection by key word)" plr="4" dbtype="SQL" blockExecution="false"
compatibilityMode="true" delimiter=";" sql="select * from tbl1 where [key]='1'" disableoutput-escaping="false">
<ResultSet xmlns="urn:com.sap.b1i.adapter:jdbcadapter" rowCount="1">
...
</ResultSet>
</Payload>
<Payload Role="C" id="atom5_2" system="0010000108" mode="single" method="Automatic detection
by key word(Automatic detection by key word)" plr="4" dbtype="SQL" blockExecution="false"
compatibilityMode="true" delimiter=";" sql="select * from tblA" disable-outputescaping="false">
<ResultSet xmlns="urn:com.sap.b1i.adapter:jdbcadapter" rowCount="5">
...
</ResultSet>
</Payload>
<Payload Role="C" id="atom5_3" system="0010000108" mode="single" method="Automatic detection
by key word(Automatic detection by key word)" plr="4" dbtype="SQL" blockExecution="false"
compatibilityMode="true" delimiter=";" sql="select * from tblB" disable-outputescaping="false">
<ResultSet xmlns="urn:com.sap.b1i.adapter:jdbcadapter" rowCount="2">
...
</ResultSet>
</Payload>
<Payload Role="C" id="atom5_4" system="0010000108" mode="single" method="Automatic detection
by key word(Automatic detection by key word)" plr="4" dbtype="SQL" blockExecution="false"
compatibilityMode="true" delimiter=";" sql="update tbl1 set F1='X' where [key]='1'"
disable-output-escaping="false">
<UpdateCount xmlns="urn:com.sap.b1i.adapter:jdbcadapter">1</UpdateCount>
</Payload>
<Payload Role="C" id="atom5_5" system="0010000108" mode="single" method="Automatic detection
by key word(Automatic detection by key word)" plr="4" dbtype="SQL" blockExecution="false"
compatibilityMode="true" delimiter=";" sql="update tbl set F1='Y' where [key]='2'" disableoutput-escaping="false">
<SqlExceptions xmlns="urn:com.sap.b1i.adapter:jdbcadapter">

Public
2014 SAP SE or an SAP affiliate company.
All rights reserved

<SqlException>
<ErrorCode>208</ErrorCode>
<Message>Invalid object name 'tbl'.</Message>
<SqlState>S0002</SqlState>
</SqlException>
</SqlExceptions>
</Payload>
</Body>
</Msg>

The single processing mode is identical with the previous Call SQL atom versions where you
have not selected the Blocked Processing checkbox.

4 Blocked Processing in Compatibility Mode


In previous versions of the SQL Call atom, you have the possibility to select the Blocked
Processing checkbox. Blocked Processing in compatibility mode provides the same system
behavior.
If you define SQL statements containing only select, only update or only delete statements, this
option hands over the statements to the database that processes them in batch mode.
However if you define different statement types, for example select and update statements for
the batch, this does not work.
Additionally, the error handling of the integration framework gives you wrong or incomplete
information about processing. If the database correctly executes the first SQL statement, but
cannot process the following statements, the integration framework always provides information,
that the processing of all SQL statements has been correct.
NOTE
SAP recommends that you no longer use this mode for new developments.

5 Blocked Processing in Batch Mode


The Blocked Processing in Batch Mode makes use of the batch mode that databases provide.
Define the delimiter separating the SQL statements in the Blocked Processing Delimiter field.
The JDBC adapter that handles the SQL call in the integration framework separates all SQL
statements that you enter, writes them to an array, and sends the array to the batch processing
of the database. The batch processing of the database analyses the array and possibly changes
the processing order of SQL statements for internal optimization. Therefore the integration
framework cannot guarantee the in order processing of SQL statements.
Note that Blocked Processing in Batch Mode always comprises one transaction. If any SQL
statement in the batch fails, the transaction completely rolls back.
Public
2014 SAP SE or an SAP affiliate company.
All rights reserved

There are databases that cannot handle read and write operations in one batch. The integration
framework provides the following to overcome this:
If the integration framework finds at least one select statement in the SQL statements you
enter, the integration framework internally switches to single processing mode and hands over
the SQL statements one by one to the database. But even then the processing comprises one
transaction. In this case, the integration framework guarantees the in order processing of SQL
statements.
The result is part of one payload.
Example for Successful Processing
SQL statements:
#select * from tbl1 where [key]='1';select * from tblA;select * from
tblB;update tbl1 set F1='X' where [key]='1';update tbl 1set F1='Y'
where [key]='2'
Result:
<?xml version="1.0" encoding="UTF-8"?>
<Msg>
<Header> ...</Header>
<Body>
...
<Payload Role="C" id="atom5" system="0010000108" mode="blocked" plr="1"
dbtype="SQL" blockExecution="true" compatibilityMode="false"
delimiter=";" sql="select * from tbl1 where [key]='1';select * from
tblA;select * from tblB;update tbl1 set F1='X' where [key]='1';update
tbl1 set F1='Y' where [key]='2'" disable-output-escaping="false">
<ResultSets xmlns="urn:com.sap.b1i.adapter:jdbcadapter">
<ResultSet rowCount="1">
...
</ResultSet>
<ResultSet rowCount="5">
...
</ResultSet>
<ResultSet rowCount="2">
...
</ResultSet>
<UpdateCount>1</UpdateCount>
<UpdateCount>1</UpdateCount>
</ResultSets>
</Payload>
</Body>
</Msg>

Example for an Exception


SQL statements:
#select * from tbl1 where [key]='1';select * from tblA;select * from
tblB;update tbl1 set F1='X' where [key]='1';update tbl set F1='Y'
where [key]='2'
Result:
Public
2014 SAP SE or an SAP affiliate company.
All rights reserved

10

The integration framework does not process any of the SQL statements. It raises an error and
hands over error handling.
The error message displays the sql error:
com.sap.b1i.bizprocessor.BizProcException: BPE001 Nested exception:
com.sap.b1i.xcellerator.XcelleratorException: XCE001 Nested exception:
com.sap.b1i.xcellerator.XcelleratorException: XCE001 Nested exception:
com.sap.b1i.xcellerator.XcelleratorException: XCE001 Nested exception:
com.microsoft.sqlserver.jdbc.SQLServerException: Invalid object name
'tbl'.

Public
2014 SAP SE or an SAP affiliate company.
All rights reserved

11

6 Optimizing the SQL Call for Large SQL Statements


In the Default SQL Statement field, you directly enter your SQL statement or statements, or you
enter an XPath that points to the SQL statement. Alternatively, you can enter the name of a
transformation atom containing the SQL call information in the Default SQL Statement field.
Enter the information in the following way: #atom<number of atom>. Enter, for example,
#atom2
NOTE
This proceeding especially makes sense, if you handle large SQL statements that can
cause memory problems at runtime, for example, a stack overflow.
In the transformation atom, provide an <sql> tag and place your SQL statement or statements
inside the tag.
You can use the following attributes in the <sql> tag:
removeinbound
In the removeinbound attribute, provide the transformation atom name that contains the
SQL statement or statements definition. At runtime, the integration framework removes the
SQL statement from the payload tag of the predecessor transformation atom. Instead, it
includes the following information: removed by sqlcall
occ
In the occ (occurrence) attribute, provide how many semicolons you use in your SQL
statements definition. If you have, for example, one SQL statement, occ=0.
This way, the integration framework does not have need to calculate the number of SQL
statements at runtime. This improves the performance.
result
Using this attribute does not improve the performance. Use it, if database fields contain
invalid characters according to the XML specification. It is the default that the integration
framework uses database table field names as tags to create the result structure of the SQL
call. If the field names contain invalid characters according to the XML specification, such as
#, for example, this leads to an error at runtime. Use the result attribute to avoid such a
situation.
Example for default processing
<ResultSet xmlns=urn:com:sap:b1i:adapter:jdbcadapter rowCount=3>
<Row>
<MenueId>01</MenueId>
<Text>This is a text</Text>
</Row>
<Row>
<MenueId>02</MenueId>
<Text>This is also a text</Text>
</Row>
.
.
.
Public
2014 SAP SE or an SAP affiliate company.
All rights reserved

12

Set result=Field
<ResultSet
<Row>
<Field
<Field
</Row>
<Row>
<Field
<Field
</Row>
.
.
.

xmlns=urn:com:sap:b1i:adapter:jdbcadapter rowCount=3>
label=MenuId name=MenuID>01</Field>
label=Text name=Text>This is a text</Field>
label=MenuId name=MenuID>02</Field>
label=Text name=Text>This is also a text</Field>

7 Preventing SQL Injection


SQL injection is a technique that exploits a potential security vulnerability occurring in the
scenario layer of your integration scenario. Whereas the integration framework takes care in all
cases when the framework generates SQL statements, you have to explicitly prevent SQL
injection in case you generate an SQL statement based on incoming data.
If you use the B1i SQL option, you can ignore this section.
You generate the SQL statement during the processing flow using a transformation atom. Inside
you render the SQL statement by fixed text and values, picked up by XPath statements from the
processed integration framework message. As one part of the integration framework message is
the inbound message handed over by an external caller, an intruder can use this channel to
handover injected data instead of a normal value.

To discuss this topic, we need to differentiate between a string value and a numeric value. Let
us take a look at the following example:

Expected Use Case A Correct User is Calling


<!-- Inbound message -->
<inbounddata>
<keyvalue1>mystring</keyvalue1>
<keyvalue2>4711</keyvalue2>
</inbounddata>
<!-- SQL statement generation -->
<xsl:variable name="strgValue" select="/inbounddata/keyvalue1"/>
<xsl:variable name="numValue" select="/inbounddata/keyvalue2"/>
Public
2014 SAP SE or an SAP affiliate company.
All rights reserved

13

<DBout type="sql">
<sql>select field1 from TBL1 where strgkey ='<xsl:value-of select="$strgValue"/>'</sql>
<sql>select field2 from TBL2 where numkey =<xsl:value-of select="$numValue"/></sql>
</DBout>
<!-- Result to be processed against the database -->
<DBout type="sql">
<sql>select field1 from TBL1 where key ='mystring'</sql>
<sql>select field2 from TBL2 where key =4711</sql>
</DBout>

Intrusion Use Case An Intruder is Calling with the Intention to Destroy the ERP System
<!-- Inbound message -->
<inbounddata>
<keyvalue1>X;drop table USERS--</keyvalue1>
<keyvalue2>5;drop table ITEMS</keyvalue2>
</inbounddata>
<!-- SQL statement generation -->
<xsl:variable name="strgValue" select="/inbounddata/keyvalue1"/>
<xsl:variable name="numValue" select="/inbounddata/keyvalue2"/>
<DBout type="sql">
<sql>select field1 from TBL1 where strgkey ='<xsl:value-of select="$strgValue"/>'</sql>
<sql>select field2 from TBL2 where numkey =<xsl:value-of select="$numValue"/></sql>
</DBout>
<!-- Result to be processed against the database -->
<DBout type="sql">
<sql>select field1 from TBL1 where key =' X;drop table USERS--'</sql>
<sql>select field2 from TBL2 where key =5;drop table ITEMS</sql>
</DBout>

Intrusion Use Case An Intruder Succeeds


<!-- Inbound message -->
<inbounddata>
<keyvalue1>X;drop table TAB3--</keyvalue1>
<keyvalue2>5;drop table TAB4</keyvalue2>
</inbounddata>
<!-- SQL statement generation -->
<xsl:variable name="strgValue" select="utils2:handleSQLString(string(/inbounddata/keyvalue1))"/>
<xsl:variable name="numValue" select="utils2:handleSQLNumber(string(/inbounddata/keyvalue2))"/>
<DBout type="sql">
<sql>select field1 from TBL1 where strgkey ='<xsl:value-of select="$strgValue"/>'</sql>
<sql>select field2 from TBL2 where numkey =<xsl:value-of select="$numValue"/></sql>
</DBout>
<!-- Result to be processed against the database -->
Public
2014 SAP SE or an SAP affiliate company.
All rights reserved

14

<DBout type="sql">
<sql>select field1 from TBL1 where key =' X;drop table TAB3--'</sql>
<sql>select field2 from TBL2 where key =NaN</sql>
</DBout>

To prevent intrusion from outside, the integration framework provides you with two functions to
wrap the variable, or value before inserting it into the SQL string.
The function utils2:handleSQLString(string()) duplicates the character. This
guarantees that the system does not process the drop statement but inserts it as string value
into the database field. An additional positive effect is that this allows you to handle normal
strings containing a character.
The function utils2:handleSQLNumber(string()) type-casts the incoming value explicitly
to a number. In case of an intrusion the result is a NaN which leads to an SQL syntax error.

CAUTION
We strongly recommend using the above functions. We strongly recommend replacing
only values by outside data. Do never design the scenario to accept complete SQL
statements or parts of SQL statements from outside. You cannot control such a
situation.

Public
2014 SAP SE or an SAP affiliate company.
All rights reserved

15

Copyrights, Trademarks, and Disclaimers


Copyright 2014 SAP SE. 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.

Public
2014 SAP SE or an SAP affiliate company.
All rights reserved

16