[external] Creating documents by using Aspose Template Syntax

External content by Markus Jenni; 17.04.2024
 

The "Generate/Update a Word file" action allows the creation of documents quite easily. In the past, we stumbled upon some challenges:

• Internal names of Test and Production can be different
  It happened that a report had to be redesigned for production as the properties are named after the internal names
• No Rich text content
• Styling a report has some limitations, especially when it is about tables
• For government organizations, the installation of the Word add-in can be challenging
• The Word Add-In is bound to a WEBCON BPS version
  When there are multiple environments with different versions, this can be a hassle

During the last partner day, Daniel Krüger gave me a look at how they use the Aspose Template Syntax. Have a quick look at the possibilities of the template syntax and become a big fan of it as I did.

Beginning of this year, we did a PoC and the first version of an SDK action. We decided to use JSON as a datasource, as in our opinion it offers the most versatile usage. 

For most users, more complex JSON structures, e.g. with one-to-many relations, will be a challenging task. So we decided to add a JSON-builder, that generates the structure based on the form fields. It is quite simple, but it also groups fields to its nearest grouping element (group, tab). Also, item lists, data tables, and data rows are supported. For most scenarios, this should be sufficient.
In addition, you can still create your own JSON, by whatever means you prefer.

Here is a simple example of how the template syntax looks like and the resulting output based on the JSON that has been generated by the JSON-builder

{
  "Hersteller": {
    "Hersteller": {
      "ID": "539",
      "DisplayName": "Musterfirma",
      "Translations": [
        
      ]
    },
    "Strassennummer": "28",
    "Strasse": "Mustergasse",
    "Zusatz": "",
    "PLZ": "1234",
    "Land": {
      "ID": "0f865973-11c9-4762-bf0c-839d2be05d89",
      "DisplayName": "Österreich",
      "Translations": [
        
      ]
    },
    "Ort": "Münster",
    "Firmenname": "Musterfirma"
  },
  "Produkt": {
    "Beschreibung_DE": "",
    "Untergruppe": {
      "ID": "4653778a-fbb2-44dc-b866-0c59844f025f",
      "DisplayName": "",
      "Translations": [
        {
          "LanguageCode": "de-de",
          "Value": "Dach - Blechprofile"
        },
        {
          "LanguageCode": "fr-fr",
          "Value": "Toiture - Profilés en tôle"
        },
        {
          "LanguageCode": "it-it",
          "Value": "Dach - Blechprofile"
        }
      ]
    },
    "Anwendungstext_DE": "<p style="text-align: center;"><span style="font-size: 16pt;">Demo</span></p><p style="text-align: left;"><br />Test mit <strong>Richtext und <span style="color: #e03e2d;">Formatierung</span></strong></p><p> </p><p style="text-align: center;"><span style="color: #333333;">Zentiert</span></p><p style="text-align: center;"> </p><p style="text-align: right;"><span style="color: #333333;">Rechtsbündig</span></p>",
    "Produktname_DE": "test",
    
  }
}

The Aspose template syntax does not allow using names with whitespace characters. So we replace whitespace by "_" and also remove "/".
E.g.
The fieldname "Produktname DE" becomes "Produktname_D". 
So it can be used in the template as <<[Produkt.Produktname_DE]>>

By using the Add-In, we 

• don't have to install an add-in
• can finally use rich text fields
• use a master document with CI/CD and content specific to a use case
• lots of other options we didn't use up until today

The SDK custom action has two configuration sections, one for the input and one for the output
 

1. The id of the word template (the original Webcon picker would be nice)
2. The type of JSON can be Standard or Custom
   Standard:
   Uses the JSON-builder
   Custom:
   Use your custom JSON
3. Define your custom JSON. You can use field values the way you are used to.
4. Name of the root element
   Only needed, when the root of the JSON structure is an array of elements

1. Mode: you can choose between Create and Overwrite
   If Overwrite is chosen, it will create a new version if a document with the same name exists.
2. Name of the generated document
3. Id/Name of the category, where the generated document should be saved
4. If empty, the generated document will be attached to the current element. Otherwise, it will be added to the defined element.
   This gives the possibility to generate a document in a different workflow than the document is being attached to.
5. The field where the ID of the generated document/attachment should be saved
   It is sometimes quite handy to know the ID of the generated document

The code for the SDK action is available on Nexplore Github.
Feel free to download, add the license file, compile, and use it!