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
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.
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.
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.
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 variabe.
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 exactly the same as the variable used in the Word template we created. It's very important that these variables have the same name in order 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 would 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 advance tags that you can use within these templates.