The functionality Validate will verify the usage and structure of the keywords/fields of the working document.

When validating a document, by pressing the "Validate" button, the tool will try to find every possible error or warning in the current template and list them to the user like it is demonstrated in the following image. The error or warning will normally have information about the problematic mapping and a message explaining the error and a possible solution to this error.


The validation process will only validate the currently active spreadsheet. If you have multiple spreadsheets you need to go one by one to validate them. 

Custom Fields


Custom fields don't follow any formatting rules and can have any sequence of characters, even ones that would be very important and used while validating fields. Since we do not have a solid way of verifying if certain custom fields could be mistakenly formatted, we will always show a warning message when this happens. If the custom field is well formatted and is structured on purpose by the user, this message needs to be ignored. 

In order to provide a better validation for the custom fields you can login into your Jira instance (only available for Xray Document Generator On-Premise).


In order to provide a better validation for the custom fields, you can login into your Jira instance and this will not be an issue anymore. The custom fields will be validated as such and instead of seeing a warning message, you will see an error message if the custom field isn't valid.

Examples

In this section, you can see examples of use cases with a "success", "an error" and a "warning" to help you use the validator to find errors and swiftly fix them all without ever having to leave the add-in.


Success

In this example, you have the iteration Attachments without any error and if you click on the "Validate" button you are going to receive a success message

#{for a=AttachmentsCount}
	${Attachments[a].ID}
	${Attachments[a].Author}
	${Attachments[a].AuthorFullName}
	${Attachments[a].Name}
	${Attachments[a].Size}
	${Attachments[a].HumanReadableSize}
	${Attachments[a].Created}
	${Attachments[a].MimeType}
#{end}

Warnings

In this example, you have the iteration Attachments with some errors and if you click on the "Validate" button you are going to receive a warning message for each possible error.


These errors will be identified as warnings by the validator. This is because all of the snippets declared, with the exception of the for-statement, can be custom fields. If you are logged in, the errors are still present but instead of warnings, they are going to appear as errors.

//This mapping has a dot in the end and no other mapping following it
${AttachmentsCount.}
//We are missing a value after the comma
${prop(myVariable, )}
#{for a=AttachmentsCount}
//In this snippet is missing the variable. The "a" inside square brackets
	${Attachments[ ].ID}
//In this snippet is missing a closing square bracket before the dot character
	${Attachments[a.Author}
//In this snippet is missing a mapping after the dot character
	${Attachments[a]. }
//This mapping has an unexpected character declared before the dot character
	${Attachments[a]/.Name}
#{end}

Once ran, the validator will pinpoint all of the errors exemplified before, give you a description of the error and give you a suggestion of how this error could be resolved. You can see this in the following image.


Errors

In this section, you can see some examples of errors that can occur during the validation. 

Example 1

In this example, you have the iteration Attachments with some errors and if you click on the "Validate" button you are going to receive an error message for each possible error.

// This for-statement has a missing ending tag (#{end})
#{for a=AttachmentsCount}
	${Attachments[a].ID}
	${Attachments[a].Author}
	${Attachments[a].AuthorFullName}
	${Attachments[a].Name}
	${Attachments[a].Size}
	${Attachments[a].HumanReadableSize}
	${Attachments[a].Created}
	${Attachments[a].MimeType}

Example 2

In this example, you have the iteration Attachments with some errors and if you click on the "Validate" button you are going to receive an error message for each possible error.

#{for a=AttachmentsCount}
	${Attachments[a].ID}
	${Attachments[a].Author}
	${Attachments[a].AuthorFullName}
	${Attachments[a].Name}
// This end-statement tag doesn't match with the declared in the for statement
&{end}

Select snippet

In the Examples section, you can see that each warning and error message has the symbol . If you click on it, the add-in is going to select an excerpt of text where the error occurred.


  • If you are in a Word document when you click the symbol the snippet is selected. 

         

  • If you are in an Excel document when you click the symbol the cell where the snippet is contained is selected.

        

Table of Contents: