InterSystems SAP Service

An InterSystems SAP Business Service to receive from a SAP System.

---

• InterSystems SAP Service
  • Overview
  • Dependencies
  • Requirements
  • Installation
    • Download the latest release
    • Setup an external language server
    • Import proxy classes
    • Setup a service
    • Configure InterSystems Credentials
    • Configure the service
  • Lookup Table for XML Schemas
  • Flatten Tables Items
  • Settings
    • SAP Service
    • SAP Server Settings
    • SAP Client Settings
    • XML
    • Remote Inbound Adapter Settings
  • Bugs
  • Release Notes
    • v0.1 (2024-03-11)
    • v0.0.6 (2023-4-3)

---

Overview

---

Dependencies

• sapco.jar 3.0.11 or higher
• intersystems-jdbc.jar
• intersystems-utils.jar

Note: The intersystems-jdbc.jar and intersystems-utils.jar are included in the InterSystems IRIS installation. You can find them in the ~/dev/java folder.

---

Requirements

• InterSystems IRIS 2022.1 or newer or InterSystems IRIS for Health 2022.1 or newer
• An interoperability enabled namespace
• Java JDK 1.8 or 11

---

Installation

Download the latest release

1. Download the intersystems-sap-service-*.jar file from the latest release
2. Save the file to a folder visible to the InterSystems IRIS instance

Setup an external language server

1. In the Management Portal navigate to System Administration > Configuration > Connectivity > External Language Servers
2. Click on Create External Language Server or configure the standard %Java Server server by double-clicking on the server name
3. Select Java as the Server Type
4. Select the current intersystems-utils-x.x.x.jar in the classpath field. This file comes with your InterSystems IRIS installation. It can be found in <irissys>/dev/java/lib/1.8/. Seperate all additonal class paths with a Semi-colon (;) for Windows-Systems (e.g. /pathA/1.jar;/pathB/2.jar;/pathC/3.jar) and a colon (:) for UNIX-Systems (e.g. /pathA/1.jar:/pathB/2.jar:/pathC/3.jar).
5. Select the sapjco.jar in the Class Path field. The sapjco.dll must be in the same folder as the sapjco.jar file
6. Select the intersystems-utils.jar intersystems-sap-service-*.jar in the Class Path field.
7. Select the jdk folder in the Java Home Directory field
8. Click on Save
9. Click on Start next to the server you just created

Note: This step is namespace independent. You can use the same server in multiple namespaces.

Import proxy classes

1. In the Management Portal navigate to System Explorer > Classes
2. On the left side of the screen select the namespace where you want to use the service
3. Click on Import
4. Select Directory under Import from File or a Directory
5. Select the cls folder from the downloaded repository
6. Click on Import

Setup a service

1. In the Management Portal navigate to Interoperability > Configure > Production
2. Create a new production or open an existing one
3. Click on the + button next to the Services
4. In the field Service Class select the class com.intersystems.dach.ens.sap.PassthroughService
5. Click on OK

Configure InterSystems Credentials

1. In the Management Portal navigate to Interoperability > Configure > Credentials
2. Add an ID of your choice
3. Select the User Name
4. Select the Password
5. Click on Save or New

Configure the service

2. Select the just created service
3. Select the Settings tab on the right side of the screen
4. Under Remote Inbound Adapter Settings: External Language Server Name configure the name of the external language server you created in the Setup an external language server step
5. Configure all SAP connection parameters
6. Under Basic Settings: Target Config Names configure the name of the process or the operation you want to call
7. Click on Apply
8. Start the service

Tip: You can see if the service could be successfully started in the Log tab of the service.

---

Lookup Table for XML Schemas

You can use a lookup table to map the XML schema to the SAP function module. Navigate to Interoperability > Configure > Data Lookup Tables and create a new lookup table. The key is the name of the SAP function module and the value is the XML schema with the category, sperated by an double point e.g. My_Category:My_XML_Schema.

---

Flatten Tables Items

You can use the FlattenTables parameter to flatten the tables in the SAP response. The parameter is a boolean and if enabled, the service will flatten the tables in the SAP response. The default value is false.

Name	Age	State
John	42	NY
Mary	32	CA

The XML for the above table would look like this with the FlattenTables parameter set to false:

...
<Person>
    <item>
        <Name>John</Name>
        <Age>42</Age>
        <State>NY</State>
    </item>
    <item>
        <Name>Mary</Name>
        <Age>32</Age>
        <State>CA</State>
    </item>
</Person>
...

And the corresponding schema would look like this:

...
<xs:element name="Person" minOccurs="0">
    <xs:complexType>
        <xs:sequence>
            <xs:element name="item" minOccurs="0" maxOccurs="unbounded">
                <xs:complexType>
                    <xs:sequence>
                        <xs:element name="Name" type="xs:string" minOccurs="0"/>
                        <xs:element name="Age" type="xs:integer" minOccurs="0"/>
                        <xs:element name="State" type="xs:string" minOccurs="0"/>
                    </xs:sequence>
                </xs:complexType>
            </xs:element>
        </xs:sequence>
    </xs:complexType>
</xs:element>
...

The XML for the above table would look like this with the FlattenTables parameter set to true:

...
<Person>
    <Name>John</Name>
    <Age>42</Age>
    <State>NY</State>
</Person>
<Person>
    <Name>Mary</Name>
    <Age>32</Age>
    <State>CA</State>
</Person>
...

And the corresponding schema would look like this:

...
<xs:element name="Person" minOccurs="0" maxOccurs="unbounded">
    <xs:complexType>
        <xs:sequence>
            <xs:element name="Name" type="xs:string" minOccurs="0"/>
            <xs:element name="Age" type="xs:integer" minOccurs="0"/>
            <xs:element name="State" type="xs:string" minOccurs="0"/>
        </xs:sequence>
    </xs:complexType>
</xs:element>
...

---

Settings

SAP Service

• UseJSON boolean - If enabled, the service will convert the SAP data to JSON. (default: false)
• ConfirmationTimeoutSec integer, required - The time in seconds the service will wait for a confirmation for a message to be processed. (default: 10)
• EnableTesting boolean - If enabled, the service will start with some test data and will log more to the log. (default: false)
• EnableTracing boolean - If enabled the service will print all messages to the log. This is useful for debugging purposes. (default: false)
• QueueWarningThreshold integer, required - The maximum number of messages that can be queued. (default: 100)

SAP Server Settings

• GatewayHost string, required - The host address of the SAP Gateway
• GatewayService string, required - The service name of the SAP Gateway. Usually sapgwNN whereas NN is the instance number.
• ProgrammID string, required - The Program ID of this service to identify the connection.
• ConnectionCount integer, required - The number of connections to the SAP Gateway.
• Repository string, required - The name of the SAP Repository.

SAP Client Settings

• HostAddress string, required - The host address of the SAP System.
• ClientID string, required - The Client ID of your mandant.
• SystemNumber string, required - The System Number of the SAP System.
• SAPLanguage string, required - The language of the SAP System.
• SAPCredentials string, required - The ID of the credentials to use for the SAP System you configured in the Configure InterSystems Credentials step.

XML

• ImportXMLSchemas boolean - If enabled, the service will try to import the XML Schemas from the SAP System. (default: false)
• XMLSchemaPath string - The path to the folder where the XML Schemas should be stored. If the folder does not exist, it will be created.
• LookUpTableName string - The name of the table you configured in Lookup Table for XML Schemas. If left empty no lookup table will be used.
• FlattenTablesItems boolean - If enabled, the service will flatten the tables in the XML. See Flatten Tables Items for more information (default: false)
• XMLNamespace string - The namespace of the XML. If left empty no namespace will be used. You can use the placeholder {functionName} to use the name of the function as namespace.

Remote Inbound Adapter Settings

• External Language Server Name string, required - The name of the external language server to connect to.
• Gateway Extra CLASSPATH string, required - The path to the intersystems-sap-service-*.jar file.

---

Bugs

• no known bugs

---

Release Notes

v0.1 (2024-03-11)

• Adds compatibility to InterSystems IRIS version 2022.1 and newer
• Removes intersystems-utils and intersystems-jdbr java library from jar. Intersystems-utils must be added to class path manually.
• Use v0.0.6 for InterSystems IRIS versions older than 2022.1

v0.0.6 (2023-4-3)

• Initial release

---

by Andreas S. and Philipp B.