Configuration

This API provides 2 primary functionalities.

PESC to HTML - Provide a pesc xml transcript and transform into a standard html transcript layout. This can be rendered in a Website UI and localized for any language.

PESC to PDF - Takes the html output, and performs an additional step of rendering into a PDF to be viewed, download, and/or printed.

PESC CDL API (to html)

CDL (Common Digital Layout) is an agreed upon style for displaying PESC xml as a transcript. This services primary functionality is taking the PESC XML and transforming it into an html document. This docker service provides the extensibility to fully customize the transform and html styles.

Feel free to review the default CDL assets directory, which is copied verbatim into the docker image. Those assets provide all the logic to transform, layout and styling for the html output.

The following section lets you configure an additional directory where you can place any files in to override the default CDL assets.

Environment Variables

Name	Default Value	Description
ConnectionStrings__CdlStorage	null	Optional, if present, all contents are copied to the default cdl assets and overwrite if necessary.

Valid Connection Strings

We leverage some Blob providers of FluentStorage to allow for a flexible number of options for overriding the built in XSL Transformation, HTML and css styling of the HTML output. Our hope is that the CDL established offers everything that is necessary, but should you want to customize it, then you will need to determine what assets to modify here, or possibly add additional assets (For example, another language). If adding another language, we would accept a pull request and contributions, so the open source community can benefit from the efforts.

Provider	Sample Connection String
Local Disk	disk://path=path_to_directory
AWS S3	aws.s3://keyId=...;key=...;bucket=...;region=...
Google Cloud Storage	google.storage://bucket=...;cred=...
Azure File	azure.file://account=account_name;key=secret_value
Azure Blob	azure.blob://account=account_name;key=secret_value or azure.blob://development=true

Example cdl assets override

We will create 2 files and a directory to look like this:

./your-workspace/docker-compose.yml
                /cdlassets/styles/Styles.xml

And first the contents of the Styles.xml, add a body tag at the top:

footer.html
<?xml version="1.0" encoding="utf-8"?>
<Styles>
    <Transcript>
    body {
        background-color: red;
    }
    ...Rest of default styles omitted, but should be present in your file, remember it overrites the default one
    </Transcript>
</Styles>

And then

docker-compose.yml
services:
  # Your other services.
  
  gotenberg:
    image: gotenberg/gotenberg:8

  cdl:
    image: canpesc/cdl:latest
    environment:
      - GotenbergSharpClient__ServiceUrl=http://gotenberg:3000
      - GotenbergSharpClient__HealthCheckUrl=http://gotenberg:3000/health
      - ConnectionStrings__pdfStorage=disk://path=/usr/local/pdf
    ports:
      - "4000:8080"
    volumes:
      - ./cdlassets:/usr/local/cdl

now, in that directory run the command

docker-compose up

Then you should be able to navigate to http://localhost:4000, Test the html or pdf endpoint with the UI, and see the background is indeed red.

PDF conversion (to pdf)

Very similar to the CDL assets, PDF output has some assets that are specific to generating the pdf document. They can be overridden through the technique outlined in this section.

Feel free to review the default PDF assets directory, which is copied verbatim into the docker image. As of writing this, the assets are 2 files header.html and footer.html

The following section lets you configure an additional directory where you can place any files in to override the default CDL assets.

Environment Variables

Name	Default Value	Description
ConnectionStrings__PdfStorage	null	Optional, if present, all contents are copied to the default pdf assets and overwrite if necessary.
PdfAssets__PdfHeader	header.html	Set the name for the header.html file used in pdf generation
PdfAssets__PdfFooter	footer.html	Set the name for the footer.html file used in pdf generation
GotenbergSharpClient__ServiceUrl	null	Set the url where the gotenberg api is available
GotenbergSharpClient__HealthCheckUrl	null	Set the health check url where the gotenberg api is available
GotenbergSharpClient__RetryPolicy__Enabled	true	Enable Polly retry.
GotenbergSharpClient__RetryPolicy__RetryCount	4	Set the retry count.
GotenbergSharpClient__RetryPolicy__BackoffPower	1.5	Set the factor for exponential backoff on the retries
GotenbergSharpClient__RetryPolicy__LoggingEnabled	true	Enable logging for polly.

** GotenbergSharpClient ** This is the client used to initiate conversion from Html to Pdf. Pdf conversion is an opt-in feature, but if you use it, there's some additional configuration available. Leaving these values as the default is suitable for most cases. Additionally, Gotenberg container itself has configuration as well.

Valid Connection Strings

Provider	Sample Connection String
Local Disk	disk://path=path_to_directory
AWS S3	aws.s3://keyId=...;key=...;bucket=...;region=...
Google Cloud Storage	google.storage://bucket=...;cred=...
Azure File	azure.file://account=account_name;key=secret_value
Azure Blob	azure.blob://account=account_name;key=secret_value or azure.blob://development=true

Example pdf assets override

We will create 2 files and a directory to look like this:

./your-workspace/docker-compose.yml
                /yourpdfassets/footer.html

And first the contents of the footer.html:

footer.html
<html>
<head>
    <style>
        body {
            font-size: 8pt;
            margin: auto;
        }

        .container {
            display: flex;
            justify-content: space-between;
            width: 100%;
        }
    </style>
</head>
<body>
    <div class="container">
        <div style="margin-left: 20pt;">SOME CUSTOM FOOTER</div>
        <div style="margin-right: 20pt;">Page <span class="pageNumber"></span> of/de <span class="totalPages"></span></div>
    </div>
</body>
</html>

If you are wondering how the page numbers are substituted in, and more, then please review all the possible header and footer configuration here.

Next create the docker compose file:

docker-compose.yml
services:
  # Your other services.
  
  gotenberg:
    image: gotenberg/gotenberg:8

  cdl:
    image: canpesc/cdl:latest
    environment:
      - GotenbergSharpClient__ServiceUrl=http://gotenberg:3000
      - GotenbergSharpClient__HealthCheckUrl=http://gotenberg:3000/health
      - ConnectionStrings__cdlStorage=disk://path=/usr/local/cdl
    ports:
      - "4000:8080"
    volumes:
      - ./yourpdfassets:/usr/local/cdl

now, in that directory run the command

docker-compose up

Then you should be able to navigate to http://localhost:4000, Test the html or pdf endpoint with the UI, and see the footer with the changed values.

info

Both examples used the local disk storage, and a mounted volume. If you wanted to use one of the other storage providers, you would have to put the file into the resource, then provide just the connection string environment variable. You would omit the mounted volume from the docker compose.

Configuration

PESC CDL API (to html)​

Environment Variables​

Valid Connection Strings​

Example cdl assets override​

PDF conversion (to pdf)​

Environment Variables​

Valid Connection Strings​

Example pdf assets override​

PESC CDL API (to html)

Environment Variables

Valid Connection Strings

Example cdl assets override

PDF conversion (to pdf)

Environment Variables

Valid Connection Strings

Example pdf assets override