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

Introduction

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

From a technical perspective, the SAP ActionHandler 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 in the implementation phase of HIRO.

  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.

  3. The containers open an http port (8080/8081). Please make sure these ports are available in network setup. Check the DockerHub help pages for details.

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:
  [...]
  control:
    image: arago/hiro-actionhandler-sap-control:latest
    ports: ["8081:8081"]
    env_file: SAPSystem.env
    restart: always
  rfc:
    image: arago/hiro-actionhandler-sap-rfc:latest
    ports: ["8080:8080"]
    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 ActionHandler environment variable file for the docker image that holds various setting and the credentials for your SAP instance.

Sample SAPSystem.env for arago SAP demo instance
LOGLEVEL=DEBUG #Preferred log level
TTL=300
SOLMAN_ENDPOINT=46.51.143.42
SOLMAN_PORT=44300
SOLMAN_PROT=HTTP
USESSL=NO

The arago SAP demo instance is currently running without SSL authentification, so you will be able to connect even with no or incorrect SSL settings.

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
{
  "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 sucess, you should see the following log entries:

Sample log entris after successfull composition
[...]
control_1      | Starting SAP control action handler
control_1      | 2021-01-20 14:59:11 INFO    Parsed command line arguments and config file
[...]
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

You can test the SAP ActionHandler by runnig curl-commands, using bash or Postman™ or alike:

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"
}

Sample KIs for testing from HIRO

Once you have successfully verified the ActionHandler 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)