Guides

Hermes for S4/Hana

Installation, and Configuration of Hermes instance for S4/HANA Interface

Suggest Edits

Introduction

Hermes is an open-source middleware in order to sync vendor master data between Graphite Connect and on-premise ERPs. Hermes supports an interface to SAP S4/HANA, and has the ability to create and update business partners and populate address, banking, company code and purchasing organization data.

Installation

You can obtain the latest Hermes installation for:

The development build of Hermes can be downloaded here (These builds are unstable and only for testing new features/bug fixes):

After unzipping to a directory of the user's choice and configuration of the settings has been completed, the integration can either run by executing the following commands in the Hermes directory:

  • For Linux: ./run.sh
  • For Windows: run.cmd

Or by setting up Hermes to run as a Windows Service. This is generally recommended for all use that is not for testing purposes.

Configuration

Setting up Hermes for S4 requires certain parameters to be defined in the production.json file at the top of the Hermes directory. 

{
  "graphiteApiUrl": "API Endpoint from which Hermes will request data from Graphite",
  "graphiteApiKey": "Graphite API Key",
  "graphiteInterfaceName": "Hermes Interface Name",
  "adapterType": "Hermes adapter type (Will always be 'SAP_S4')",
  "S4Params": {
    "baseUrl": "URL to access the business partner endpoint on S4",
    "bankBaseUrl": "URL to access to bank master endpoint on S4",
    "username": "Integration Username",
    "password": "Integration User Password",
    "client": "S4 Client Number"
  }
}

The production.json file might look like: 

{
  "graphiteApiUrl": "https://poc-api.projectgraphite.com",
  "graphiteApiKey": "US12345.0123456789abc.0123456789abcdefg0123456789abcdefg",
  "graphiteInterfaceName": "SFour",
  "adapterType": "SAP_S4",
  "S4Params": {
    "baseUrl": "https://my123456.s4hana.cloud.sap/sap/opu/odata/sap/API_BUSINESS_PARTNER",
    "bankBaseUrl": "https://my123456.s4hana.cloud.sap/sap/opu/odata4/sap/api_bank/srvd_a2x/sap/bank/0001",
    "username": "GRAPHITE_USER",
    "password": "aVery$trongPassword54321%",
    "client": "500"
  }
}

To generate a Graphite API key, read here

The contents of this file must be valid JSON in order to be read by Hermes. Errors connecting will be encountered otherwise. Note that the adapter must be restarted in order for any changes to the configuration settings to take effect.

To secure the settings written in this file, Hermes offers the means by which this information can be encrypted.

System Requirements

OS:

  • Windows 10 or greater
  • Windows Server 2019 or greater
  • Any recent x86-64 Linux distro
    • Must have glibc version >= 2.28

Memory: 1 GB

Disk Space: 1 GB

CPU: Intel Core i5-10400 or equivalent

Network and Permissions

As middleware, Hermes will communicate with both Graphite and S4. For both directions, Hermes makes use of the HTTPS protocol to make RESTful API requests. In the case where Hermes is installed behind the customer's firewall, the customer's firewall must whitelist Graphite API endpoint. This will be provided upon customer request along with SSL certificates.

  • Windows: node.exe dist\encryption.js --provide `
  • Linux: node dist/encryption.js --provide

The CLI will prompt the user for a password. The password that is entered must be the same password that was used to encrypt the file with. Otherwise, the decryption will not be successful.

Encryption

Hermes requires a key in order to decrypt the configuration file. You can supply this key to Hermes in several ways:

  • An environment variable (HERMES_ENCRYPTION_KEY)
    • This option allows Hermes to start as a service without user interaction.
  • An interactive CLI program
    • This option requires users to run a CLI command every time hermes restarts, prompting that user for the encryption key. The CLI will send the key to the running Hermes process which can then decrypt the configuration file and continue operation. If the configuration file is encrypted, Hermes will block until it receives the key.

CLI Usage

Configuration settings can be secured by symmetrically encrypting them with a password. Hermes comes with a CLI to help facilitate this process. To Encrypt, run the commands from the top directory:

  • Windows: node.exe dist\encryption.js --encrypt
  • Linux: node dist/encryption.js --encrypt

The CLI will then prompt the user for a password. Once entered, the contents of production.json will be encrypted and moved into the production.json.encrypted file. One must keep a copy of this password elsewhere, as there is no way to recover this password if it is lost. If the password is lost, the contents of production.json.encrypted will be unrecoverable, and it will have to be recreated.

Hermes uses the AES-256 CTR cipher for encryption.

Starting Hermes with an Encrypted Configuration

The process for starting Hermes using an encrypted config file is slightly different than the standard usage. After the initial step of starting Hermes via the command/shell script or as a windows service, Hermes will await a separate command to be provided the password with which it will decrypt in memory the configuration settings. To do so, run the command in a separate terminal:

  • Windows: node.exe dist\encryption.js --provide `
  • Linux: node dist/encryption.js --provide

The CLI will prompt the user for a password. The password that is entered must be the same password that was used to encrypt the file with. Otherwise, the decryption will not be successful.

Decryption

To make edits to or view the contents of production.json.encrypted, run the command:

  • Windows: node.exe dist\encryption.js --decrypt
  • Linux: node dist/encryption.js --decrypt

The CLI will prompt the user for the password used for the encryption. If successful, contents will be written out to the prouction.json file. Otherwise, an error will be thrown and the command will have to be run again with the correct password.

Windows Service

To run Hermes as a Windows Service, run the following command with admin privledges:

node.exe dist\win-svc.js install

This will install a service (named "Graphite Hermes" by default) and start it. The name of the service can be configured using the windowsServiceName parameter in the production.json file.

To uninstall, run with admin privileges:

node.exe dist\win-svc.js uninstall

Updated 27 days ago