Configure Access to SAP oData Print API¶

Introduction¶

As of version 7.1.0, PLOSSYS Output Engine supports access to the SAP oData Print API with the goal to substitute the SAP Cloud Print Manager with a full integration into Output Engine.

The print API is a way to retrieve print jobs from SAP systems and notifiy the SAP system about the status of the print jobs.

SAP print jobs with attachments are supported, too. In this case all documents within the print job are handled as a document stream to ensure they are printed in correct order without being interrupted. Only one notification is sent after the last document in the document stream has been processed.

The print API is a RESTful API that is used to communicate with SAP by offering different communication scenarios. Output Engine supports scenario "SAP_COM_0466: Printing – Pull integration".

Access to SAP print API is provided by seal-cpm-checkin service and configured with the following service keys:

SAP_AIR_KEY: The secret key used to access the SAP Application Interfaces. The key is provided by SAP.
SECRET: The secret used to encrypt the passwords.
SECRET_FILE: File containing the secret used to encrypt the passwords.
SAP_SYSTEMS: A JSON or YAML representation of the SAP systems to access, refer to SAP_SYSTEMS below.

Additionally, SAP printer parameters have to be configured in the Output Engine printer configuration.

SAP_SYSTEMS¶

The SAP_SYSTEMS key is a JSON or YAML representation of the SAP systems that are accessed. The key is a list of objects, where each object represents a SAP system. The following keys are used for each object:

Mandatory keys¶

systemId: Three-letter name of the SAP system, e.g. H22, used for logging purposes and future implementation of scenario "SAP_COM_0467: Printing - Notification Integration".
user: SAP technical user name.
password: SAP technical user password. Either encrypted using SECRET or SECRET_FILE or clear text. On how to encrypt passwords, refer to Secure the SAP Login Data.
authClientId: oAuth client id, only mandatory for oAuth 2.0 authentication, not used for basic or csrf authentication.
authClientSecret: oAuth client secret, only mandatory for oAuth 2.0 authentication, not used for basic or csrf authentication.

Optional keys¶

systemName: Description of the SAP system, replaces systemId for logging if given.
client: Client Id used for the SAP system.
loginMethod: Method to use for login, possible values are basic, csrf, oauth, default csrf.
scenario: The communication scenario to use, possible values are "466", "467", "both", default "both". The "both" scenario distinguishes the queues by the OMSType ("466", or "467") given by the SAP system.
srvHostPort: Host and port of SAP service in URL format, default is "https://localhost:50001".
srvPath: Path to SAP oData Print API service, default is /sap/opu/odata/sap/API_CLOUD_PRINT_PULL_SRV.
icmInterval: Interval for polling SAP ICM cache, default is 5s.
maxItems: Maximum number of items to fetch from SAP when itemTransfer is set to multi, default is 150.
waitAfterFetchError: Time to wait after fetch error, default is 5s.
authIssuerUrl: URL to OAuth service, default is ${srvHostPort}/oauth/token.
itemTransfer: Method for transfering document items, possible values single and multi. Default is multi.
notifyTransfer: Method for transfering document status notifications, possible values single and multi. Default is value from itemTransfer.
mappings: List of mappings for SAP printer names to OMS printer names. Every entry consists of an object with two properties:
- sap: Name of the queue in SAP. The key is mandatory if mappings is present.
- pls: Printer name in PLOSSYS Output Engine. The key is mandatory if mappings is present.

Typical configuration¶

Example - typical configuration using HTTPS and systemId

SAP_SYSTEMS: |
  - systemId: "H22"
    user: "technicalUser"
    password: "encryptedPassword"
    srvHostPort: "https://123.124.125.126:44300"

Connects to https://123.124.125.126:44300, using csrf as login method and the default path to the SAP Cloud Print service. Retrieving print jobs for all printers assigned to user technicalUser.

Example - typical configuration using HTTP and systemName

SAP_SYSTEMS: |
  - systemName: "My SAP System"
    client: "001"
    user: "technicalUser"
    password: "encryptedPassword"
    srvHostPort: "http://10.100.53.130:50000"

Connects to http://10.100.53.130:50000, using csrf as login method and the default path to the SAP Cloud Print service. Retrieving print jobs for all printers assigned to user technicalUser.

Full YAML configuration¶

SAP_SYSTEMS: |
  - systemName: "My SAP System"
    client: "001"
    loginMethod: "oauth"
    user: "username"
    password: "encryptedPassword"
    authClientId: "cpm-checkin"
    authClientSecret: "f042973a-b56c-4ded-8414-7988b8e7bff0"
    authIssuerUrl: "https://myidentityprovider:443/oauth/token"
    srvHostPort: "http://10.100.53.130:50000"
    srvPath: "/sap/opu/odata/sap/API_CLOUD_PRINT_PULL_SRV"
    icmInterval: 5s
    maxItems: 150
    waitAfterFetchError: 10s
    itemTransfer: multi
    notifyTransfer: multi
    mappings:
      - sap: TEST1
        pls: printer4

Full JSON configuration¶

SAP_SYSTEMS: |
  [
    {
      "systemName": "My SAP System",
      "client": "001",
      "loginMethod": "oauth",
      "user": "username",
      "password": "encryptedPassword",
      "authClientId": "cpm-checkin",
      "authClientSecret": "f042973a-b56c-4ded-8414-7988b8e7bff0",
      "authIssuerUrl": "https://myidentityprovider:443/oauth/token",
      "srvHostPort": "http://10.100.53.130:50000",
      "srvPath": "/sap/opu/odata/sap/API_CLOUD_PRINT_PULL_SRV",
      "icmInterval": "5s",
      "maxItems": 150,
      "waitAfterFetchError": "10s",
      "itemTransfer": `multi`,
      "notifyTransfer": `multi`,
      "mappings": {
        "sap": "TEST1",
        "pls": "printer4"
      }
    }
  ]

Printer Configuration¶

The SAP printer parameters are derived from the Output Engine printer configuration.

job overrides are used to disable a parameter or set a single available value. Valid parameter keys for overrides are PRINT_QUALITY, COLOR_MODEL and DUPLEX.

Example - job override disabling duplex

job:
  override:
    DUPLEX: false

Example - job override set duplex to LONG_SIDE

job:
  override:
    DUPLEX: LONG_SIDE

job defaults are used to set a default value from a fix list of possible values. Valid parameter keys for setting defaults are PRINT_QUALITY, COLOR_MODEL and DUPLEX.

Example - job default COLOR

job:
  default:
    COLOR_MODEL: COLOR

finisher enables one or more finishing options for print jobs. Available options are STAPLE, PUNCH, FOLD and SORT.

Example - enabling finishing for STAPLE

finisher: ["STAPLE"]

ppd enables selecting media sizes for the print jobs. The media sizes are read from the spezified PPD file.

Example - PPD file

ppd: "small-a4-a3.ppd"

The above example results in selectable media sizes from "ISO_A6" to "ISO_A3" in the print job.

Communication Scenario 467¶

The communication scenario 467 extends the communication scenario 466 by adding a notification route to the seal-cpm-checkin service. The notification route is used by the SAP system to notify Output Engine about jobs to print.

The general URL of the notification route is:

```
https://<oms_host>:<oms_port>/v1/jobs/notification
```

<oms_host> and <oms_port> are host and port of the seal-cpm-checkin service.

For the notification route of the communication scenario "SAP_COM_0467: Printing - Notification Integration" to work correctly and secure, the following service keys need to be configured:

USE_HTTP: Optional, if set to true, the seal-cpm-checkin service will only use HTTP for communication with the SAP system. This is useful for cloud environments that handle traffic via load balancers and nginx controllers. Default is false.
TLS_EXTERNAL_DIR: Directory with TLS certificates and keys used for TLS encryption and authentication

Authentication¶

AUTH_TYPE: The authentication type to use for the notification route, possible values are "none", "basic", "cert" and "oidc", default is "none". Depending on the authentication type, different service keys are required.

Hint - AUTH_TYPE none

The AUTH_TYPE none is dangerous, because it allows any user to access the notification route without authentication. Do not expose the seal-cpm-checkin service to the internet if you use this authentication type.

Hint - AUTH_TYPE cert

For AUTH_TYPE cert to work the TLS_EXTERNAL_DIR directory may need to contain the certification authority certificate ca.pem.

Basic Authentication:

HTPASSWD_FILE: File with user/password combinations for basic authentication.
HTPASSWD: Single user/password combinations for basic authentication, has priority over HTPASSWD_FILE.

Certificate Authentication:

AUTH_ISSUER_URL: URL of the OIDC identity provider, used for OIDC authentication
AUTH_PROXY: Optional URL of a proxy for accessing the OIDC identity provider.
ID_PROVIDER_NAME: List of identity provider names, used for OIDC authentication.
TRUSTED_CLIENT: Expected name of the OIDC client, used for OIDC authentication.