Specifications often needs to leave the platform where they were elaborated :

• To be shared with a 3rd party actor that cannot have access to the platform for security / network reasons.
• Because they are required by a customer, for instance when specifications are made by a supplier for a customer and customer wants to consolidate / compute coverage on its own (for instance with things like Reqtify).
• Because they are requested for audit purpose.

Those documents should look like Company documents in term of colors, images, headers and footers. The solutions to export to docx with the necessary level of formatting led to a dead end (see art #32665) so the current strategy will be to :

• export to PDF with Company look and feel
• export to docx "naked"

Export to PDF

Investigations made in art #32665 showed that the best approach is to leverage on the ability of the browser to generate a PDF. There are some limitations, mainly on the ability to have page numbers in the Table of Contents. However, user interview made with users that are used to concurrent product like Confluence did not raise this as major problem (if any).

Define a template

We need to be able to define :

• a cover page, including images
• styling and colors for headings and paragraphs
• headers and footers with images and user defined text

The definition of a template is done in HTML / CSS (with code mirror ?)

1. One section for cover page
2. One section for general styling
3. One section for headers
4. One section for footers

There is also the ability to upload images that will be used in the template. A template must have a name and has an optional description.

On template definition page, there is a Preview button that allows to test the rendering of the PDF with «Lorem ipsum» content.

When a new template is created, a default content is proposed that corresponds to a Tuleap template. The goal is to provide a working example that template administrators can use as a starting point to develop their own templates. It's also possible to duplicate an existing template.

In addition to template definition, several metadata are collected and displayed (on template view):

• Last author (user)
• Last update date

At each template modification, an application log is recorded with the user who did the change, the date of change, the template id, template name and which fields where changed.

Site wide templates

Templates will be a bit tedious to build so it's expected that a handful of person will develop the initial template that will be reused across the company. However, it's very unlikely that site administrators will have the skills to build the templates (HTML and CSS at a level that is not basic). In addition to that, we cannot promote the sharing of templates across projects because it would engage to a dangerous path where confidential info about project names or people names could be leaked. We choose to address these problems by defining templates at site admin level with a new, dedicated, permission.

In this first user story, templates can only be defined at Site level, the ability to define templates at project level will come in the future. The goal is to cover the most common use case (company wide shared templates).

Applying a template to a document

On an Artidoc, in the carret menu, there is an option to export to PDF. Anyone who can read the document can export it to PDF. The user who does the export have the possibility to choose a template to apply to the document.

The user must select the template each and every time the export is done.

If no template is defined at site admin level, the ability to export to PDF is displayed "disabled" with an info "No template was defined for export, contact site administrator"

User must be registered to export to PDF (otherwise the content of templates are exposed to anonymous)

Non requirements

This story is a first implementation and some features are excluded to better collect the actual need and, more important, verify that we address the right problem, the right way. Things that are not covered:

• Variables. It's possible that some metadata will be required inside the template (for instance the document owner might be needed in the header / footer).
• Produce the PDF server side. The current strategy is to leverage on the browser print features with specific stylesheet. In a longer term, we might imagine to do the rendering server side with headless chromium. However that requires the deployment of a lot of things for On Premise deployments. We should ensure that the overall process and rendering is OK for end users before going this way (if we really have to).
• Have templates at project level. It's possible that some projects might need specific templates, for instance to produce docs that looks like a template requested by a customer. But at the moment we don't know if this requires to have the need to treat it separately. If really needed, it could be done either by having a concept of site wide templates, restricted to some projects (as we do when we restrict plugin usage), or to have templates defined at project level.