lae sap integration nodes: getting started - · pdf filelae sap integration nodes getting...

LAE SAP Integration Nodes Getting Started

LAE SAP Integration Nodes:

Getting Started

Date: September 18, 2013

Issue: 1.0


Copyright © THE CONTENTS OF THIS DOCUMENT ARE THE COPYRIGHT OF LAVASTORM

ANALYTICS LIMITED. ALL RIGHTS RESERVED. THIS DOCUMENT OR PARTS THEREOF

MAY NOT BE REPRODUCED IN ANY FORM WITHOUT THE WRITTEN PERMISSION OF

MDS.

Disclaimer No representation, warranty or understanding is made or given by this document or the information

contained within it and no representation is made that the information contained in this document is

complete, up to date or accurate. In no event shall Lavastorm be liable for incidental or

consequential damages in connection with, or arising from its use, whether LAVASTORM

ANALYTICS was made aware of the probability of such loss arising or not.


Table of Contents 1. Introduction ............................................................................................................................. 4

2. Requirements .......................................................................................................................... 4

3. Glossary .................................................................................................................................. 4

4. SAP Nodes Overview ............................................................................................................. 6

5. Common Connectivity Parameters ......................................................................................... 6

6. Working with SAP Remote Functions .................................................................................... 8

6.1. Extract ERP Metadata ...................................................................................................... 8

6.1.1. General Usage ........................................................................................................... 8

6.1.2. Standard Configuration ............................................................................................. 8

6.1.3. Error Handling .......................................................................................................... 9

6.1.4. Advanced Configuration ......................................................................................... 10

6.1.5. Inputs....................................................................................................................... 10

6.1.6. Outputs .................................................................................................................... 10

6.1.7. Limitations .............................................................................................................. 12

6.1.8. Examples ................................................................................................................. 12

6.2. ERP Connector ............................................................................................................... 16

6.2.1. General Usage ......................................................................................................... 16

6.2.2. Standard Configuration ........................................................................................... 16

6.2.3. Error Handling ........................................................................................................ 18

6.2.4. Advanced Configuration ......................................................................................... 19

6.2.5. Inputs....................................................................................................................... 19

6.2.6. Outputs .................................................................................................................... 20

6.2.7. Limitations .............................................................................................................. 20

6.2.8. Examples ................................................................................................................. 20


1. Introduction The SAP integration nodes allow for LAE graphs to integrate with a SAP system in order to execute functions on the SAP system. This is done using the SAP Java Connector library (JCo), and allows the user to configure nodes to create, read, update and extract data from an SAP system via remote function calls (RFC's).

2. Requirements Use of these nodes assumes a working knowledge of the Lavastorm Analytics Engine and of SAP BAPI functionality. The following software components are required:

A working LAE installation

LAL 2.13 or greater

A sapjco3.jar Java library, available to users of SAP

A sapjco3.dll Windows library, available to users of SAP

A working connection to a SAP instance, either via direct connection or via the SAPRouter application

An ERP Node Pack License The sapjco3.jar and sapjco3.dll files can be obtained from the SAP Service Marketplace for users of SAP. This can be found at http://service.sap.com/connectors. You will need to login to the SAP Service Marketplace to access the download. If necessary, select the Tools and Services page to display the download page. The library requires the 32bit Windows installation for SAP JCo 3.0.x.

3. Glossary Term Acronym Explanation

SAP SAP Technically refers to the company SAP (Systeme, Anwendungen und Produkte in der Datenverarbeitung – or Systems, Applications and Produtcs in Data Processing). In this document is used interchagably with the main product provided by SAP – the ERP system – e.g. "Extracting data from SPA" implies extracting data from the SAP ERP system, not trying to extract data from the company.

Enterprise Resource Planning

ERP A system integrating internal and external management information across an entire organization.

Business Application Programming Interface

BAPI A standardized programming interface that facilitates external access to business processes and data in the SAP System.

BAPIs offer an object-oriented view of business components in the SAP system. They are implemented and stored as RFC-enabled function modules (RFMs) in the Function Builder of the ABAP Workbench.

http://service.sap.com/connectors


Remote Enabled Function Module

RFM A function module that is enabled for execution via a remote function call (RFC). BAPIs are examples of RFM's. Also referred to as "RFC Enabled Function Modules" in some cases.

Remote Function Call RFC The call or remote execution of a Remote Function Module in an external system. In the SAP system, these functions are provided by the RFC interface system. The RFC interface system enables function calls between two SAP systems, or between a SAP system and an external system. Some function calls operate on function modules (RFMs) and some of these use the Business Application Programming Interface (BAPI)

SAP Java Connector JCO A middleware component that enables Java to access R/3 based systems and vice versa. This means that JCO as well serves as a client to call R/3 Remote Function Calls (BAPIs, Function Modules that can be called from outside) and in addition to that it offers the possibility to work as a Server that receives calls from R/3. R/3 is a file format for transferring workflow information from an SAP System to a SAPforms form, and vice versa.

SAP Enterprise Resource Planning

SAP ERP THE ERP software produced by SAP. It is an enterprise-wide information system designed to coordinate all the resources, information, and activities needed to complete business processes. In this document is often simply referred to as "SAP".

SAP Realtime 3-Tier Architecture

SAP R/3 The former name of the enterprise resource planning software, now known as SAP ERP, product from SAP.

Import Parameter N/A Parameter (Structure, Scalar or Table) that is provided to an SAP RFC in order to execute it. These can be used for various purposes such as to restrict the data retrieved from SAP, or specify values that are to be stored in a creation call.

Export Parameters N/A Parameter (Structure, Scalar or Table) that is returned from SAP. For instance when extracting tables, this will generally be returned in a table export parameter.

Scalar Parameter N/A A scalar parameter is a single field name/field value combination provided to or returned from a remote function call (RFC). Scalar parameters can be import parameters or export parameters.

Structure Parameter N/A Structure parameters are a group of field name/field value combinations provided to or returned from a remote function call (RFC). These can be effectively considered equivalent to a single row of a table parameter. Structure parameters can be import parameters or export parameters.

Table Parameter N/A Table parameters are tables that are passed to or returned from a remote function call (RFC). While structure and scalar


parameters are explicitly marked as Import Parameters or Export Parameters, only the function documentation (i.e. source code) informs as to whether a table parameter is to be interpreted as an import parameter, an export parameter or both. When an RFM is defined as a BAPI, a table parameter can be marked as to whether it is import only, export only or both, however there is no restriction in the interface to ensure that this information is followed in the implementation. Table parameters are generally export parameters however there is no rule around this.

4. SAP Nodes Overview Two SAP integration nodes are provided within the Lavastorm Analytics Library:

Extract ERP Metadata o Queries the SAP system in order to extract the metadata information (i.e. the interface)

for RFM's. o Can be queried via wildcard pattern matching or looking for an exact function name o When using wildcard pattern matching, it currently will only find BAPI's. o Can be configured to return the full interface (all scalar, structure and table parameters)

or simply return the function names – useful when doing a wildcard search to first find the name of the function that you are interested in.

o Generally used to locate information on functions to be executed using the ERP Connector node

ERP Connector o Executes a remote function call on the SAP system. o Depending on the function executed, this could be a BAPI, an RFM that is not a BAPI, or

another RFC that does not interact with a RFM. o Import parameters provided via configuring input pins and/or node parameters o Output pins must be configured in order to retrieve the export parameters

5. Common Connectivity Parameters The integration nodes require a connection to the SAP system, they share a set of common connectivity parameters. Rather than setting these parameters on each node, it is simpler to create a set of corresponding Graph/Run parameters that can be used to provide these parameter values to each of the SAP nodes which requires them. The connectivity parameters that are common to all nodes are the following:

Parameter Name Parameter

Type Required

Allowable Options

Default Description

ApplicationServer string Yes N/A NONE Name of the SAP Application server.

SystemNumber string Yes N/A NONE Two-digit system number of the


SAP system

ClientNumber string Yes N/A NONE Three-digit client number for the client connection to be made. In the SAP landscape, a client is an entity with independent information and data. The SAP client concept is based on the fact that an application service provider (ASP) must provide and administer all resources at a minimal cost, which is quite challenging in a multiple customer-client environment.

RouterString string No N/A NONE If connecting via an SAP Router, specifies the SAP router string through which the connection is made.

Requires the format:

/H/<IP address of SAP Router/S/<port of the SAP Router>/H/<SAP server host ip address/H/

User string Yes N/A NONE SAP username to connect with

Password password Yes N/A NONE Password for the specified SAP user on the SAP system

ConnectionMethod choice No Direct Connection

Pooled Connection

Direct Connection

Method used to connect to the SAP system. A "Direct Connection" implies that the connection will be held for the duration of the node run. A "Pooled Connection" implies that the connection while be taken and returned as neeed during node execution.

PoolCapacity string No Must be an integer if specified

3 Integer value specifying the pool capacity for the SAP system when using pooled connections.

See: http://docs.oracle.com/cd/E14571_01/doc.1111/e17656/jco_updates.htm

PeakLimit string No Must be an integer if specified

10 Integer value specifying the peak limit when using pooled


connections to the SAP system.

See: http://docs.oracle.com/cd/E14571_01/doc.1111/e17656/jco_updates.htm

6. Working with SAP Remote Functions The preferred mechanism for integrating with an SAP system is to use the Extract ERP Metadata and ERP Connector nodes to execute remote functions. This section outlines the interface, usage and limitations of these nodes.

6.1. Extract ERP Metadata The Extract ERP Metadata node queries the SAP system in order to extract the metadata information (i.e. the interface) for RFM's.

6.1.1. General Usage There are two main use cases for the Extract ERP Metadata node:

1. Locate all functions on the SAP system, or given a wildcard, attempt to locate a specific

function on the system 2. Given a specific function, retrieve the metadata (interface) for that function

While it is possible to get the metadata for multiple functions at once, this is not the most common use case. Doing so can lead to the node taking a long time to complete as each retrieving the metadata requires a separate call for each function.

6.1.2. Standard Configuration In most circumstances, provided the connection information (see section ) has been set, only the parameters on the "General" tab need to be populated. The following parameters are defined on the "General" tab:


Type Required

Allowable Options

Default Description

FunctionName string No N/A NONE Name of the function who's metadata is to be retrieved. If no function name is entered, will search all functions on the system. Wildcard characters can be used within the function name to search for a function matching a specific regex or glob pattern (provided the


corresponding value is set in the FunctionMatchMethod parameter).

FunctionMatchMethod string No Exact

Regular Expression

Glob Pattern

Exact Specifies how to match the specified FunctionName to locate the corresponding function(s) on the SAP system. If no function name is provided, will search for all functions. Otherwise, will search using one of these options

Case Sensitive boolean No N/A True Specifies whether to search for the functions case-sensitively on the SAP system.

FunctionNamesOnly boolean No N/A False Specifies whether all the metadata should be retrieved for the matching functions, or simply the function names and their descriptions.

6.1.3. Error Handling In certain circumstances if the node is erroring, it can be useful to specify the "RecoverableErrorBehavior" such that unnecessary warnings are not written to the log to obfuscate the true cause of the problem


Type Required

Allowable Options

Default Description

RecoverableErrorBehavior

choice No Error

Log Ignore

Log In some circumstances, a call to an SAP function can complete sucessfully, however the function will be returned with an exception list.

This generally implies that processing can continue but htat there were some errors.

In the case of running non-BAPI RFM's, these errors will always be returned.

This parameter specifies the action to take when such errors occur.


6.1.4. Advanced Configuration There is no advanced configuration required for this node.

6.1.5. Inputs The node does not take any inputs.

6.1.6. Outputs

6.1.6.1. Functions The "Functions" output of the node contains all of the functions on the system which matched the specified FunctionName. The "Functions" output contains the following fields:

Field Name Description

Function Name Name of the function

Description Description of the function

Method Function method

Method Name Element name in upper/lower case

Object name Name of the object

Object type Type of the object

Short text Additional short description of the function

6.1.6.2. Scalar Parameters In order to execute the function, the user needs to know which scalar parameters are to be imported to SAP and which will be exported. The "Scalar Parameters" output identifies all of the scalar parameters, their corresponding types and whether or not they are import or export parameters. These can then be provided to the ERP Connector node (via an input pin or via the "Scalar Parameters" node parameter). The output has the following fields:


Function Name Name of the function in which the scalar parameter is defined

Param Direction Import or Export, specifying whether the parameter is to be provided from the LAE node to the SAP function call, or will be returned from the SAP function call.

Param Name Name of the scalar parameter

SAP Param Type Type of the parameter in the ERP system

LAE Field Type Type of the LAE field which should be used if the parameter is to be provided in an input pin, or which will be provided in an output pin. Will be set to "Unmappable" if the parameter type cannot be


mapped to an LAE type

Description Description of the scalar parameter (if available)

Required For import parameters, specifies whether or not this is required. Set to NULL for export parameters.

6.1.6.3. Structure Parameters In order to execute the function, the user needs to know which structure parameters are to be imported to SAP and which will be exported. The "Structure Parameters" output identifies all of the structure parameters, their corresponding types and whether or not they are import or export parameters. These can then be provided to the ERP Connector node (via an input pin or via the "Structure Parameters" node parameter). The output has the following fields:


Function Name Name of the function in which the structure parameter is defined

Structure Name Name of the structure parameter

Param Direction Import or Export, specifying whether the parameter is to be provided from the LAE node to the SAP function call, or will be returned from the SAP function call.

Param Name Name of the parameter within the structure

SAP Param Type Type of the parameter in the ERP system

LAE Field Type Type of the LAE field which should be used if the parameter is to be provided in an input pin, or which will be provided in an output pin. Will be set to "Unmappable" if the parameter type cannot be mapped to an LAE type

Description Description of the parameter within the structure (if available)

Required For structure import parameters, specifies whether or not this structure is required. Set to NULL for export structures.

6.1.6.4. Tables In order to execute the function, the user needs to know which table parameters are to be imported and/or exported from SAP. The "Tables" output identifies all of the table parameters, their corresponding types, and how they should be input to or output from SAP. Note that since the function interfaces provide no information as to whether table parameters are import or export, the node is unable to provide this information. The output has the following fields:



Function Name Name of the function in which the structure parameter is defined

Table Name Name of the table parameter

Field Name Name of the field within the table

SAP Field Type Type of the field in the ERP system

LAE Input Field Type Type of the LAE field which should be used in an input pin.

LAE Output Field Type Type of the LAE field which should be used if the parameter is to be provided in an input pin, or which will be provided in an output pin. Will be set to "Unmappable" if the parameter type cannot be mapped to an LAE type

Description Description of the field (if available)

6.1.7. Limitations The Extract ERP Metadata node has the limitation that when searching for a function (rather than when retrieving the details of a function using a specified function and "Exact" function name matching) it currently will only find BAPI's rather than all RFMs/RFCs defined on the system. In addition, the Extract ERP Metadata node is limited in that it can not determine whether a table parameter is defined as an import export parameter – as this information is not available on the interface.

6.1.8. Examples The two most common use cases for the Extract ERP Metadata node is to search for the names of functions matching a specified pattern, or to extract all of the metadata for a specific function. The following two examples show how these operations can be performed.

6.1.8.1. Searching for a function In order to search for a function that matches a specific pattern, simply set the parameters:

FunctionName o Set to the pattern you want to match

FunctionMatchMethod o Set to Regular Expression or Glob Pattern, depending on how you are

searching

CaseSensitive o If you want to match case-insensitively, set this to false

FunctionNamesOnly o Set this to true, to ensure that only the function names, and not all interface

information is returned for all matched functions.

As an example, consider that you want to find all of the BAPI functions which are to do with handling bank details. If you know that the functions you care about all contain the string "_BANK_", but aren't sure of the function names, and aren't sure whether this "_BANK_" string needs to be uppercase, you could configure the node as shown below:


Figure 1 Searching for all bank related funcitons

In this example, the "FunctionName" has been set to the glob-pattern "*_BANK_*", and a case-insensitive, glob pattern match is performed. Since only function names are to be returned, the "Scalar Parameters", "Structure Parameters" and "Tables" outputs will have no records. On the "Functions" output, however, you see that all of the functions that match this pattern are output: Figure 2 Result of searching for all bank related functions


6.1.8.2. Extracting Metadata for a Specific RFM In order to extract the metadata for a specific function, you can simply set the parameters:

FunctionName o Set to the exact name of the function you want to match

FunctionMatchMethod o Set to Exact (or leave empty, as "Exact" is the default)

CaseSensitive o Set to true (or leave empty, as "true" is the default)

FunctionNamesOnly o Set this to false (or leave empty, as "false" is the default), to ensure that all

interface information is returned for the function. From the example above, we have now located all of the functions that deal with "_BANK_" information. If we now wanted to execute the "BAPI_BANK_GETLIST" function, we would first need to extract the metadata information, or the interface for this BAPI. In order to do this, we would simply set the "FunctionName" parameter to "BAPI_BANK_GETLIST" as shown below and run the node. Figure 3 Extracting the interface for BAPI_BANK_GETLIST

Since in this case, we have extracted all of the fuction interface information and not the function name only, you will see that all of the outputs have records.


The "Functions" output will simply contain a single record matching the function who's metadata we have extracted – the same record that was part of the "Functions" output displayed in the previous example. Investigating the "Scalar Parameters" output shows that there are two import scalar parameters (i.e. parameters that need to be provided when executing the function), a string/Unicode field "BANK_CTRY", and an integer field "MAX_ROWS". Figure 4 "Scalar Parameters" for BAPI_BANK_GETLIST

Investigating the "Structure Parameters" output shows that there is just one structure export parameter "RETURN". "RETURN" is the standard export structure used by BAPI's to return error information. The records returned on the "Structure Parameters" output are shown below: Figure 5 : Structure parameters for BAPI_BANK_GETLIST

The "Tables" output shows that the BAPI_BANK_GETLIST defines just one table "BANK_LIST". While the interface does not define whether a table parameter is an export or import parameter, since the function is a "GETLIST" function, and since the only table defined is a "BANK_LIST" it is reasonable to assume that this is an export parameter. The records returned on the "Tables" output are shown below:


Figure 6 Tables for BAPI_BANK_GETLIST

As will be shown in the next section, once this interface information is extracted it can be used to configure the ERP Connector node to execute a function.

6.2. ERP Connector The ERP Connector node executes a remote function call on the SAP system. SAP Import parameters are provided either via entering the values in the "Structure Parameters" or "Scalar Parameters" node parameters in the node editor, or via node inputs. If the function returns data that is to be available after execution of the node, the appropriate outputs must be constructed on the node.

6.2.1. General Usage Depending on the purpose of the function, the general usage of the node is to create, read, update or delete data from the SAP system for a specific object. In general, if this is the first time you have executed the function, you will normally first need to run the Extract ERP Metadata node in order to determine the function interface prior to configuring the node to execute the desired function. As the node provides a generic mechanism to execute any function on the SAP system, if the same function is to be used regularly, it may be worthwhile constructing a pre-configured version of the node such that the inputs/outputs required by the node are configured correctly, and such that parameters to the function can be named parameters in the LAE node and provided in a "normal" LAE manner rather than requiring the user of the node to know which "Scalar Parameters" and "Structure Parameters" are required by the function.

6.2.2. Standard Configuration Since the node is very generic and can be used to call any remote function, the configuration that is to be provided to this node is very much function specific. However, the following general rules apply:

1. First, determine the interface of the function using the Extract ERP Metadata node discussed in the previous section

2. Set the name of the function to execute in the "FunctionName" parameter 3. If the function requires any scalar import parameters, either

a. Set these in the "ScalarParameters" parameter on the node in the format: <ParamName>=<ParameterValue>


The node help outlines how these parameter values must be formatted depending on the type of parameter being provided Or

b. Provide these parameters via an input i. Create an input "Scalar Parameters". ii. For each scalar parameter, the input needs to have a field, where the

field name equals the name of the parameter iii. The parameter value must be provided as the field value for the

corresponding field in the input iv. The type of the field must match the specified "LAE Field Type" specified

in the interface, which can be seen on the corresponding record of the "Scalar Parameters" output on the Extract ERP Metadata node.

v. There must only be one input record 4. If the function requires any structure import parameters, either

a. Set these in the "StructureParameters" parameter on the node in the format: <StructureName>.<ParamName>=<ParameterValue> The node help outlines how these parameter values must be formatted depending on the type of parameter being provided Or

b. Provide these parameters via inputs to the node. Each structure import parameter provided must have its own input. For each structure:

i. Create an input "Structure Parameters_<StructureName>". ii. For each parameter in the structure, the input needs to have a field,

where the field name equals the name of the parameter iii. The parameter value must be provided as the field value for the

corresponding field in the input iv. The type of the field must match the specified "LAE Field Type" specified

in the interface, which can be seen on the corresponding record of the "Structure Parameters" output on the Extract ERP Metadata node.

v. There must only be one input record 5. If the function requires any table import parameters

a. Provide these parameters via inputs to the node. Each table import parameter provided must have its own input. For each structure:

i. Create an input "<TableName>". ii. For each field in the table, the input needs to have a field, where the

field name equals the name of the field in the table import parameter iii. The field value must be provided as the field value for the

corresponding field in the input iv. The type of the field must match the specified "LAE Input Field Type "

specified in the interface, which can be seen on the corresponding record of the "Tables" output on the Extract ERP Metadata node.

b. There can be any number of records for a Table import parameter 6. If the function defines any scalar export parameters that you want to extract, construct

an output "Scalar Parameters". All scalar parameters will be written to this output 7. If the function defines any structure export parameters that you want to extract,

construct corresponding outputs on the node. For each of the structures to extract, create an output on the node "Structure Parameters_<StructureName>". The parameters for that structure will be written to this output.


A special case is the "RETURN" structure. All BAPIs will define a structure export parmeter "RETURN" which will contain information returned from the BAPI related to the success or otherwise of the function. Since BAPIs follow a general approach of returning exceptions via the RETURN structure rather than throwing the exceptions directly, it is good practise whenever executing a BAPI to create the corresponding "Structure Parameters_RETURN" output.

8. If the function defines any table export parameters that you want to extract, construct corresponding outputs on the node "<TableName>". The corresponding exported table will be written to this output.

9. If the function you are executing is a BAPI function that is going to modify the SAP system (i.e. a creation, update or deletion function), then you need to set the CommitTransaction parameter to true in order for the operation to take effect in the system.

6.2.3. Error Handling The ERP Connector node has the following parameters specifically designed to deal with error scenarios:


Type Required

Allowable Options

Default Description

CoerceInputData boolean No N/A false Specifies whether not not input LAE data should attempt to be coerced to SAP data types, when the mapping is not the preferred choice. (e.g. LAE boolean->SAP character. If coerce is used, this could export true as 'T').

UnmappableInputBehavior

choice No Error

Log

Ignore

Error Action to take when LAE input data cannot be coerced to an SAP data format.

This can occur either because there is no valid coercion method, or because coerce is set to false.

UnmappableOutputBehavior

choice No Error

Log

Ignore

Error Action to take when SAP data cannot be mapped to an LAE data type (e.g. ABAPObject types)

RecoverableErrorBehavior

choice No Error

Log Ignore

Log In some circumstances, a call to an SAP function can complete sucessfully, however the function will be returned with an exception list.

This generally implies that


processing can continue but htat there were some errors.

In the case of running non-BAPI RFM's, these errors will always be returned.

This parameter specifies the action to take when such errors occur.

6.2.4. Advanced Configuration For performance reasons, it is sometimes desirable to deactivate certain export parameters. If the export parameters are deactivated, they will not be returned through the SAP Jco interface and the function call can take significantly less time. In order to deactivate the parameters this can be done either via the node parameter "DeactivateExportParameters" or can be provided via an input pin. If using the node parameter "DecativateExportParameters", the name of each export parameter to deactivate is specified in its own line in the parameter value. If specifying the export parameters to deactivate via an input pin, construct an input "Deactivate Parameters". The input must contain one string or Unicode field only. The value in this field for each records specifies the name of the export parameter to deactivate.

6.2.5. Inputs By default, the node does not contain any inputs. However, if import parameters are to be specified dynamically, via input data, corresponding inputs need to be created on the node. Similarly, any export parameters to deactivate can be specified in a corresponding input.

6.2.5.1. Scalar Parameters As discussed in section 6.2.2, scalar import parameters can be provided via the "Scalar Parameters" input, or via specifying the parameters in the "ScalarParameters" node parameter. The details and requirements on this input are specified in section 6.2.2.

6.2.5.2. Structure Parameters_<Structure Name> As discussed in section 6.2.2, structure import parameters can be provided via "Structure Parameters_<StructureName>" inputs, or via specifying the parameters in the "StructureParameters" node parameter. The details and requirements on this input are specified in section 6.2.2.

6.2.5.3. <TableName> As discussed in section 6.2.2, all table import parameters must be provided via corresponding "<TableName>" inputs. The details and requirements on this input are specified in section 6.2.2.


6.2.5.4. Deactivate Parameters As discussed in section 6.2.4, deactivation of export parameters can be done via an input pin "Deactivate Parameters" or via specifying the parameters to deactivate in the "DeactivateExportParameters" node parameter. The details and requirements on this input are specified in section 6.2.4.

6.2.6. Outputs By default, the node does not contain any outputs. However, if export parameters are to be extracted, corresponding outputs need to be created on the node.

6.2.6.1. Scalar Parameters As discussed in section 6.2.2, any scalar export parameters to extract will be written to the node output "Scalar Parameters" if one exists on the node. The details and requirements on this output are specified in section 6.2.2. In order to determine which scalar parameters will be written to the output, run the Extract ERP Metadata node for this function and investigate the "Scalar Parameters" output – as discussed in section 6.1.6.2.

6.2.6.2. Structure Parameters_<Structure Name> As discussed in section 6.2.2, any structure export parameters to extract will be written to corresponding node output "Structure Parameters_<StructureName>" if the output exists on the node. The details and requirements on this output are specified in section 6.2.2. In order to determine which parameters will be written to the output and which outputs should be constructed, run the Extract ERP Metadata node for this function and investigate the "Structure Parameters" output – as discussed in section 6.1.6.3.

6.2.6.3. <TableName> As discussed in section 6.2.2, any table export parameters to extract will be written to corresponding node output " <TableName>" if the output exists on the node. The details and requirements on this output are specified in section 6.2.2. In order to determine which fields will be written to the output and which table outputs should be constructed, run the Extract ERP Metadata node for this function and investigate the "Tables" output – as discussed in section 6.1.6.4.

6.2.7. Limitations There are no known limitations to this node.

6.2.8. Examples

6.2.8.1. Create Consider the case where we want to create a new Bank object in the SAP system. First, we need to locate the correct BAPI to execute and its interface. In section 6.1.8.1, we can see that there exists a BAPI on the system called "BAPI_BANK_CREATE". In order to determine the interface, we can therefore run the Extract ERP Metadata node with the configuration shown in the screenshot below.


Figure 7 Extracting the metadata for BAPI_BANK_CREATE

Investigating the "Scalar Parameters" output shows that it defines the following scalar parameters: Figure 8 Scalar Parameters for BAPI_BANK_CREATE

Of these, only the BANK_CTRY parameter is a required import parameter. Therefore, on the ERP Connector node, we can already enter the FunctionName as "BAPI_BANK_CREATE" and in "ScalarParameters", enter the value:

BANK_CTRY=US


As this example was run against a system which was not correctly configured1, a "BANK_KEY" was also required, and provided as: BANK_KEY=0001 We then move onto the "Structure Parameters" output of the Extract ERP Metadata node, which shows the import structures "BANK_ADDRESS" and "BANK_ADDRESS1" along with the export structure "RETURN". Of these, however, only the "BANK_ADDRESS" structure is a required import structure. The details of this import structure are shown below. Figure 9 Required import structure - BANK_ADDRESS

Therefore, we can setup the "StructureParameters" parameter on the node to specify this structure parameters. Further investigation of documentation revealed that not all parameters are required on the structure, therefore only the following were configured in the "StructureParameters" parameter:

BANK_ADDRESS.BANK_NAME=My New Bank BANK_ADDRESS.REGION=MA BANK_ADDRESS.STREET=100 State Street BANK_ADDRESS.CITY=Boston BANK_ADDRESS.SWIFT_CODE=MYNBUS3N

Finally, the "CommitTransaction" parameter was set to true as this is a create operation which requires the transaction to be committed in order for it to take effect. The outputs then need to be configured. The "Scalar Parameters" and "Structure Parameters" output from the Extract ERP Metadata node shows that the node exports a "RETURN" structure and the scalar parameters "BANKCOUNTRY" and "BANKKEY". Therefore, in order to ensure that this return structure, and the scalar parameters are output, the outputs "Scalar Parameters" and "Structure Parameters_RETURN" are constructed on the node.

1 SAP documentation indicates that if the internal number assignment is not defined for the bank country, then the

bank key is required. Since this example was executed on a test system without these internal numer assignment

setup for the countries, providing the bank key was necessary.


This then leads to the configured node shown in the screenshot below. Figure 10 Node configuration for BAPI_CREATE_BANK

After running the node, you will see that it returns the BANKCOUNTRY and BANKKEY on the "Scalar Parameters" output pin shown below.


Figure 11 Scalar Parameters output after running BAPI_BANK_CREATE

Investigation of the Structure Parameters_RETURN shows that the node did not return anything that indicated an error had occurred in executing the BAPI. Figure 12 Structure Parameters_RETURN output after running BAPI_BANK_CREATE

6.2.8.2. Read We now want to check that the bank in the previous example was successfully created. In order to do so, we first run the BAPI_BANK_GETLIST function. As seen in section 6.1.8.2, the BAPI_BANK_GETLIST function requires two scalar import parameters "BANK_CTRY" and "MAX_ROWS". For some reason the API defines these as both required, however some investigation shows that MAX_ROWS is not actually required.

In section 6.1.8.2, we also saw that the BAPI_BANK_GETLIST has an export structure parameter "RETURN" along with an export table "BANK_LIST". Therefore, we construct the node to have the outputs "Structure Parameters_RETURN" "BANK_LIST". Since we want to extract the bank list for the country within which we created the bank in the previous example, we set the "BANK_ CTRY" scalar parameter to "US".

After performing these steps, the configured node appears as shown in the below screenshot. Note that since we are not making a modification to the system (i.e. this is a read operation, not a create, update or delete) we do not need to set the CommitTransaction parameter to true.


Figure 13 Node configured to run BAPI_BANK_GETLIST

After running the node, the "Structure Parameters_RETURN" output shows no errors, and amongst the banks in the "BANK_LIST" output is the bank we created in the previous step – shown below.


Figure 14 Output of the BAPI_BANK_GETLIST function

6.2.8.3. Update Consider te case that we made an error in constructing the bank information in the previous section. In such cases, we may want to use an update function to modify an existing object in the SAP system. When looking at the different BAPI_BANK_* functions (see section 6.1.8.1) you can see that the mechanism to do this would be using the BAPI_BANK_CHANGE function. Most BAPI update functions (those ending in "_CHANGE") take a "value" import structure specifying the new field values, and a "flag" structure which has the format "<valueImportStructureName>X" specifying which fields from the "value" import structure are to be modified. For the BAPI_BANK_CHANGE function, you can see there are the following structures:

BANK_DETAIL, BANK_DETAILX

BANK_ADDRESS, BANK_ADDRESSX

BANK_ADDRESS1, BANK_ADDRESS1X Therefore, if we needed to modify the "STREET" field in the BANK_ADDRESS structure to change from "100 State Street" to "105 State Street", we could populate the two Structure Parameters: BANK_ADDRESS.STREET=105 State Street BANK_ADDRESSX.STREET=X This then tells the BAPI_BANK_CHANGE function to modify the STREET field to the new value.


In order to do this, we configure the node as shown in the screenshot below. Again, note that the CommitTransaction parameter has been set to false, since this function needs to modify data on the SAP system. Figure 15 Node configured for function BAPI_BANK_CHANGE

6.2.8.4. Delete While the other examples investigated so far have dealt with the BAPI_BANK_* set of BAPIs, no corresponding "Delete" BAPI was found on this system. Therefore, in order to test the "Delete" functionality, we'll use the BAPI_USER_DELETE function. In order to see which BAPIs are available for the USER object, first run the Extract ERP Metadata node with the "FunctionName" parameter set to "BAPI_USER_*", using a "FunctionMatchMethod" of "GlobPattern", and "FunctionNamesOnly" set to true. This results in the "Functions" output from the node as shown below.


As shown above, there are numerous BAPI_USER_* functions, including one for deleting users "BAPI_USER_DELETE". We don't want to delete just any user from the SAP system, so we will first create a dummy user that we will later delete. In order to do this, first examine the metadata for the BAPI_USER_CREATE function – again using the Extract ERP Metadata node. Since this is a dummy account, it makes sense to only look at the import parameters that are required. From this, we see that the only required scalar import parameter is a "USERNAME". The required import structures are "ADDRESS", "LOGONDATA", and "PASSWORD". While these structures are required, not all parameters on the structures will be required. Therefore, we'll attempt to create a dummy user with as little information as possible. N order to do this, insert an ERP Connector node with the following configuration:

FunctionName: BAPI_USER_CREATE

ScalarParameters: USERNAME=Dummy

StructureParameters: ADDRESS.PERS_NO=0000010899 ADDRESS.ADDR_NO=0000010900 ADDRESS.TITLE=Mr ADDRESS.FIRSTNAME=Dummy ADDRESS.LASTNAME=User ADDRESS.FULLNAME=Dummy User ADDRESS.NAMCOUNTRY=US ADDRESS.LANGU_P=E ADDRESS.DEPARTMENT=Engineering ADDRESS.FLOOR=5 ADDRESS.CITY=Boston


ADDRESS.DISTRICT=Boston ADDRESS.POSTL_COD1=02210 ADDRESS.STREET=Summer Street ADDRESS.COMM_TYPE=RML ADDRESS.STREET_NO=321 ADDRESS.COUNTRY=US ADDRESS.COUNTRYISO=US ADDRESS.LANGU=E ADDRESS.LANGU_ISO=EN ADDRESS.TIME_ZONE=GMT COMPANY.COMPANY=Dummy Company LOGONDATA.GLTGV=2013-01-01 LOGONDATA.GLTGB=2016-01-01 LOGONDATA.USTYP=A LOGONDATA.CODVN=B LOGONDATA.CODVC=F PASSWORD.BAPIPWD=abcd1234

CommitTransaction: true There are no export parameters that we care about, so no outputs need to be configured. Once the above configuration has been entered, execute the node. In order to verify that the user has been successfully created, use the BAPI_USER_EXISTENCE_CHECK function. This function simply requires a scalar import parameter "USERNAME", and an export structure "RETURN". Therefore, the configuration of the ERP Connector node to execute the function is relatively trivial and is shown below:


If the user has successfully been created, in the output of the "Structure Parameters_RETURN", you will see that the "MESSAGE" field contains the text:

User DUMMY exists

Now that the dummy user exists, it can be deleted. The BAPI_USER_DELETE function is similarly trivial. It requires only one scalar import parameter "USERNAME" – specifying the name of the user who is to be deleted. It has only one exported table "RETURN". Therefore, to delete the user in question, all you need to do is insert an ERP Connector node, with the "Scalar Parameters" set to: USERNAME=Dummy As this is a modification operation, the CommitTransaction parameter should be set to true. An output "RETURN" should also be added to the node. A screenshot of the configured node is shown below.


If the node runs successfully, and the user has been successfully deleted, you will see three records in the "RETURN" output, with the following information in the "MESSAGE" field:

Role assignment to user DUMMY deleted Profile assignment for user DUMMY was deleted User DUMMY deleted

In order to verify that these messages accurately reflect the state of the system, run the BAPI_USER_EXISTENCE_CHECK function again, checking for user "DUMMY". In this case, in the "MESSAGE" field of the "Structure Parameters_RETURN" output, you will see:

User DUMMY does not exist

This indicates that the user has been successfully deleted and no longer exists on the system.

NOTE: While the BAPI_USER_CREATE and BAPI_USER_DELETE functions are modification functions, these do not require the CommitTransaction parameter to be set to true. These functions automatically commit their changes to the SAP system. The general rule for BAPIs is that they do not commit the transaction and a separate call to commit is required.


However these functions were apparently written prior to changes to the general BAPI interface which means that they do not follow these guidelines. It is important to check the definition of functions prior to running them in order to ensure that you do not inadvertently commit changes to the system when you are simply trying to test an interface or function.

6.2.8.5. Parameters from Node Inputs So far, we have been providing all We now want to check that the change we performed on the bank details in the the previous example (BAPI_BANK_CHANGE) was successfully commited. In order to do so, we run the BAPI_BANK_GETDETAIL function. If we run the Extract ERP Metadata node, we'll see that there are two scalar import parameters: BANKCOUNTRY and BANKKEY. The bank created in the previous section had a coutry code of "US" and a key of "0001". Rather than specifying these in the node's "ScalarParameters" parameter, however, this time we'll pass these values into the node in an input pin. In order to do this, create a static data node with these two fields, both of a "string" type, with the values "US" and "0001" as shown in the screenshot below. Figure 16 Configuring Scalar Parameters via node input

Then, create a "Scalar Parameters" input on the ERP Connector node and connect the output of the static data node to the input of the ERP Connector node as shown below.


Figure 17 Connecting to the Scalar Parameters input pin

Set the FunctionName parameter to "BAPI_BANK_GETDETAIL". Since the BAPI defines three export structure parameters "BANK_DETAILS", "BANK_ADDRESS" and "RETURN", construct three corresponding outputs on the node "Structure Parameters_BANK_DETAILS", Structure Parameters_BANK_ADDRESS" and "Structure Parameters_RETURN". The node will then be configured as shown below. Figure 18 BAPI_BANK_GETDETAIL configured with Scalar Parameters on node input

Then run the node. After running the node, you'll see in the "Structure Parameters_BANK_ADDRESS" output, the data shown below, indicating that the update performed in the previous section was performed successfully.


Figure 19 "BANK_DETAIL" output for BAPI_BANK_GETDETAIL

6.2.8.6. Providing Table Inputs Generally, BAPIs do not take table parameters as import parameters. However, in some cases they do, and some RFC's also take import table parameters. In this example, we'll show how to construct a node which takes two table import parameters to execute the function RFC_READ_TABLE. First, run the Extract ERP Metadata node, extracting the metadata for the "RFC_READ_TABLE" function. The scalar parameters defined on the RFC_READ_TABLE function are shown below. Figure 20 Scalar parameters for RFC_READ_TABLE function

Investigation into the function reveals that it will extract all fields from the source table into a single output field. the following information for the scalar import parameters:

DELIMITER o If specified, the returned data will contain a delimiter between each of the

fields in the source table that are extracted to the destination "WA" field. o The fields are extracted as fixed width, however, and no escape character is

used, so use of a delimiter does not necessarily make it easier to reconstruct the original field values

NO_DATA o If set, only the metadata is extracted


QUERY_TABLE o Name of the table to extract

ROWCOUNT o Number of rows to extract

ROWSKIPS o Number of rows to skip prior to extracting the data from the table

There are no structure parameters for the function, however there are three table parameters as shown in the below screenshot. Figure 21 Table parameters for RFC_READ_TABLE function

In this case, further investigation of the function online reveals that while all of these tables can be provided as both import and export parameters, the intended use is that the "OPTIONS" table can be provided as an import table parameter in order to essentially perform the equivalent of a "WHERE" clause of a query. The "FIELDS" table when provided as an import table parameter is used to restrict the fields that are extracted from the table (like the SELECT part of a query). In this case, only the FIELDNAME field is are considered, and the other fields within the "FIELDS" table are ignored. When used as an export table parameter, this will return the information on the fields in the table. The "DATA" table is designed to be used for export only and all of the extracted fields are dumped to the "WA" field in the "DATA" table. Using this information, we can construct a node to simply extract the field metadata from the table "DBCON" as shown below:


Figure 22 RFC_READ_TABLE configured to extract field info only

Once this is done, we can then construct a node which will read the data from that table using the field information returned from this call, shown below. Figure 23 FIELDS returned from RFC_READ_TABLE


First, consider the case where we only want to extract the CON_NAME, DBMS, USER_NAME and MAX_CONNECTIONS fields. Then, we could construct a static data node which specifies each of these to be provided as the table import parameter "FIELDS" as shown below. Figure 24 FIELDS table import parameter definition

Then, say we wanted to only extract data where the "CON_NAME" feld equals "NSP" and the "USER_NAME" field is SAPNSP. We could then construct the OPTIONS table import parameter definition as shown below:


Figure 25 OPTIONS table import parameter to RFC_READ_TABLE

Once this is done, we can create an OPTIONS and a FIELDS input to the ERP Connector node to accept these table import parameters and configure the node with "FIELDS" and "DATA" outputs to extract the field metadata information and the data from the table. This is shown below. Figure 26 Configuring the ERP Connector node with table import parameters "FIELDS" and "OPTIONS"

Then, with the scalar import parameter "QUERY_TABLE" set to "DBCON", and the scalar import parameter "NO_DATA" not set, running the node will yield the "FIELDS" and "DATA" outputs shown below:


Figure 27 FIELDS output for configured RFC_READ_TABLE

Figure 28 DATA output for configured RFC_READ_TABLE

6.2.8.7. Creating a Configured Node for a Specific function In the previous example, we showed how to execute the RFC_READ_TABLE function by providing it with table import parameters for the "OPTIONS" and "FIELDS" tables. The name of the table to extract was also provided in the ERP Connector node. While this specific function already has specific implementations in the "Extract ERP Table Metadata" and "Extract ERP Table" nodes, it is worthwhile investigating this function to see how in general a pre-configured node can be written to handle specific functions and allow an end user to then easily configure such a node without needing to setup the inputs and outputs and static data nodes for each execution.


The general parameters that users should be able to easily configure for this function are specifying which fields are to be extracted (or extracting all by default), specifying the OPTIONS, and specifying the table that is to be extracted. On order to allow users to easily configure such parameters, we construct a composite. The contents of the composite are shown below. Figure 29 Inside the configured "Read Table" composite

First, the "FIELDS" static data node is configured as shown below: Figure 30 The FIELDS static data input


If the user wants to extract all fields, the field list should come from the definition of the field metadata, rather than from the user specified fields. Therefore, this node is set with the "Enabled" parameter on the Logistics tab set to: {{?Fields?}} Which means that the node wil be disabled if the user does not specify a "Fields" parameter on the composite. If enabled, this node will simply output the user defined fields in a comma separated list. Each of these fields need to be output on a different record. Therefore, the "Expand From List" node is used to split this list into different records. The configuration of this node is shown below. Figure 31 Splitting the user-defined field list into different records

The output of this node will then contain a field "FieldName" with a different record per field. This node is also configured with the Enabled parameter set to {{?Fields?}} as in the previous static data node. In order to ensure the correct fields are extracted, a lookup is performed with the output of the ERP Connector node designed to extract the field metadata only from RFC_READ_TABLE against the output of this user-specified field list. Again, the lookup is configured with the same Enabled parameter as per the Expand From List node and the Static Data node. The lookup is configured to only output cases where the user specified field exists in the field metadata for the table as shown below:


Figure 32 Configuration of the field lookup node

The output of this node is then connected to the first input of a Bypass node, with the output of the ERP Connector node designed to extract all fields connected to the botton input of the Bypass. Since all nodes in the "top" path are configured to only be enabled when the user has specified a field list, this means that if the user specifies a field list, the top path will be executed and the bypass will pass through the user specified fields. Otherwise, only the "bottom" path will be executed meaning all fields will be passed through the bypass. The "Extract Field Metadata" node is configured to only extract the field metadata from the user-specified table as shown below.


Figure 33 Configuration of the "Extract Field Metadata" node to extract field from RFC_READ_TABLE

Note that in the configuration above, the NO_DATA is set to "X" which means that only the field metadata will be output. The "QUERY_TABLE" scalar import parameter is set to {{^TableName^}} meaning that the TableName parameter the user sets on the composite will be used here to define the table who's fields are to be extracted. The OPTIONS path is simpler than the FIELDS path, since if there are no OPTIONS provided, we can simply provide an empty OPTIONS input table. The configuration of the OPTIONS Static Data node is shown below.


Figure 34 Configuration of the OPTIONS Static Data node

Then, all that is left to be configured within the composite is the node to actually read the table data. This node is configured with a "FIELDS" input for the "FIELDS" table import parameter and connected to the output of the bypass node. It also has an "OPTIONS" input for the "OPTIONS" table import parameter and is connected to the output of the "OPTIONS" static data node. The node is configured with "FIELDS" and "DATA" outputs to capture the corresponding table export parameters. Within the "Read Table" node, the configuration is shown below.


Figure 35 Configuration of the Read Table ERP Connector node

Here again, the QUERY_TABLE scalar import parameter is taken from the value set on the TableName parameter from the composite. Once the internals of the composite have been configured all that is left to do is configure the composite interface. This is relatively straightforward and simply involves creating three parameters on the node "TableName", "Fields" and "Options" as shown below. Note that only the TableName parameter is required.


Figure 36 Parameter Definitions for the Read Table composite

In order to run the node, the user simply needs to configure the composite parameters similar to that shown below for extracting the fields "CON_NAME" and "DBMS" from the "DBCON" table (with an additional "where" clause in the "Options" parameter".


Figure 37 Configured Read Table node extracting specific fields

Since the user only needs to specify the "TableName" parameter, if we wanted to extract all fields and all records from the table DD03L, the user could configure the node as shown below (note: this table can be very large so it is not advised to run this query).


Figure 38 Configuring the Read Table with only a table name

If the node is configured in such a manner, the "Fields" parameter is empty, therefore the "top" path within the composite will be disabled as shown below. Figure 39Internals of the Read Table composite with no user specified fields.

lae sap integration nodes: getting started - · pdf filelae sap integration nodes getting...

Documents