Using action steps
      Back to home
      1. Betty Blocks Documentation
      2. Use-case guides
      3. Using action steps

      Document generation step

      Learn how to generate Word documents with a template that uses data from your data model.

      After reading this article you'll know:

      • What generating a document is all about

      • Why you'd use the document generation step

      • How to use the document generation step in your application

      Getting started

      The generate document step can be found in the Block Store and is used to generate a document based on a template and data from your data model. To find the step go to the block store and search for 'document', the document generation step should pop up.

      Click on View details followed by Install block to install the block to the appropriate organization and application.

      Once installed we can use the step in our application.

      Starting off

      Let's create the following use case to practice how this step works. We want our employees to be able to download a Word document that automatically gets generated with their own data.

      For this, we need a model called 'Employee'. This model will contain the following properties:

      • Text (single line) 'Name', required

      • Email address 'Email address', has to be unique & required

      • Date 'Date of birth', format DD/MM/YYYY

      • File (Information document), allowed file extension

      With the model in place we can go to the next step; note that this model is a bit plain. Feel free to add more properties to give it a bit more body if you like.

      With this model in place, we can continue to the next step, which is creating a Word template to work with. Check out this link to learn more about the syntax for creating Word templates.

      For this example, I've created this template:
      ​

      Now there are two ways to use this template, we can add the template as a property into our model, or use the public files feature. In this use case, I'll use the latter. So, let's navigate to the public files overview, located in the Tools section.

      We can then click on the Upload new file button and upload our template.

      Hit Save to save the template and make sure to copy the URL, we'll use that in the next step.

      Which is to create an action that'll dynamically create this template with the data of one of the employees within the 'Employee' model.

      Generating the document

      Start off by creating a new action called something like 'Generate document'. Let's add an input variable, we'll generate a document with an employee's data based on their id. Create an input variable in the Start step like so:

      We can then based on this input variable create an object of the employee based on the ID. We'll need that object in our action to determine where to save the generated document and also what information we'll need to display beside the employee's ID. Create a new variable - not an input variable - in the start step, don't forget the add a filter for this variable.

      After adding the 'employee_object' to the Start step, we can drag the Document generation step into our action flow. Select the model and the property where the generated document has to be saved. Paste the URL of the public file template we just created. Name the file, in our case 'Information', will suffice. You could use the Expression step to create a dynamic name, for example, include an employee's name in the filename or his number.

      You can also see in the image above that the template variables are the same as the variable used in the Word template we created. These variables must have the same name for this step to function properly.

      The second part of the action is updating the employee with his new file. Add an Update step after the Generate document step.

      Configure the Update step like the image above.

      If we test this action, it should generate a new document dynamically with the data of an employee that we can specify ourselves based on the employee's ID.

      Let's try it out, click on the Test run button in the top-right corner. Copy the mutation and query variables over and paste them into the playground.

      I have a few employees already present in my model. In this example I'll choose the employee with ID number 3, this is Menouer. Make sure to change the Number value from the query variable to an actual ID like '3'.

      We can see that the action ran successfully and that a file has been created called 'Information.docx'. The URL that has been created is a link to that file, to verify that our action step works we can simply copy this URL into the browser and it should download the generated file automatically.

      And there we go, the newly generated file that's been saved to our employee has been downloaded, if we open it we can check if his data is within this document.

      And there we go, our document has successfully been generated and contains the data that we expect it to contain.

      This is of course a super basic example, you can create way more dynamically advanced documents with this step. Make sure to give this link a proper read to learn more about the advanced tags that you can use within these templates.