Printing

Put yourself in the shoes of a poetry slam manager who uses a poetry slam management application to manage the events. Instead of creating, viewing and downloading forms, you want the guest list to be directly sent to a physical printer. Because your printer is located in your customer landscape, an SaaS cloud application like the Poetry Slam Manager will not have direct access to the printer. To support printing, SAP BTP offers the SAP Print Service. It consists of several parts:

The Print Service with service plan sender is a service that runs in the provider subaccount and allows you to assign documents to print queues. Print queues are the consumer-subaccount-specific storage of documents waiting to be printed.
The Print Service with service plan standard is an application that runs in a consumer subaccount and allows you to create and manage the print queues.
The Print Service with service plan receiver is a service running in a consumer subaccount. It provides the credentials to pull documents from SAP BTP to the customer landscape.
The Print Manager is a Windows application that runs on a customer's computer. It regularly pulls documents from print queues (using the receiver credentials) and sends them to a local printer.

The next sections describe how the components are used and configured.

To explore this feature with the Poetry Slam Manager, you have two options:

Clone the repository of the Partner Reference Application. Check out the main-multi-tenant branch and enhance the application step by step.
Alternatively, check out the main-multi-tenant-features branch where the feature is already included.

The following describes how to enhance the main-multi-tenant branch (option 1).

Enabling Printing in the Poetry Slams Application

As you will print the guest list which you created based on chapter Manage Forms follow all enablement steps described there first.
Generate access classes to the SAP Print Service API.
1. Download the definition of the SAP Print Service API which you can find on the overview page under API Specification as JSON .
2. Copy the downloaded openAPI definition file (PRINTAPI.json) to the folder external_resources.
3. Add a prebuild script to your package.json. This will generate the access classes out of the uploaded definition whenever you run the npm run build command. If you need to execute several commands in the prebuild step, you can concatenate them with &&.
```
"prebuild": "npm ci && npx openapi-generator --input external_resources/PRINTAPI.json --outputDir srv/external -t --overwrite && npx openapi-generator --input external_resources/FORMSAPI.json --outputDir srv/external -t --overwrite",
```
4. Add the folder for the generated files to .gitignore.
```
# generated openapi artefacts
srv/external/
```
5. Add @sap-cloud-sdk/openapi to the dependencies of your package.json by running npm add @sap-cloud-sdk/openapi.
6. Add @sap-cloud-sdk/openapi-generator to the devDependencies of your package.json by running npm add -D @sap-cloud-sdk/openapi-generator.
7. Run the command npm install in your project root folder to install the required npm modules for the application.
8. Run npm run prebuild to generate the access classes.

Extend your service by an action Print Guest List.

Extend srv/poetryslam/poetrySlamService.cds with a new action printGuestList. The action has a parameter printQueue. The calculated entity PrintQueues is used for the value help of the action parameter:

...
entity PoetrySlams as
    ...;
    actions {
        ...;
        // Action: print visitor list
        action printGuestList(
                    @(
                      title:'{i18n>selectPrintQueue}',
                      mandatory:true,
                      Common:{
                        ValueListWithFixedValues: true,
                        ValueList               : {
                          $Type         : 'Common.ValueListType',
                          CollectionPath: 'PrintQueues',
                          Parameters    : [
                            {
                              $Type            : 'Common.ValueListParameterInOut',
                              ValueListProperty: 'name',
                              LocalDataProperty: printQueue
                            },
                            {
                              $Type            : 'Common.ValueListParameterDisplayOnly',
                              ValueListProperty: 'descr'
                            }
                          ]
                        },
                      }
                    )
                    printQueue : String);
    };

// PrintQueues (virtual entity for value help)
@readonly
@cds.persistence.skip
entity PrintQueues {
    key name  : String;
        descr : String;
};

Provide an implementation for the action in srv/poetryslam/poetrySlamServiceOutputImplementation.js

const { getPrintQueues, print } = require('./util/print');
...
module.exports = async (srv) => {
    ...
    // Entity action "printGuestList": Create a Form (PDF) and send it to the Print Service
    srv.on('printGuestList', async (req) => {
        ...
    });
    // Virtual Entity PrintQueues
    srv.on('READ', 'PrintQueues', async () => {
        ...
    });
};

Copy the implementation of srv/poetryslam/util/print.js. This file contains the logic to call the Print Service APIs (read print queues, create documents, create print tasks).

Provide translatable messages for your implementation in srv/i18n/messages.properties. Add the corresponding translation to the language-specific file srv/i18n/messages_de.properties.

ACTION_PRINT_NO_ACCESS                                  = Access to print service not possible.
ACTION_PRINT_NO_QUEUE                                   = No print queue available.
ACTION_PRINT_NO_DOCUMENT                                = Document could not be sent to print queue.
ACTION_PRINT_NO_PRINTTASK                               = Print task could not be created.
ACTION_PRINT_FAIL                                       = Printing not possible.
ACTION_PRINT_SUCCESS                                    = Document "{0}" sent to print queue "{1}".

Use the implementation in srv/poetryslam/poetrySlamServiceImplementation.js

const outputHandler = require('./poetrySlamServiceOutputImplementation');

module.exports = cds.service.impl(async (srv) => {
    ...
    await outputHandler(srv); // Forward handler for output
    ...
});

Add the action to the user interface of your application.
1. Add an action to the Poetry Slam Object page by annotating Identification of the UI of service.PoetrySlams in annotations.cds:
```
// Print the guest list
{
  $Type : 'UI.DataFieldForAction',
  Action: 'PoetrySlamService.printGuestList',
  Label : '{i18n>printGuestList}',
  ![@UI.Hidden]: {$edmJson: {$Not: {$Path: 'IsActiveEntity'}}}
}
```
  Note: The action is only available for saved poetry slams, not for drafts.
2. Provide the translatable texts for the button label, action parameter and file name in srv/i18n/i18n.properties. Add the corresponding translation to the language-specific file srv/i18n/i18n_de.properties.
```
printGuestList          = Print Guest List
selectPrintQueue        = Select Print Queue
guestList               = Guest List
```

SAP BTP Configuration and Deployment

Add the Print Service as a resource to your application.

Add the resource in mta.yaml.

modules:
- name: poetry-slams-srv
    requires:
    - name: poetry-slams-print-service

- name: poetry-slams-mtx
    requires:
    - name: poetry-slams-print-service

resources:
  # Print Service
  - name: poetry-slams-print-service
    type: org.cloudfoundry.managed-service
    parameters:
      service: print
      service-plan: sender

Ensure subscription for multi-tenancy in mtx/sidecar/package.json.

  "cds": {
    ...
    "requires": {
      ...  
      "poetry-slams-print-service": {
        "subscriptionDependency": { "uaa": "xsappname" }
      }
    }
  }

Add the entitlement for the "Print Service", plan "sender" to your provider subaccount.
Build the application and deploy it to your provider subaccount.

Note: If the application was already deployed in a previous step, you need to update the subscriptions of the application. For more information on the subscription manager, refer to Test and Troubleshoot Multitenancy.

Configuring Printing in Consumer Subaccounts

To use the print functionality, you have to maintain a print queue which is the cloud storage for documents to be printed.

In the SAP BTP cockpit of the consumer subaccount, in the Entitlements, use Edit and Add Service Plans to add the service Print Service with plan standard (Application). Save this change to Entitlements.
In Instances and Subscriptions of the consumer subaccounts, create a subscription for plan standard.
In Security -> Role Collections create a role collection PrintQueueManager. Edit this role collection, add the role "PrintQueueSuperUser" and add Users and/or UserGroups who should be entitled to maintain print queues.
In Instances and Subscriptions create an instance of Print Service plan receiver.

Note: The instance name must have a length of no more than 12 characters and may consist only of letters, digits and underscore. You may choose pq_access.
For the created instance pq_access, use the action to Create Servince Binding. Use the name access_key.
In Instances and Subscriptions, section Application, click the link Print Service.
1. Click Manage Print Queues.
2. Click Create.
3. Enter a name, for example print_queue_consumer_01.
4. Enter a description, for example Print Queue for Consumer Subaccount 01.
5. Enter format PDF.
6. Choose print user pq_access.
7. Choose Save.

Next, you and/or your customer need to install the SAP Print Manager for Pull Integration to regularly read the print queue and send the documents to a printer. Follow the documentation about Establishing the Connection Between SAP Print Service and SAP Cloud Print Manager for Pull Integration.

Testing

Local Testing

To test locally (from within SAP Business Application Studio), you can connect the "local" application (started with cds watch) with a deployed print service and a subscription.

Go to your provider subaccount in the SAP BTP cockpit and navigate to the Cloud Foundry space.
Click the link of the application called poetry-slams-print-srv.
Go to the Environment Variables and copy the whole json structure containing the attribute "VCAP_SERVICES".
Go to the consumer subaccount and note down the Tenant ID.
Create a file default-env.json on the root folder of your project in the Business Application Studio. Copy the previously copied values into this file:
```
{
    "VCAP_SERVICES": {
        "print": [
            ...
        ],
        "adsrestapi": [
            ...
        ]
    },
    "test_tenant_id": "<Tenant ID of the consumer tenant to test with>"
}    
```
Note: Since you are using the guest list that you created based on chapter Managing Forms, you will need both sections for print and adrestapi.
Run the application using cds watch from a terminal within SAP Business Application Studio. You can use a terminal of type JavaScript Debug Terminal for easy debugging.

Unit Tests for Printing

To support automatic testing of the print feature, a sample unit test implementation is provided in print.test.js. The test uses stubs to decouple from the external services.

To run the automated SAP Cloud Application Programming Model tests:

Enter the command npm install in a terminal in SAP Business Application Studio.
Execute the command npm run prebuild to run the forms API generator.
Enter the command npm run test. All tests are carried out and the result is shown afterwards.

A Guided Tour to Explore the Print Feature

Now, take a tour through the print feature of Poetry Slam Manager:

Open the SAP BTP cockpit of the customer subaccount.
Open the Poetry Slams application of the Poetry Slam Manager.
If the list of poetry slams is empty, click the button Generate Sample Data and choose Go to refresh the list. As a result, a list with several poetry slams is shown.
Open a poetry slam and click the button Print Guest List in the menu of the object page. On the popup, select a print queue and choose Print Guest List. A popup confirms that the guest list was sent to the selected print queue.

Note: If no print queue is available from the drop down list box, go back to the paragraph Configuring Printing in Consumer Subaccounts and maintain a print queue as described there.
When you open the print queue from the application Print Service available in the consumer subaccount, you will find the printed document.
You can install the SAP Cloud Print Manager for Pull Integration on your local computer to regularly pull documents from print queues and send them to a local printer.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

44b-Multi-Tenancy-Features-Print.md

44b-Multi-Tenancy-Features-Print.md

Printing

Enabling Printing in the Poetry Slams Application

SAP BTP Configuration and Deployment

Configuring Printing in Consumer Subaccounts

Testing

Local Testing

Unit Tests for Printing

A Guided Tour to Explore the Print Feature

Files

44b-Multi-Tenancy-Features-Print.md

Latest commit

History

44b-Multi-Tenancy-Features-Print.md

File metadata and controls

Printing

Enabling Printing in the Poetry Slams Application

SAP BTP Configuration and Deployment

Configuring Printing in Consumer Subaccounts

Testing

Local Testing

Unit Tests for Printing

A Guided Tour to Explore the Print Feature