Before building a form in AlayaCare for which you wish to use a custom template, you should design what you want the final output to look like and set the field tags that you will use in AlayaCare. This will then indicate how data should map from the fields on the form, to the fields in the template.
AlayaCare uses Docmosis as our document generation software. To create a custom PDF template, you will need to follow Docmosis' syntax and conventions to ensure that data maps correctly from the form fields to the template fields. For best results, AlayaCare recommends that Docmosis templates are designed using the open-source word processor LibreOffice. However, it is also possible to create the templates using Microsoft Word.
Creating the Docmosis template
1. To begin, click here to download LibreOffice for free.
2. Review the official Docmosis template user guide, which can be found here.
3. If you are starting with an existing PDF template, you will need to start by converting the file from .pdf to .odt. To convert the file to .odt, use the use the Convertico file converter. Once you have converted the file, open it in LibreOffice. Make sure to review the converted file carefully as some issues can occur when converting between formats. Note that fillable PDFs tend to convert more seamlessly to .odt format.
4. Customize the design of your template in LibreOffice. We recommend that you enter fake data in the template fields during the design phase to help you visualize what the final output will look like.
5. After you have designed your template, you will need to map how data from AlayaCare will populate in the template fields. To do this, replace the fake data in your template with the correct tag for the field in the accepted Docmosis format. These tags will be used to connect each template field to a field on the form in AlayaCare.
With fake data:
With Docmosis tags added:
6. When adding field tags to template fields that will map to fields in the form created in AlayaCare, you must add before the field tag name in your Docmosis template. The names of the fields must match exactly for the output to be successfully generated. Note that field tags cannot begin with a number or underscore (_) or contain special characters. Use underscores (_) instead of spaces (snake case). See the example below of the field tag in the form builder and how it is mapped in the corresponding template:
Field on template:
Field tag on AlayaCare form:
7. Some fields can be added to Docmosis templates without needing to use field tags on forms to populate them with the correct data. The following fields can be added to templates without using field tags or the fields format:
- agency_address: the address of the agency.
- agency_logo: the agency logo.
- agency_name: name of the agency.
- approved_by: name of the employee the submitted form was approved by.
- approved_on: date and time that the submitted form was approved.
- alayacare_id: AlayaCare ID of the client.
- brn_number: BRN number of the client's service.
- client_name: name of the client the form was submitted for.
- date_of_birth: the client's date of birth.
- external_id: the client's external ID.
- form_name: the name of the submitted form.
- gender: the client's gender.
- id: the identification number of the submission.
- phone_number: the client's phone number listed in AlayaCare.
- printed_on:date and time at which the form was printed.
- updated_at: date and time at which the form was updated.
- service_address: address at which the visit occurred.
- service_address_type: the address type (for example, client address).
- submitted_by: the employee the form was submitted.
- submitted_on: the date and time at which the form was submitted.
- timezone: time zone used for the dates and times.visit_start_at: Scheduled start time of the linked visit
- visit_end_at: scheduled end time of the linked visit
- work_session_start_at: clocked start time of the linked visit
- work_session_end_at: clocked end time of the linked visit
- visit_verified_start_time: verified/adjusted start time of the linked visit if approved through electronic visit verification
- visit_verified_end_time: verified/adjusted end time of the linked visit if approved through electronic visit verification
To pull this information into the template from AlayaCare, simply add the tag between << and >> (Date of Birth: <<date_of_birth>>).
Additionally, users will now be able to add custom form context fields that exist on the client profile to their custom form templates. The format to add to the docmosis template is <<client.form_context_tag>>.
For example, the form context field "Pets Name" can be captured on a custom form template using the tag <<client.pets_name>>, as seen in the sample below.
8. Some form components require more complex Docmosis syntax to populate correctly in the template:
Checkboxes
For data to render correctly in checkbox format, the following Docmosis syntax should be used within LibreOffice: <<cs_{fields.fieldtag==true}>>☒<<else>>☐<<es_>> . Replace any checkboxes in the template with the above syntax. See the example below:
Field tag on form:
Checkbox field on template:
Images (drawings or photos)
For images to appear correctly in a Docmosis template, you must add a placeholder image to the template, set a variable in the image properties, and then use Docmosis syntax to indicate that you wish to replace that image with the data from a particular form field.
The following placeholder image can be used when designing a form with images:
To set the variable on the image, right click on the image and select properties.
In the name field, write imgfit_var_ followed by the variable you wish to use (for example, imgfit_fields.fieldtag).
The syntax you should use is <<$variable=fields.fieldtag>> given that variable is the variable set on the image in the template and fieldtag is the field tag that will be set for the field on the form in AlayaCare. See the example below:
Field in template:
Image properties (variable = w1)
Signatures
Signatures should be treated the same way as images in Docmosis templates. Add an example image to your template where the signature should populate, create a variable in the image properties, and use the correct syntax to indicate that the image should be replaced in the template with data from the correct form field.
You can use the image below as a placeholder image for signatures:
The correct syntax is <<$variable=fields.fieldtag>> given that variable is the variable set on the image in the template and fieldtag is the field tag that will be set for the field on the form in AlayaCare. See the example below:
Field tag on form:
Field in template:
Image properties (variable = s4):
Hyperlinks
To map a hyperlink field to a template field, use the following syntax: <<link: fields.fieldtag>> where fieldtag is the name of field tag for the form field for which you wish to insert a hyperlink. This syntax indicates that a hyperlink should be inserted using the URL from the data entered in the field with the specified field tag.
9. Form comments: if you wish to capture comments added to the form after it is submitted in the template, you will need to add a comments section to the template. To allow form comments to appear in the template in chronological order, enter the following in the comment box on the template: <<cs_{isBlank(comments.comment)}>> This form has no comments. <<es_>> <<rs_comments>> <<create_user>> | <<created_at>> <<html:comment>> <<es_comments>>
To add a chart to your template, simply add a table and customize it the way you ordinarily would in LibreOffice. Then enter the field tags using proper Docmosis syntax.
Once you have designed the template, you can proceed to add your field tags to the form in AlayaCare that requires a custom template.