Communication Scenario 466:
Printing – Pull Integration¶

Literature - SAP documentation

Refer to SAP_COM_0466 for further information.

Set up communication scenario SAP_COM_0466 on the SAP side first, using the section matching your deployment type below. Then configure the seal-cpm-checkin service with the values obtained there.

Configure SAP_COM_0466 in SAP (Private Cloud)¶

For on-premise and private cloud systems:

Activate the OData service API_CLOUD_PRINT_PULL_SRV on the SAP system, following SAP Basis Configuration - Server - System Description as of version 1.5.1, chapter OData Service Activation.
Create or use a technical user with the rights described in SAP Note 3420465 - Print queues in on-premise systems.
Ensure the seal-cpm-checkin service URL is reachable from within the SAP system landscape.
Note the SAP system's host, port, and the technical user's name and password; they are used in Configure the cpm-checkin Service below.

Configure SAP_COM_0466 in SAP (Public Cloud)¶

This section describes only the SAP-side setup, using the Communication Management apps of SAP S/4HANA Cloud Public Edition. It does not apply to on-premise or private cloud systems, see Requirements for their SAP-side setup. The system URL, user and password obtained here are used in Configure the cpm-checkin Service below.

Prerequisites¶

The solution process 1LQ Output Management is installed in the SAP system.
A user with the business roles Communication Management (SAP_CORE_BC_COM) and Output Management (SAP_CORE_BC_OM or SAP_CORE_BC_OM_PRT) is available. Without these roles, the configuration steps below cannot be performed.

Check Communication Scenario SAP_COM_0466¶

Sign in to the SAP S/4HANA system with the user described above.
Go to the Communication Management section and start the app Display Communication Scenarios.
Find the communication scenario described above in the list. If the entry does not exist, the system is not set up correctly; contact SAP.

Create a Communication User¶

Go to the Communication Management section and start the app Maintain Communication Users.
Create a new user for this scenario: enter user name, description and a password, or use Propose Password. Do not use the certificate section; only basic authentication is currently implemented.
Press Create to save the new user.

Create a Communication System¶

Go to the Communication Management section and start the app Communication Systems.
Create a new communication system, using a System ID that was not used before. The System Name is filled automatically; keep it unchanged to avoid confusion.
In the General section, select inbound only, or enter the host name or IP address of the OMS.
In the Users for Inbound Communication section, add the communication user created above.
Save the communication system. Scenario 0466 only uses inbound communication; do not change any other section of the communication system.

Create a Communication Arrangement¶

Go to the Communication Management section and start the app Communication Arrangements.
Create a new communication arrangement for the communication scenario described above, referencing the communication system created above. The user name is filled automatically with the communication user created earlier.
Save the arrangement.

Create a Print Queue¶

Go to the Output Management section and start the app Maintain Print Queues.
Create a new print queue of type OMS for Pull Integration Queue — the default queue type is for SAP's own Cloud Print Manager and does not appear in the OMS.
Enter a name and description for the queue, choose a format, and select the communication user and arrangement created above.
Note the system URL shown at the bottom of the print queue list; it is needed in Configure the cpm-checkin Service below.

A communication user can have any number of print queues. When changing the user of a communication arrangement, the print queue names using that user can be updated automatically via the arrangement's additional properties.

Configure SAP_COM_0466 in SAP (BTP)¶

SAP BTP does not use communication scenarios or the Communication Management apps described above. Instead, print queues are accessed through the Print Service, which is subscribed to and configured per subaccount in the SAP BTP cockpit. The values obtained here are used in Configure the cpm-checkin Service below.

Ensure Cloud Foundry is enabled for the subaccount and a space exists.
Subscribe to the Print Service, then go to Instances and Subscriptions and create a service instance using the receiver plan. This plan is used to connect an external OMS such as PLOSSYS Output Engine; create a separate instance for each connecting system.
Create a service key for the new instance. Note the service_url, clientid, clientsecret and url values from the key; they are used in Configure the cpm-checkin Service below.
Select the Print Service subscription and open the Maintain Print Queues app.
Create a new print queue: enter a name and description, choose a format, set Print User to the name of the service instance created above, and set the retention period. The queue offers a Create Test Page action that can be used to test the connection without a full SAP business process.

A service instance can have any number of print queues.

Configure the cpm-checkin Service¶

This configuration is required for all deployment types (on-premise, private cloud, public cloud and BTP). Access to SAP OData Print API is provided by seal-cpm-checkin service and configured with the following service keys:

SAP_AIR_KEY: Mandatory. The secret key used to access the SAP Application Interfaces. The key is provided by SAP.
SECRET: Optional, alternative to SECRET_FILE. The secret used to encrypt the passwords. If neither SECRET nor SECRET_FILE is set, the passwords are stored in plain text.
SECRET_FILE: Optional, alternative to SECRET. File containing the secret used to encrypt the passwords. If neither SECRET nor SECRET_FILE is set, the passwords are stored in plain text.
SAP_SYSTEMS: Mandatory. 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: Name of the SAP system, used for logging purposes and future implementation of scenario SAP_COM_0467: Printing - Notification Integration. The length depends on the deployment: three characters for on-premise or private cloud systems, e.g. H22; seven characters for public cloud systems; for SAP BTP, any identifying string can be used, e.g. the Print Service instance's UI host name.
user: SAP technical user name. Not required for SAP BTP, where the OAuth client already identifies the print user.
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 Logon Data. Not required for SAP BTP.
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.
icmUseApiOnly: Whether the cache is retrieved exclusively via the SAP API Get_IcmCache, instead of the dynamic cache URL. Default is false.
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. For SAP BTP, the path uses an uppercase SAP segment instead: /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.
saveJSON : If true save original JSON document object from SAP as temporary file in the database for debugging purposes. Default is false.
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.

Examples¶

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.

Example - full YAML configuration

SAP_SYSTEMS: |
  - systemName: "My SAP System"
    client: "001"
    loginMethod: "oauth"
    user: "<username>"
    password: "<encryptedPassword>"
    authClientId: "cpm-checkin"
    authClientSecret: "<authClientSecret>"
    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
    saveJSON: true
    mappings:
      - sap: TEST1
        pls: printer4

Example - configuration for SAP BTP

SAP_SYSTEMS: |
  - systemId: "mysubaccount.ui.eu10.print.services.sap"
    loginMethod: "oauth"
    authClientId: "<authClientId>"
    authClientSecret: "<authClientSecret>"
    authIssuerUrl: "https://mysubaccount.authentication.eu10.hana.ondemand.com"
    scenario: "466"
    srvHostPort: "https://api.eu10.print.services.sap:443"
    srvPath: "/sap/opu/odata/SAP/API_CLOUD_PRINT_PULL_SRV"

Connects to the receiver service instance of the Print Service in the eu10 landscape, using the clientid, clientsecret and url values from its service key. srvHostPort uses the service_url value from the same key.

Example - full JSON configuration

SAP_SYSTEMS: |
  [
    {
      "systemName": "My SAP System",
      "client": "001",
      "loginMethod": "oauth",
      "user": "<username>",
      "password": "<encryptedPassword>",
      "authClientId": "cpm-checkin",
      "authClientSecret": "<authClientSecret>",
      "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`,
      "saveJSON": true,
      "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 specified PPD file.
Example - PPD file
```
ppd: "small-a4-a3.ppd"
```
The example results in selectable media sizes from ISO_A6 to ISO_A3 in the print job.

Test the Connection (Public Cloud)¶

This section applies to the public cloud SAP-side setup and assumes Configure the cpm-checkin Service above is already done.

Use the system URL, together with the user and password created earlier, to connect PLOSSYS Output Engine to the SAP S/4HANA system.
From the Maintain Print Queues app, create a few test pages without an assigned printer for the print queue. They should appear with status new in both SAP and PLOSSYS Output Engine.
Assign a physical printer to the print queue in PLOSSYS Output Engine.
The queued documents should print, and their status in SAP should change to successful.

Communication Scenario 466:Printing – Pull Integration¶