ui.sql

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

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

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 where 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]/*.


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


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.


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 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: select * from table

3. In the SQL call atom, in the Default SQL Statement field, enter #atom to

reference the XSL transformation atom.

is the number of the XSL transformation atom that contains the SQL statement.


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.


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.


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.


208

Invalid object name 'tbl'.

S0002

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.


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:

...

...

...

...

...

1

1

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:


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.microsoft.sqlserver.jdbc.SQLServerException: Invalid object name

'tbl'.


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. 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 tag and place your SQL statement or statements

inside the tag.

You can use the following attributes in the 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

01

This is a text

02

This is also a text

.

.

.


Set result=Field

01

This is a text

02

This is also a text

.

.

.

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

mystring 4711


select field1 from TBL1 where strgkey ='' select field2 from TBL2 where numkey =

select field1 from TBL1 where key ='mystring' select field2 from TBL2 where key =4711

Intrusion Use Case An Intruder is Calling with the Intention to Destroy the ERP System

X;drop table USERS-- 5;drop table ITEMS select field1 from TBL1 where strgkey ='' select field2 from TBL2 where numkey =

select field1 from TBL1 where key =' X;drop table USERS--' select field2 from TBL2 where key =5;drop table ITEMS

Intrusion Use Case An Intruder Succeeds

X;drop table TAB3-- 5;drop table TAB4

select field1 from TBL1 where strgkey ='' select field2 from TBL2 where numkey =


select field1 from TBL1 where key =' X;drop table TAB3--' select field2 from TBL2 where key =NaN

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.


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.

ui.sql

Documents

sql atom

predecessor atom

atom identifier

convention atom

functional atom

atom creation

sql calls

sql injection