Template-based PDF generation via API

[blizzz]

Is your feature request related to a problem? Please describe.

Through an API endpoint, it shall be possible to create a PDF document based on a template with placeholders.

Describe the solution you'd like

An OCS endpoint accepts

• a folder id to store the resulting document
• a template identifier
• a json parameter with key-value-pairs for the placeholders

The app will on-the-fly create a new document, do the replacements, and store it as a PDF document.

Additional context

This is required for the upcoming workflow engine efforts.

[juliushaertl]

Would be good to evaluate together with Collabora if this could just be done by extending the convert to endpoint they have, as this would also allow doing conversions to various file types right away https://www.collaboraoffice.com/document-conversion/

[juliushaertl]

a template identifier

Has there been some discussions on how templates are defined? I assume they'd just be another Nextcloud file so a file ID is probably best for this one?

[juliushaertl]

Could also be the same backend mechanism as for https://github.com/nextcloud-gmbh/office-team/issues/51

[blizzz]

a template identifier

Has there been some discussions on how templates are defined? I assume they'd just be another Nextcloud file so a file ID is probably best for this one?

Not specified more closely, my assumption was to use the existing mechanism. If that works with file id, file id it is.

[juliushaertl]

Basic implementation idea:

• Some service class in richdocuments with two methods (extractFields(Node $file): ?array/fillFields(Node $file, array $fieldValues))
• OCS Controller to expose those as an API with two possible modes
  • Send file data directly
  • Send a file id for an existing file in Nextcloud
  • Have a parameter target to either write the target file to or return the file if left out

The service can then be reused for https://github.com/nextcloud-gmbh/office-team/issues/51

[juliushaertl]

For reference the early draft from Collabora:

If you want to experiment early, we expect the API would look like this:

1) Extraction

• new /cool/extract-doc-structure?limit=content-control endpoint

• we'll add more document structure here, emitting everything by
  default, but you want to limit to content controls probably

• takes a document

• outputs a JSON like this:

{
   "DocStructure": {
       "ContentControls.ByIndex.0": {
           "id": -1318486635,
           "tag": "machine-readable",
           "alias": "Human Readable",
           "content": "plain text value",
           "type": "plain-text"
       },
       "ContentControls.ByIndex.1": {
           "id": 80127134,
           "tag": "name",
           "alias": "Name",
           "content": "",
           "type": "plain-text"
       }
   }
}

Note that all of id/tag/alias is optional to allow working with existing
DOCX templates, so worst case you only get an index to refer to the form
controls.

2) Filling a template

• this will be a new transforms parameter for the existing
  /cool/convert-to endpoint

• takes a document and a transforms HTTP form parameter, where the value
  is again a JSON

• that JSON looks like this:

{
   "Transforms": {
       "ContentControls.ByIndex.0": {
           "content": "new value for the first content control"
       },
       "ContentControls.ByTag.name": {
           "content": "John Smith"
       }
   }
}

This always allows referring to content controls by index; if you have a
nice template where a unique tag is provided for each content control,
then you can have a more readable transforms JSON where you refer to
content controls by tag names.