• Services
  • Migration Topics
  • Integration
    • Standard ActionHandlers
    • ServiceNow
    • SAP
      • SAP™ Action Handler Installation Guide (Docker Image)
    • Jira
    • Email
    • CSV
    • Approval
    • Introduction to ActionHandlers and Connectors
  • Concepts
  • Best Practices
  • Api

Introduction

Action Handlers are integration components of the HIRO™ system. They are used to invoke actions on target systems. This document walks you through the installation procedure of the HIRO™ SAP™ Action Handler.

From a technical perspective, the SAP Action Handler is a microservice envoked using the HIRO™ HTTP Action Handler, which is included in the Standard Docker image for Action Handlers.

Prerequisites

Before you can configure the SAP Action Handler, make sure the following prerequisites are fulfilled:

  1. You have configured your SAP according to the HIRO™ for SAP Operations - Implementation Guide. This document will be provided to you by us in the implementation phase of your project.

  2. You have followed the instructions in Standard Docker image for Action Handlers to setup the Action Handler Docker container. Please ensure that you are able to process HTTP requests from HIRO.

Defining docker composition (docker-compose.yml)

You need to add the following services definitions to your docker composition file:

Extensions to docker-compose.yml
services:
  [...]
  rfc:
    image: arago/hiro-actionhandler-sap-rfc:latest
    env_file: SAPSystem.env
    restart: always
    volumes: #required for SSL only
      - type: bind
        source: [absolut path]/[certificate file]
        target: /opt/arago/actionhandler/certs/cert.crt
      - type: bind
        source: [absolut path]/[key file]
        target: /opt/arago/actionhandler/certs/cert.key

Creating environment variable file (SAPSystem.env)

You need to create an additional environment variable file for the docker image that holds various settings for your SAP instance.

Sample SAPSystem.env for arago SAP demo instance
LOGLEVEL=DEBUG #Preferred log level
TTL=300
SOLMAN_ENDPOINT=XXX.XXX.XXX.XXX # the IP address of your SAP endpoint
SOLMAN_PORT=44300
SOLMAN_PROT=HTTP
USESSL=NO

Arago has a SAP demo instance, which customers may use on request for testing purposes. We can provide you with the IP and credentials for this demo instance.

Action Handler configuration map (AH_CONFIG)

You also need to extend your Action Handler configuration map to define the new SAP capabilites:

Extensions to AH_CONFIG in the ActionHandler.env file
{
  "handlers": [
    {...},
    {
      "name": "SAPHandler",
      "capability": "SAPRequest",
      "implementation": "REST",
      "applicability": ["on ogit/_id"],
      "url": "http://rfc:8080/request"
    }
  ]
}

Please refer to How to configure capabilities in the standard Action Handler (Docker image) for details on the configuration map.

Starting the ActionHandler container

Once the composition is defined, you can start the ActionHandler docker container by issuing the following command:

docker-compose up

Please make sure you are issuing this command from the same directory your docker-compose.yml file is located in. Upon success, you should see the following log entries:

Sample log entris after successful composition
[...]
rfc_1          | Starting SAP rfc action handler
rfc_1          | 2021-01-20 14:59:11 INFO    Parsed command line arguments and config file
[...]
rfc_1          | 2021-01-20 14:59:11 DEBUG   <HIROEngineSyncRESTInterface "Engine Interface"> registered <Root "SAP RFC ActionHandler"> as its parent.
rfc_1          | 2021-01-20 14:59:11 DEBUG   <HIROEngineSyncRESTInterface "Engine Interface"> registered as child of <Root "SAP RFC ActionHandler">.
rfc_1          | 2021-01-20 14:59:11 DEBUG   <ShortestQueueRouter "actor-0"> registered <Root "SAP RFC ActionHandler"> as its parent.
rfc_1          | 2021-01-20 14:59:11 DEBUG   <ShortestQueueRouter "actor-0"> registered as child of <Root "SAP RFC ActionHandler">.
[...]

In case of generic docker problems, please refer to the DockerHub help pages. On problems related to the ActionHandler docker image, please contact HIRO Support.

Running a local test

If you want to test the SAP connection locally without running actions through HIRO™, you can test the SAP ActionHandler by running curl commands, using bash or Postman™ or alike.

Preparation: You need to temporarily expose the internal request endpoint of the rfc service, so that you can call it from outside the container. This is done by specifying a port forwarding for port 8080 of the service:

services:
  [...]
  rfc:
    image: arago/hiro-actionhandler-sap-rfc:latest
    ports: ["8080:8080"]
    [...]

After you have exposed the request endpoint, you can send commands to SAP, as in the examples below. Don’t forget to remove the port mapping after your tests!

curl commands for testing
curl --request POST 'http://localhost:8080/request' --header 'Content-Type: application/json' --data-raw '{"function":"RFC_SYSTEM_INFO"}'
curl --request POST 'http://localhost:8080/request' --header 'Content-type: application/json' --data-raw '{"function":"RFC_READ_TABLE", "parameters": "{ \"QUERY_TABLE\":\"T000\" }" }'

Expect the following results:

{
    "result": {
        "rc": 0,
        "status": "",
        "stderr": "",
        "stdout": "{\"CURRENT_RESOURCES\":14,\"DEST_COMMUNICATION_MESSAGE\":\"\",\"DEST_SYSTEM_MESSAGE\":\"\",\"DIALOG_USER_TYPE\":\"Y\",\"MAXIMAL_RESOURCES\":15,\"RECOMMENDED_DELAY\":0,\"RFCSI_EXPORT\":{\"RFCPROTO\":\"011\",\"RFCCHARTYP\":\"4103\",\"RFCINTTYP\":\"LIT\",\"RFCFLOTYP\":\"IE3\",\"RFCDEST\":\"vhcala4hsmci_A4H_00\",\"RFCHOST\":\"vhcala4h\",\"RFCSYSID\":\"A4H\",\"RFCDATABS\":\"A4H\",\"RFCDBHOST\":\"vhcalhdbdba\",\"RFCDBSYS\":\"HDB\",\"RFCSAPRL\":\"740\",\"RFCMACH\":\"  390\",\"RFCOPSYS\":\"Linux\",\"RFCTZONE\":\"     0\",\"RFCDAYST\":\"\",\"RFCIPADDR\":\"172.31.25.64\",\"RFCKERNRL\":\"749\",\"RFCHOST2\":\"vhcala4hsmci\",\"RFCSI_RESV\":\"\",\"RFCIPV6ADDR\":\"172.31.25.64\"},\"RFC_LOGIN_COMPLETE\":\"Y\"}",
        "success": true
    },
    "status": "done"
}
{
    "result": {
        "rc": 0,
        "status": "",
        "stderr": "",
        "stdout": "{\"DATA\":[{\"WA\":\"000SAP AG Konzern Walldorf EUR S2 X SOLMAN 20170613\"},{\"WA\":\"001SAP AG Konzern Walldorf EUR C1 X SOLMAN 20160712A4HCLNT001\"},{\"WA\":\"066Test EarlyWatch Profiles Walldorf EUR S11 X SAP 00000000\"}],\"FIELDS\":[{\"FIELDNAME\":\"MANDT\",\"OFFSET\":\"000000\",\"LENGTH\":\"000003\",\"TYPE\":\"C\",\"FIELDTEXT\":\"Client\"},{\"FIELDNAME\":\"MTEXT\",\"OFFSET\":\"000003\",\"LENGTH\":\"000025\",\"TYPE\":\"C\",\"FIELDTEXT\":\"Client name\"},{\"FIELDNAME\":\"ORT01\",\"OFFSET\":\"000028\",\"LENGTH\":\"000025\",\"TYPE\":\"C\",\"FIELDTEXT\":\"City\"},{\"FIELDNAME\":\"MWAER\",\"OFFSET\":\"000053\",\"LENGTH\":\"000005\",\"TYPE\":\"C\",\"FIELDTEXT\":\"Standard currency throughout client\"},{\"FIELDNAME\":\"ADRNR\",\"OFFSET\":\"000058\",\"LENGTH\":\"000010\",\"TYPE\":\"C\",\"FIELDTEXT\":\"Character Field Length = 10\"},{\"FIELDNAME\":\"CCCATEGORY\",\"OFFSET\":\"000068\",\"LENGTH\":\"000001\",\"TYPE\":\"C\",\"FIELDTEXT\":\"Client control: Role of client (production, test,...)\"},{\"FIELDNAME\":\"CCCORACTIV\",\"OFFSET\":\"000069\",\"LENGTH\":\"000001\",\"TYPE\":\"C\",\"FIELDTEXT\":\"Changes and Transports for Client-Specific Objects\"},{\"FIELDNAME\":\"CCNOCLIIND\",\"OFFSET\":\"000070\",\"LENGTH\":\"000001\",\"TYPE\":\"C\",\"FIELDTEXT\":\"Maintenance Authorization for Objects in All Clients\"},{\"FIELDNAME\":\"CCCOPYLOCK\",\"OFFSET\":\"000071\",\"LENGTH\":\"000001\",\"TYPE\":\"C\",\"FIELDTEXT\":\"Protection reg. client copy program and comparison tools\"},{\"FIELDNAME\":\"CCNOCASCAD\",\"OFFSET\":\"000072\",\"LENGTH\":\"000001\",\"TYPE\":\"C\",\"FIELDTEXT\":\"Client control: No client cascade for upgrade import\"},{\"FIELDNAME\":\"CCSOFTLOCK\",\"OFFSET\":\"000073\",\"LENGTH\":\"000001\",\"TYPE\":\"C\",\"FIELDTEXT\":\"Client control: Soft Lock Required (Planned for 4.0)\"},{\"FIELDNAME\":\"CCORIGCONT\",\"OFFSET\":\"000074\",\"LENGTH\":\"000001\",\"TYPE\":\"C\",\"FIELDTEXT\":\"Recording Client for Switch BC Sets\"},{\"FIELDNAME\":\"CCIMAILDIS\",\"OFFSET\":\"000075\",\"LENGTH\":\"000001\",\"TYPE\":\"C\",\"FIELDTEXT\":\"Client Control: CATT und eCATT Authorization\"},{\"FIELDNAME\":\"CCTEMPLOCK\",\"OFFSET\":\"000076\",\"LENGTH\":\"000001\",\"TYPE\":\"C\",\"FIELDTEXT\":\"Client control: Indicator that client is temporarily locked\"},{\"FIELDNAME\":\"CHANGEUSER\",\"OFFSET\":\"000077\",\"LENGTH\":\"000012\",\"TYPE\":\"C\",\"FIELDTEXT\":\"Last Changed By\"},{\"FIELDNAME\":\"CHANGEDATE\",\"OFFSET\":\"000089\",\"LENGTH\":\"000008\",\"TYPE\":\"D\",\"FIELDTEXT\":\"Date of Last Change\"},{\"FIELDNAME\":\"LOGSYS\",\"OFFSET\":\"000097\",\"LENGTH\":\"000010\",\"TYPE\":\"C\",\"FIELDTEXT\":\"Logical system\"}],\"OPTIONS\":[]}",
        "success": true
    },
    "status": "done"
}

Please don’t forget to remove the port mapping again after your tests!

Sample KIs for testing from HIRO

Once you have successfully verified the Action Handler locally, you can test it by triggering the follow KI from HIRO™:

Sample KI for an SAP request
on
  ogit/_id
when
  ProcessIssue == "TestSAPRequest"
do
  stdout: LOCAL::OUTPUT,
  stderr: LOCAL::ERROR,
  rc: LOCAL::SYSTEMRC = action("SAPRequest",
	  function :"RFC_GET_SYSTEM_INFO"
  )
  if LOCAL::SYSTEMRC == 0 then
    log("SUCCESS: ${LOCAL::OUTPUT}")
  else
    log("ERROR ${LOCAL::ERROR}")
  end

  stdout: LOCAL::OUTPUT,
  stderr: LOCAL::ERROR,
  rc: LOCAL::SYSTEMRC = action("SAPRequest",
	  function :"RFC_READ_TABLE",
	  parameters: '{
      "QUERY_TABLE": "T000"
    }'
  )
  if LOCAL::SYSTEMRC == 0 then
    log("SUCCESS: ${LOCAL::OUTPUT}")
  else
    log("ERROR ${LOCAL::ERROR}")
  end

  delete(ProcessIssue)