Summary

Hermes is a lightweight software application that clients deploy on a server inside their private network, safeguarded by their firewall. Its primary function is to regularly query the Graphite Public API for updates related to suppliers and then synchronize these updates with Oracle EBS using the provided stored procedures.

The software is designed to only initiate outbound HTTPS connections to the Graphite Public API and does not host any open ports or handle incoming requests from external sources.

For support and monitoring purposes, Hermes sends back error notifications and selected integration activity details to Graphite.

Architecture

Requirements

For PL/SQL Package:

Oracle Database Version >= 12c Rev 2 or greater
Access to APPS or a user that can properly execute APPS procedures.
An EBS user who has access to manager vendors and banking data across the required operating units.

For Hermes Binary:

If compiling from source: Go Version >= 1.21
Credentials for APPS or a user that can properly execute APPS procedures.
Outgoing and Incoming connection to *.projectgraphite.com and app.graphiteconnect.com
Hermes Configuration File

Configuration File

The configuration file allow Hermes to create the communication from Graphite to the Oracle Database. Please see the bundled encryption utility for information on storing this file securely.

Location: Same directory as the Hermes binary
File Name: config.json
Additional Notes: When copying the configuration, remove all comments (//). Including these will prevent Hermes from parsing the JSON properly.

Example for EBS

{
  "adapters": [
    {
      "dsn": "oracle://tiger:SCOTT@localhost:1521/ebs_ebsdb", // connection string for oralce database
      "adapterType": "ebs", // type of the adapter. Will always be ebs
      "adapterConfig": {
        "userId": 123, // user ID. Used in apps_initialize
        "applicationId": 123, // application ID. Used in apps_initialize
        "responsibilityId": 123, // responsibility ID. Used in apps_initialize
        "packageName": "graphite_sync", // name of the package. If not in APPS schema, pass with <schema_name>.<package_name>
        "withPljson": true,
        "packageLogLevel": "debug" // what level of debugging to use for the package. trace, debug, warn, error, panic are available values
      },
      "graphitePublicApi": {
        "url": "https://api-poc.projectgraphite.com", // URL of the environment. This will be provided
        "interfaceName": "interfaceName", // Name of the external interface. This will be provided
        "apiKey": "US000000.000000000.000000000000000000000" // Graphite API Key. Instructions will be provided.
      },
      "logging": {
        "level": "debug", // Log Level: trace, debug, warn, error
        "outputPath": "path/to/log/file.log", // Where to store the log file. This is a relative path to the binary
        "jsonLogging": true // log in JSON or flat text. JSON avoids some compatibility issues.
      }
    }
  ]
}

Multiple Concurrent Adapters

To run multiple concurrent adapters, include another object with the fields provided in the above example into the array. If you already have an executing process, restart it to include the additional adapter. This can make and maintain multiple database connections, allowing for multiple environments/multiple databases to be run on the same Hermes process.

Encryption

The Hermes configuration file gives the adapter the necessary credentials and context to connect and make updates to the database. Due to the sensitivity of this data, the configuration is always encrypted with AES-256 encryption on the file system. At runtime, Hermes will decrypt in memory without ever re-writing the decrypted configuration file on the file system.

Hermes will store the required decrypted data in memory to maintain connection with the database.

To enable this, Hermes come bundled with an encryption utility to facilitate easy encryption and decryption with several supported encryption key providers.

Location: Same directory as the Hermes binary
File Name: encryption_config.json
Additional Notes: When copying the configuration, remove all comments (//). Including these will prevent Hermes from parsing the JSON properly.

Configuration

Hermes uses an encryption configuration to specify what encryption method should be used and any additional parameters that need to be provided.

Encryption Key Providers

Password

To encrypt using a password, set the fetchType to password. Once prompted, enter the password to encrypt/decrypt the configuration file.

Environment Variable

To encrypt using en environment variable, set the fetchType to environmentVariable and provide the environment variable the key is stored in with the environmentVariable key.

Named Pipes / Sockets

To encrypt using named pipes (Windows)/sockets (Unix and Unix-like), set the fetchMethod to named_pipes. This will create a listener waiting for the password from a key provider. Launch another hermes process with the argument --provide. Once provided, the initial process will begin executing.

Secret Managers

Hermes supports storing the encryption key in a cloud provider secret manager. To use, set the fetchMethod to one of the secret providers specified below. Find your secret manager below for setup instructions:

AWS Secret Manager
- fetchMethod: aws_secretmanager
- To use AWS Secret Manager, the shared credential file must be stored in ~/.aws/credentials.

Examples

All Configuration Options

{
  "fetchMethod": "password", // Method for fetching key. Values are environmentVariable, password, named_pipes, aws_secretmanager
  "alwaysFetch": false, // --encrypt and --decrypt by default will use the "password" fetch method. set to true to always use the provided fetch method

  // environmentVariable
  "environmentVariable": "ENV_NAME", // The name of the environment variable to fetch the key from

  // aws_secretmanager
  "awsRegion": "us-east-1", // The AWS region to fetch the key from
  "awsSecretKey": "SECRET_KEY" // The AWS secret key to fetch the key from
}

AWS Secret Manager

{
  "fetchMethod": "aws_secretmanager",
  "alwaysFetch": true,
  "awsRegion": "us-east-1",
  "awsSecretKey": "superSecretKey"
}

How to Encrypt

Once the configuration file is created and located in the same directory as the Hermes binary, execute the command: ./hermes –encrypt. By default, Hermes will use the password fetch method to encrypt the file. Set alwaysFetch to true to override this behavior and use the fetchMethod instead.

Once the key is provided, Hermes will encrypt the configuration file with the provided key.
After the file is encrypted, the original configuration file will be overwritten and renamed it to config.json.encrypted.

How to Decrypt

If a config.json.encrypted file exists in the same directory of the Hermes binary, execute the ./hermes -decrypt method to decrypt back to plain text. By default, Hermes will use the password fetch method to encrypt the file. Set alwaysFetch to true to override this behavior and use the fetchMethod instead.

Hermes will prompt with an incorrect key if the file did not decrypt to valid JSON. This will not overwrite the encrypted file with the incorrect key.

This key will be used to decrypt the contents of the configuration file.

PL/SQL Procedure

Procedures Called

ap_vendor_pub_pkg.create_vendor
ap_vendor_pub_pkg.create_vendor_contact
ap_vendor_pub_pkg.create_vendor_site
ap_vendor_pub_pkg.update_vendor_contact_public
ap_vendor_pub_pkg.update_vendor_public
ap_vendor_pub_pkg.update_vendor_site_public
iby_ext_bankacct_pub.check_bank_exist
iby_ext_bankacct_pub.check_ext_acct_exist
iby_ext_bankacct_pub.check_ext_bank_branch_exist
iby_ext_bankacct_pub.create_ext_bank
iby_ext_bankacct_pub.create_ext_bank_acct
iby_ext_bankacct_pub.create_ext_bank_branch
iby_ext_bankacct_pub.create_intermediary_acct
iby_ext_bankacct_pub.update_ext_bank
iby_ext_bankacct_pub.update_ext_bank_acct
iby_ext_bankacct_pub.update_ext_bank_branc

Tables Selected From

ap_supplier_sites_all
ap_suppliers
hz_code_assignments
hz_parties
iby_ext_bank_accounts
iby_intermediary_accts