Welcome to @cap-js/print

About this project

The @cap-js/print package is a CDS plugin that provides print service features through integration with the SAP Print Service.

Table of Contents

Requirements and Setup

Using this plugin requires a valid subscription of the SAP Print Service.

Usage

To use this plugin to print documents, there are two main steps:

1. Ensure your model meets the requirements
2. Annotate your CDS model with @PDF.Printable

Model Requirements

• The attribute(s) you want to print are of type LargeBinary
• Those attributes have the annotation @Core.ContentDisposition: fileName, where fileName is the attribute that specifies the file name or a hardcoded string with the file name

Annotations in CDS model

To use the print plugin, annotate your entity with @PDF.Printable:

@PDF.Printable
entity Books as projection on my.Books;

This annotation does the following things in the background:

• Adds an action print to the annotated entity with the following parameters:
  • Queue: Name of the print queue to use.
  • Copies: Number of copies to print.
  • File: Only added if the entity has multiple LargeBinary attributes. Allows selecting which file should be printed. Ensure that the LargeBinary properties are annotated with @Common.Label.
• This action is added to the UI and a handler is generated to process the print request.
• An entity PrintServiceQueues is added to the service to provide available print queues in a value help.
• An entity PrintServiceFiles is added to the service to provide available files in a value help (only if multiple LargeBinary attributes exist).

Manual Usage

You can also use the print service to print documents manually, i.e., without the @PDF.Printable annotations and generated actions and handlers.

Use cases for a manual approach could be:

• You want to print documents that are not part of your CDS model, i.e., files generated at runtime.
• Your model does not meet the requirements for the automatic approach.
• You want to print a file type other than PDF.

For this, you can use the cds.connect.to API of CAP to connect to the print service and invoke the print action manually.

const printService = cds.connect.to("PrintService");

await printService.send("print", {
  qname: "Printer_Queue_Name",
  numberOfCopies: 1,
  docsToPrint: [
    {
      fileName: "file_name.pdf",
      content: "<base64-encoded-pdf-content>",
      isMainDocument: true,
    },
  ],
});

const queues = await printService.get("/Queues");

It is possible that for LargeBinaries retrieved from the database, the content is provided as a stream. In this case, the stream needs to be converted to base64 before passing it to the print service. For example, see the sample application in test/bookshop/

Local Development

When running the application locally, the print service is mocked. This mock implementation prints the print job details to the console instead of sending them to the actual print service. It also provides a number of sample print queues for selection.

Hybrid Testing

You can also run the application locally with a binding to the cloud print service with CAP profiles. For more information, see Hybrid Testing. You need an instance of the SAP Print Service.

Local

As the hybrid profile of the plugin uses SAP HANA Cloud to execute integration tests in CI, a profile local is added that can be used to execute the application locally with a binding to the cloud print service.

# Once as setup
cd test/bookshop
cds bind -2 <print-service-instance-name> -4 local
# Run the application (from the root)
npm run watch-sample:local

CI

For CI, the hybrid integration tests are automatically run against a SAP Print Service instance and a SAP HANA Cloud instance created for testing purposes.

Support, Feedback, Contributing

This project is open to feature requests/suggestions, bug reports, etc. via GitHub issues. Contributions and feedback are encouraged and always welcome. For more information about how to contribute, the project structure, as well as additional contribution information, see our Contribution Guidelines.

Security / Disclosure

If you find a bug that may be a security problem, please follow the instructions in our security policy on how to report it. Please do not create GitHub issues for security-related doubts or problems.

Code of Conduct

We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone. By participating in this project, you agree to abide by its Code of Conduct at all times.

Licensing

Copyright 2025 SAP SE or an SAP affiliate company and print contributors. Please see our LICENSE for copyright and license information. Detailed information, including third-party components and their licensing/copyright information, is available via the REUSE tool.