Troubleshooting Dynamics

The intention of this article is to troubleshoot Dynamics issues. In many cases the validation in Template Designer or the Admin Center shows an error message if a template is configured incorrectly. However if no error message is shown this guide can help you to find a solution.

Generic issues

Creating a new template or uploading a template fails

When you open Template Designer the message 'Generated by Templafy' is shown, or when you upload a template to the Admin Center the message 'Processing document failed' (Word document) or 'Processing presentation failed' (PowerPoint presentation) is shown:

This happens when the document has been generated with Templafy. A generated document contains document specific information, like the document properties TemplafyTenantId, TemplafyTemplateId and TemplafyUserProfileId. You should not use a document  as base for a template.

The recommended solution is that the Space owner downloads the original template from the Admin Center, makes the desired changes to it and then replaces the current version.

If you want to create a new template from scratch then always choose MS Themes > Blank document or MS Themes > Blank presentation. Do not use New document or New presentation on the Home tab, as this will create a Templafy document/presentation and you'll get the same message shown above. 

Fields are not shown on the Template tab (PowerPoint)

When a PowerPoint template contains grouped shapes, then the smart fields of these grouped shapes are not shown in Template Designer Template tab. You have to ungroup them to see the smart fields. This behavior is described in the PowerPoint best practices article.

Document looks different in Word Web App

When you edit a document in Word Web App, the document is presented in Editing view so that you can edit and format text. Editing view doesn’t show page formatting, such as margins or page breaks, cover pages, or headers and footers. Additionally, many kinds of objects are displayed as placeholders. For a full overview of the differences between Word Web App and Word Desktop, read the Microsoft article.

To see the right formatting of your document, you should open it in Reading View of the Word Web App. In the example below the logo is misplaced in Editing view, and is showing correctly in Reading view.

To switch from Editing to Reading view, click Viewing from the menu:

You can also open the document in Word Desktop by selecting Open in Desktop and have the full Word experience.

Message 'Rich text controls cannot be applied here'

When creating a group from the selected text below the message 'Rich text controls cannot be applied here' is shown:

This occurs because there's a space (marked red) in front of the header. The solution is to remove the space, or to include it in the selection.

Binding errors

Validation error in Template Designer

Inserting a smart field via User profile or Form response works without any issues, because you just have to click the field you want to use. If you want to insert a smart field via e.g. Custom text binding or Custom image binding where you have to type a binding yourself, it can cause error messages like this:

The 'error at position 2-19' in the example above means that the error begins at character '2' and ends at character '19' (note that counting starts with '0'):

• Expression UserProfile has a type UserProfileType which does not contain member with name <name>: In this case it means that the User Profile doesn't contain a form field named 'Office'.
• Expression does not evaluate to a type String: This error is shown when you refer to a dropdown field in the binding and the column name is missing. For example the binding {{UserProfile.Office}} is used while it should be {{UserProfile.Office.Name}}.

Validation error in Admin Center

The Admin Center validates a template when you upload or replace it. It shows 'Processing document failed' for Word templates or 'Processing presentation failed' for PowerPoint templates, followed by the  the cause of the validation error in the side panel:

For example these error messages can be shown: 

Content elements

When uploading or replacing a template this message can be shown:

A template with a large amount of XML may cause performance implications, which is why we have set a limit and cannot support templates exceeding this limit. 

The current limitations are:

This is most often happening on PowerPoint presentations containing a lot of shapes that can be edited by the end-user (world maps for example). In this case, we recommend: 

• The shapes do not need to be edited by the end-user: replace the content elements (shapes) with a picture. You can do so by copying the group of shapes and pasting it as a picture. 
• The shapes do require to be edited by the end-user: split the presentation into several smaller ones so it fits into the maximum allowed number of content-elements.

Creating a document

Formatting is not applied to content control

In a template the content control of a Templafy field is set to e.g. show bold+italic text, but when a user creates a document, the text is not bold+italic. This can occur if no placeholder text is used when adding a smart field to a template.

When adding a smart field to a template in Word, Templafy automatically creates a content control including a placeholder text. When you want to use custom formatting for the content control, you need to select text as a placeholder text before adding the smart field.

For example you have a 'Subject' field and add it to the template by clicking Add to template:

When no placeholder text is used the Display name is shown in grey text (1).
If you then change the formatting of the content control to e.g. bold+italic (2), then the result (when a document is created) is that 'hello world' is not bold+italic (3):

If a placeholder text like [Subject] is used (1) and then the formatting of the content control is changed to bold+italic (2), then this time the result is that 'hello world' is shown in bold+italic text (in the correct font size) as expected:

Hidden text is shown while VisibilityType.Hidden is used

In a Word template in a Visibility expression field e.g. the expression {{IfElse(Form.Show_text, VisibilityType.Visible, VisibilityType.Hidden)}} is used. When the checkbox is not checked, the text should be hidden, but the hidden text is shown in the document:

When hidden text is shown, then check the following Word settings:

• In Word go to File > Options and select the Display section. The option Hidden text and/or Show all formatting marks is enabled. Disable the option(s):
  
• In the Word ribbon the paragraph marking (¶) is enabled. Disable the paragraph marking:
  

After applying the settings above, the hidden text is not shown anymore:

Field codes are shown instead of values

In a Word document field codes are shown instead of values:

Document shows values Document shows field codes

This occurs when in Word the option Show field codes instead of their values is enabled in the form below. Disable the option to show the values:

Share value is not working

The option Share value is used to display a form field only once, even if the form field is used multiple times. For example the form field is used in a document (template), and the same form field is also used in a text element that is dynamically inserted into the document.

This can occur in these situations:

• The option Share value is only enabled in the template or text element. The option Share value only works when it's enabled in both the template and text element.
• The name of the form field in the template and text element is different. The form type and name should be the same. For dropdowns make sure the same data source and column are used.

Read the article how to share the answer from template and text elements.

Filtering dropdown is not working

This can occur when data sources are not configured correctly. To be able to use field A to filter field B, the data source for field A needs to be a reference in the data source used for field B.

For example if you want to filter a city (dropdown) based on a country (dropdown), you need to have a separate Country data source and used that as a reference in the City data source.

Values in a table are shown twice

A table contains for example only one Address field, but in the created document the address is shown twice:

This can occur when the Text wrapping property of the table that contains the field is set to Around (marked red):

Change the setting to None (marked green). Note that you now have no text wrapping! If you need text wrapping, then the solution is to replace the table by a shape.

Form fields are shown twice in the composer or response form

When a document is created then (some) form fields are shown twice in the composer or response form, even though in Template Designer all form fields only occur once and are configured correctly.

This can occur when the elementsMetadata property in the JSON contains clutter. For the solution see Text element is not inserted below.

Image field is empty

In the document an empty image field is shown:

This can occur if a data source record (intentionally) contains no image. To solve it use a dummy image file for this record (e.g. 'dummy.png') that consists of 1 (white or transparent) pixel. Or use a visibility binding to hide the image when there is none.

Creating document failed error message

When creating a document the message 'Creating document failed' and/or 'Failed' is shown:

The 'Failed' message often contains a 'Tracking id', that shows detailed information about what went wrong. For example:

Invalid measure unit string value. (Parameter 'stringValue'): An Image header has e.g. the binding {{UserProfile.Office.Logo.LeftOffset}} in the Left Offset field. In the data source the'Left Offset' column contains e.g. the value '3.75'.
The error is shown because the measure unit (centimeters) is missing. Change '3.75' to '3.75 cm'.

The asset you are trying to access does not exist or is not available to you

This error message can be shown in these situations:

• In the header or footer of a Word template both the first page and 'Different first page' contain a binding to the same text element. Delete one of the bindings.
• A text element used in a template does not have a placeholder (on the Template tab the Placeholder field is empty). Add a placeholder. If that doesn't solve the issue, then delete the content control in the template and recreate the binding to the text element.
• In Word Restrict Editing is enabled (with 'Filling in forms' allowed). This is not supported by Templafy. Disable Restrict Editing.

Updating a document

The Update Document button is not available

This can occur in these situations:

• In the template Document content updater is not enabled. In Template Designer open Settings and enable Document content updater.
• You are using a different MSI than the tenant you are creating the document from.
  This is expected behavior. Always use the correct MSI, for example if you switch between a test and production tenant.
• A binding in the template is invalid.
• The binding is linking to a non-existing text element.

Dynamic bindings in the document are not updated

This can occur in these situations:

• Text element (fixed part of template): if the option Replace on update on the Template tab is not enabled then values of form fields still will be updated, but if the content of the text element has changed (e.g. in the Admin Center the original version is replace by a new version) this will not be updated.
• Text element (inserted via dropdown): if the option Replace on update on the Template tab is not enabled then the dropdown will not be shown anymore. For example if the user can choose to Yes/No insert a text element and chooses 'No', then it's not possible anymore (after the document is created) to change it to 'Yes'. If you want the user to be able to change the answer then Replace on update needs to be enabled.
• Text binding or Image binding: if the option Allow updates is not checked. There are 3 possible settings:
  • Only Allow updates is checked: values are updated.
  • Only Remove And Keep Content is checked: values are not updated, because the content control is removed (the value now has become plain text).
  • Both Allow updates and Remove And Keep Content are not checked: values are not updated.
• Visibility binding: In the Visibility expression field VisibilityType.Delete is used. If a content control is deleted updating is not possible anymore. Use VisibilityType.Hidden instead.

Document update failed

Creating a document works as expected, but when you try to update the document the message 'Document update failed' is shown:

This can occur in these situations:

• When a 2 letter code like en or fr is used in the Proofing Language document property (on the Template Designer Advanced tab). Only 4 letter codes like en-US or fr-FR are supported.
• The template contains a corrupt smart field. For example an image smart field should show the icon marked green below, but instead it shows the icon marked red. Delete the field and create a new one.
  
  
• In Word Restrict Editing is enabled with e.g. the option No changes (Read only). This is not supported by Templafy.

Layout of Word document changes or text is cut off

A template contains a text element or table located in the header and the template is also configured with an Image Header. If a document is created using this template and then updated then one of these issues might occur:

• The layout of the document changes:
  • For example a text box containing a colophon (content of the text element) is located at the right side of the document, but after updating it is now aligned to the left or has disappeared.
  • For example a logo is positioned at the upper right corner of the document, but after updating the logo is shown in the middle of the document or has disappeared.
• Text is cut off. For example the text element only contains the text 'hello world', but after updating the document shows 'hello worl'.

Text element

This happens if the text element content control is located in the last paragraph of the header. The solution is to add an extra paragraph after the one containing the text element:

Table

This happens if the table is the first object in the header. The solution is to add a paragraph before the table:

Text Elements

Text element cannot be inline text

When you upload or replace a text element in the Admin Center library the error message 'Text Element TextElement<number> can not be inline text' can be shown:

This means the template contains a text element content control inside a sentence (marked red below). This is not supported, the content control needs to be created in it's own paragraph (marked green) or table cell:

A correctly used text element content control can be recognized by two (start and end) textElement tags (visible when Design Mode in Word is enabled).
When it's not used correctly it will only have one (start) textElement tag (marked red above). Deleting the sentence will not solve the issue: the end tag is deleted permanently.
The solution is to delete the current content control and create a new one.

Empty paragraph of text element is removed

When a text element starts with an empty paragraph and a document (that contains this text element) is updated, then the empty paragraph is removed. This is by design. The reason for this (in short) is that Word sometimes adds unwanted empty paragraphs when a document (with a text element) is updated. For example if the first item of a text element is a table and you do not have an empty paragraph before (above) that table, then when the document is updated, Word adds an empty paragraph!

If for example you want to show an empty bullet, this means that this bullet is deleted after updating the document since it is an empty paragraph. To solve this, add a space to the paragraph so it's not deleted.

Hyperlink of text element is shown as plain text

A text element contains a hyperlink (like 'Click here'). The text element is part of the footer of a template. When a document is created with this template, the hyperlink is shown as plain text, so the hyperlink does not work.

This can occur when the template does not contain a hyperlink style. To solve this, type e.g. 'www.templafy.com' in the template and press Enter. Now a hyperlink style should automatically have been added to the template. Save the template, then remove the temporary text ('www.templafy.com') and save the template again. The style remains present in the template, so the text element in the footer will now show a working hyperlink when a document is created.

Text element is not inserted

A text element should be inserted when a checkbox is ticked or when a specific value is selected in a dropdown, but nothing happens, even though the text element binding is correct.

This can occur when the elementsMetadata property in the JSON contains clutter, like "type": "richTextContentControl", "id": 123ab-456-7cd8e90" etcetera, as shown in the left image (marked red) below:

To solve this, follow the steps below:

1. Make a backup of the template.
2. In Template Designer click the ellipsis (3 dots) in the upper right corner, then click Settings.
3. Click Advanced configuration.
4. In the 'Configuration' form, on the Template tab, remove the clutter in the elementsMetadata property (marked red in the left image above).
5. The result should look as shown in the middle image (marked green) with only 2 brackets [ and ] (and a comma) behind the elementsMetadata property.
6. Depending on the content of the template the transformationConfigurations property may contain content (marked blue in the right image above), this should not be removed.
   

Section breaks in text element are ignored

A text element contains section breaks, for example to show page 1 and 3 in portrait orientation and page 2 in landscape. When the text element is inserted dynamically then the section breaks are ignored and, in this example, all pages are shown in portrait orientation. Only when Update Document is run, the section breaks are recognized and now the second page is shown in landscape. This behavior is by design.

Languages and Translations

Translations are not working

This can occur in these situations:

• There's a mismatch between the binding and the Translations data source. For example the binding is {{Translate("Subject")}} but the name in the Translations data source is "Subject ". The extra space creates a mismatch. As result the value in the Name column is used. Verify the value is written correctly. Note that it is also case sensitive.
• If the column name parameter is not used, then e.g. {{Translate("Subject")}} assumes the User Profile contains a dropdown named DocumentLanguage. When a different name is used (which is not recommended) then you need to add the column name parameter to the binding, e.g. {{Translate("Subject", Language)}}. So either rename the user profile field to DocumentLanguage or specify the different name in the binding.

Proofing language is not working

This can occur in these situations:

• The language is not available in the Languages data source. Add the correct language.
• If the binding {{DocumentLanguage}} is used in the Language field of the Proofing Language property (on the Advanced tab), but the User Profile does not contain a dropdown named DocumentLanguage. So either rename the User Profile field to DocumentLanguage or specify the User profile field name in the binding.

Gibberish is shown instead of a date

The Translations data source is used for date formats:

In a template the binding {{FormatDateTime(Form.Date, Translate("FormatGeneralDate", DocumentLanguage), DocumentLanguage)}} is used. This means that if in the User Profile the document language is set to en-US the date format 'MMMM d yyyy' is used or when it's nl-NL the date format 'd MMMM yyyy' is used.

If the date is e.g. '12 March 2024' then the output should be 'March 12 2024' for en-US and '12 maart 2024' for nl-NL. However the output shows 'or0aAGeneralDaAe' instead.

This can occur when the DocumentLanguage in the User Profile is not set by the user. The system tries to format the text found in the first column (like 'FormatGeneralDate') as a date. The solution is to make the DocumentLanguage field in the User Profile required.