Iterating Issue Activity

As it is not known in advance how many changes are made on issues and these changes are registered on Issue Activity, there is a notation that allows iterating a section over all the activities of an issue. For example, this allows creating a document that dynamically grows according to the number of existing activities. The notation is:

#{for activityEntries}
   ${ActivityEntries[n].Title}
   ${ActivityEntries[n].Summary}
   ${ActivityEntries[n].Content}
   ${ActivityEntries[n].Author}
   ${ActivityEntries[n].AuthorEmail}
   ${ActivityEntries[n].Published}
   ${ActivityEntries[n].Updated}
   ${ActivityEntries[n].Categories}
#{end}
 
or
 
#{for <VariableName>=ActivityEntriesCount}
   Content and Issue Mappings. Example: ${ActivityEntries[VariableName].Field}
#{end}

Below there is a sample of using the Activity iteration in a Word template:

or

Below there is a sample of using the Activity iteration in an Excel template:

or

Iterating Issue Links

As it is not known in advance how many linked issues exist for an issue, there is a notation that allows iterating a section over all the linked issues of an issue. For example, this allows creating a table that dynamically grows according to the number of existing linked issues. The notation is:

#{for links}
   ${Links[n].AppType}
   ${Links[n].LinkType}
   ${Links[n].Key}
   ${Links[n].Summary}
   ${Links[n].URL}
#{end}
 
or
 
#{for <VariableName>=LinksCount}
   Content and Linked Issue Mappings. Example: ${Links[VariableName].Field}
#{end}

Note:  When the link you are iterating is on of these AppTypes: External JIRA or Confluence, the name is obtained using the Summary property.

The image below demonstrates an example of a Word template that iterates over linked issues.

or

For a working example of this functionality, check the template (SampleIterations.docx) on the  Samples Page.

The image below demonstrates an example of an Excel template that iterates over linked issues.

or

Iterating Issue Comments

As it is not known in advance how many comments exist for an issue, there is a notation that allows iterating a section over all the comments on an issue. For example, this allows creating a table that dynamically grows according to the number of existing comments. The notation is:

#{for comments}
   ${Comments[n].Author} 
   ${Comments[n].AuthorFullName} 
   ${Comments[n].Body} 
   ${Comments[n].Created}
   ${Comments[n].GroupLevel}
#{end}
 
or
 
#{for <VariableName>=CommentsCount}
   Content and Issue Mappings. Example: ${Comments[VariableName].Field}
#{end}

Iterating Issue Worklogs

As it is not known in advance how many worklogs exist for an issue, there is a notation that allows iterating a section over all the worklogs of an issue. For example, this allows to create a table that dynamically grows according to the number of existing worklogs. The notation is:

#{for worklogs}
   ${Worklogs[n].Author} 
   ${Worklogs[n].AuthorFullName} 
   ${Worklogs[n].Comment}
   ${Worklogs[n].Created}
   ${Worklogs[n].Date Started} 
   ${Worklogs[n].Time Spent}
   ${Worklogs[n].TimeSpentFormatted} 
   ${Worklogs[n].BilledHours} 
   ${Worklogs[n].BilledHoursFormatted} 
#{end}
 
or
 
#{for <VariableName>=WorklogsCount}
   Content and Worklog Mappings. Example: ${Worklogs[VariableName].Field}
#{end}

The image below demonstrates an example of a Word template that iterates over issue worklogs.

or

For a working example of this functionality, check the template (SampleIterations.docx) on the Samples Page.

The image below demonstrates an example of a template in Excel that iterates over issue worklogs.

or

Iterating Issue Subtasks

As it is not known in advance how many subtasks exist for an issue, there is a notation that allows iterating a section over all the subtasks of an issue. For example, this allows creating a table that dynamically grows according to the number of existing subtasks. The notation is:

#{for subtasks}
   ${Subtasks[n].Key}
   ${Subtasks[n].Summary}
   ${Subtasks[n].AssigneeUserDisplayName}
#{end}
 
or
 
#{for <VariableName>=SubtasksCount}
   Content and Issue Mappings. Example: ${Subtasks[VariableName].Field}
#{end}

For a working example of this functionality, check the template (SampleIterations.docx) on the Samples Page.

The image below demonstrates an example of an Excel template that iterates over issue subtasks.

or

For an example of how to iterate the details of a subtask Parent issue, please check the Iterating JQL Queries area below.

Iterating Issue Components

As it is not known in advance how many components exist for an issue, there is a notation that allows iterating a section over all the components of an issue. For example, this allows creating a table that dynamically grows according to the number of existing components. The notation is:

#{for components}
   ${Components[n].Name}
   ${Components[n].Description}
   ${fullname:Components[n].Lead}
   ${Components[n].Id}
   ${Components[n].ProjectId}
   ${Components[n].AssigneeType}
#{end}

 The image below demonstrates an example of a Word template that iterates over issue components.

 The image below demonstrates an example of an Excel template that iterates over issue components.

Iterating Issue Status Transitions

As it is not known in advance how many Status Transitions exist for an issue, there is a notation that allows iterating a section over all the Status Transitions of an issue. For example, this allows creating a table that dynamically grows according to the number of existing status transitions. The notation is:

#{for statusTransitions}
   ${StatusTransitions[n].Author}
   ${StatusTransitions[n].Created}
   ${StatusTransitions[n].OldStatus}
   ${StatusTransitions[n].NewStatus}
#{end}
 
or
 
#{for <VariableName>=StatusTransitionsCount}
   Content and StatusTransitions Mappings. Example: ${StatusTransitions[VariableName].Field}
#{end}

Iterating Issue Attached Images

As it is not known in advance how many Images can exist for an issue (as attachment), there is a notation that allows iterating a section over all the attached images of an issue to get some metadata about them. For example, this allows creating a table that dynamically grows according to the number of existing images. The notation is:

#{for images}
   ${Images[n].Image|maxwidth=150|maxheight=150}
   ${Images[n].Name}
   ${Images[n].ID}
   ${Images[n].Size}
   ${Images[n].HumanReadableSize}
   ${Images[n].Author}
   ${Images[n].Created}
   ${Images[n].MimeType}
   ${Images[n].ThumbnailURL}
 #{end}
 
or
 
#{for <VariableName>=ImagesCount}
   Content and Images Mappings. Example: ${Images[VariableName].Field}
#{end}

The image below demonstrates an example of a Word template that iterates over attached images. 

or

The image below demonstrates an example of an Excel template that iterates over attached images. 

or

Iterating Issue Attachments

As it is not known in advance how many attachments exist in an issue, there is a notation that allows iterating a section over all the attachments of an issue. For example, this allows creating a table that dynamically grows according to the number of existing attachments. The notation is:

#{for attachments}
   ${Attachments[n].ID}
   ${Attachments[n].Name}
   ${Attachments[n].Author}
   ${Attachments[n].AuthorFullName}
   ${Attachments[n].Created}
   ${Attachments[n].Size}
   ${Attachments[n].HumanReadableSize}
   ${Attachments[n].MimeType}
#{end}
 
or
 
#{for <VariableName>=AttachmentsCount}
   Content and Issue Mappings. Example: ${Attachments[VariableName].Field}
#{end}

The image below demonstrates an example of a Word template that iterates over attachments.

or

The image below demonstrates an example of an Excel template that iterates over attachments.

Iterating Issue Labels

As it is not known in advance how many labels exist in an issue, there is a notation that allows iterating a section over all the labels of an issue. The notation is:

#{for labels}
   ${Labels[n].Name}
#{end}
 
or
 
#{for <VariableName>=LabelsCount}
  ${Labels[VariableName].Name}
#{end}

The image below demonstrates an example of a Word template that iterates over labels.

or

The image below demonstrates an example of an Excel template that iterates over labels.

or

Iterating Project Versions from an Issue

This iteration allows you to iterate over all project versions from the project which the issues belong to. The notation is:

Start date

Release date

#{for projectVersions}
   ${ProjectVersions[n].Name}
   ${ProjectVersions[n].Description}
   ${ProjectVersions[n].Start date}
   ${ProjectVersions[n].Release date}
#{end}
 
or
 
#{for <VariableName>=ProjectVersionsCount}
   ${ProjectVersions[VariableName].Name}
   ${ProjectVersions[VariableName].Description}
   ${ProjectVersions[VariableName].Start date}
   ${ProjectVersions[VariableName].Release date}
#{end}

The image below demonstrates an example of a Word template that iterates over project version.

or

The image below demonstrates an example of an Excel template that iterates over project version.

or

Iterating JQL Queries

It is also possible to iterate issues that are the result of a JQL Query. The syntax is similar to the other iterations, but there is a clause parameter that will receive the JQL Query. A few examples are provided below.

a simple example iterating the details of issues from a specified Project:
 
#{for i=JQLIssuesCount|clause=project = DEMO}
   ${JQLIssues[i].Key}
   ${JQLIssues[i].Summary} 
#{end}

or a more advanced example iterating the details of issues linked with the current Issue:
 
#{for m=JQLIssuesCount|clause=issuekey in linkedIssues (${Links[j].Key})}
   Linked Issue ${JQLIssues[m].Summary} has ${JQLIssues[m].LinksCount} links
#{end} 
 
or an also advanced example iterating the details of the Parent issue from the current Subtask:
 
#{for i=JQLIssuesCount|clause=issuekey = ${ParentIssueKey}}
	${JQLIssues[i].Key}
	${JQLIssues[i].Id}
	${JQLIssues[i].Description}
#{end}

For a working example of this functionality, check the template Sample Iterations in the Template Store.

The image below demonstrates an example of an Excel template that iterates over issue subtasks.

Iterating Issue Commits

As it is not known in advance how many commits exist for an issue, there is a notation that allows iterating a section over all the commits of an issue. For example, this allows creating a table that dynamically grows according to the number of existing commits. The notation is:

Message

Author

In order to extract more information from Commits, it is possible to get information from files committed:  

#{for commits}
	${Commits[n].Author} 
	${Commits[n].URL} 
	${Commits[n].Message}
	${Commits[n].CreatedDateTime}
	
	Here we have the FilesCount where we can get all the files associated with a commit.
	#{for m=Commits[n].FilesCount}
		${Commit[n].FilesCount[m].Path}
		${Commit[n].FilesCount[m].URL}
		${Commit[n].FilesCount[m].ChangeType}
	#{end}
#{end}
 
or
 
#{for <VariableName>=CommitsCount}
   Content and Issue Mappings. Example: ${Commits[VariableName].Field}
#{end}

Iterating Issue Branches

As it is not known in advance how many branches exist for an issue, there is a notation that allows iterating a section over all the branches of an issue. For example, this allows the user to create a table that dynamically grows according to the number of existing branches. The notation is:

RepositoryName

RepositoryURL

#{for branches}
  ${Branches[n].URL}
  ${Branches[n].Name}
  ${Branches[n].RepositoryName}
  ${Branches[n].RepositoryURL}
#{end}
 
or
 
#{for <VariableName>=BranchesCount}
   Content and Issue Mappings. Example: ${Branches[VariableName].Field}
#{end}

Iterating Issue Pull Requests

As it is not known in advance how many pull requests exist for an issue, there is a notation that allows iterating a section over all the pull requests of an issue. For example, this allows creating a table that dynamically grows according to the number of existing pull requests. The notation is:

RepositoryName

RepositoryURL

You can get information about reviewers from each  pull request:

#{for pullRequests}
  	${PullRequests[n].URL}
  	${PullRequests[n].Name}
  	${PullRequests[n].RepositoryName}
  	${PullRequests[n].RepositoryURL}
	${PullRequests[n].CommentsCount} (This represents the number of comments in a pull request)
	${PullRequests[n].Status}
	${PullRequests[n].LastUpdated}
 
	Here we have the PullRequestReviews where we can get all the reviewers for this pull request.
	#{for m=PullRequests[n].PullRequestReviewers}
  		${PullRequests[n].PullRequestReviewers[m].Name}
  		${PullRequests[n].PullRequestReviewers[m].Approved}
	#{end}
#{end}
 
or
 
#{for <VariableName>=PullRequestsCount}
   Content and Issue Mappings. Example: ${PullRequests[VariableName].Field}
#{end}

Iterating Issue Builds

 As it is not known in advance how many builds exist for an issue, there is a notation that allows iterating a section over all the builds of an issue. For example, this allows the user to create a table that dynamically grows according to the number of existing builds. The notation is:

In order to get more information, we can get all the individual plans for the project and the correspondent build in existence for this plan

Plans.Key

Plans.BuildNumber

#{for builds}
  	${Builds[n].ProjectName}
  	${Builds[n].ProjectKey}
	
	Here we have the each Build Plans where we can get all the individual plans for this project and the correspondent build in existence for this plan.
	#{for m=Builds[n].Plans}
  		${Builds[n].Plans[m].Key}
  		${Builds[n].Plans[m].Name}
  		${Builds[n].Plans[m].BuildNumber}
  		${Builds[n].Plans[m].BuildKey}
  		${Builds[n].Plans[m].BuildDuration}
  		${Builds[n].Plans[m].BuildFinishedDate}
	#{end}
#{end}
 
or
 
#{for <VariableName>=BuildsCount}
   Content and Issue Mappings. Example: ${Builds[VariableName].Field}
#{end}

Iterating Issue Reviews

 As it is not known in advance how many reviews exists for an issue, there is a notation that allows iterating a section over all the pull requests of an issue. For example, this allows the user to create a table that dynamically grows according to the number of existing reviews. The notation is: 

In order to get all the reviewers from this review we can use de following mappings:

#{for reviews}
  	${Reviews[n].Id}
  	${Reviews[n].URL}
  	${Reviews[n].Status}
  	${Reviews[n].Title}
  	${Reviews[n].Author}
  	${Reviews[n].Moderator}
	
	Here we have the Reviewers for each review where we can get all the individual reviewers for this review.
	#{for m=Reviews[n].Reviewers}
 		${Reviews[n].Reviewers[m].Username}
  		${Reviews[n].Reviewers[m].Completed}
	#{end}
#{end}
 
or
 
#{for <VariableName>=ReviewsCount}
   Content and Issue Mappings. Example: ${Reviews[VariableName].Field}
#{end}

Applying filters to Iterations

If you want to take the previous iterations over comments, subtasks and issue links to another level of control you can use a javascript filter to define over which issues the iteration will be made. For instance, this can be useful in the following scenarios:

• Iterating over linked issues that are only of a specific issue type
• Iterating over subtasks of a specific issue type
• Iterating over linked issues with a specific priority
• Iterating over comments created by a specific user
• etc...

The notation for applying filters to the iterations is the following:

#{for <VariableName>=<LinksCount|SubtasksCount|CommentsCount|WorklogsCount>|filter=%{<Javascript>}}
   Content here
#{end}

Notice that as the filter is evaluated as a Javascript expression, there is a big flexibility on the definition of the conditions. You can use and (&&), or (||) and other logical operators supported by the Javascript language.

It is also possible to format fields inside iteration filters. For more information on formaters, see Formatting Fields.

The image below demonstrates an example of a template that iterates over issue links and comments with filters being applied.

Links Bugs with High Priority:

Nested Iterations:

For a working example of this functionality, check the template Sample Iterations in the Template Store.

Iterating in the same line of the document

It is also possible to iterate values in the same line of the document. This can be useful for instance to display a list of Subtasks on Linked Issues in the same line, separated by commas or spaces. Find examples below:

Users that added comments to this issue: #{for comments}${Comments[n].Author} #{end}

Subtasks of this issue: #{for j=SubtasksCount}${Subtasks[j].Key};#{end}

Linked issues this issue duplicates: #{for j=LinksCount|filter=%{'${Links[j].LinkType}'.equals('duplicates')}}${Links[j].Key} #{end}

Iterating in the same cell in an Excel document

It is possible to iterate values in the same cell in an Excel document. You can achieve this by simply making your Iteration inside the same cell.

You can use all the Iterations that you are used to and construct them in the exact same way, the difference being that you only use one cell to do them.

Issue iteration as a demonstration.
Copy this iteration below and paste it into a cell.
 
&{for issues} ${Key} &{end}

Iterating with the BREAK or CONTINUE statement.

It is possible to iterate anything and setup a Conditional expression and utilize the BREAK and CONTINUE statements.

The way to do this is by doing a normal Conditional expression and using the mapping #{break} or #{continue} inside it. You can check a more detailed example inside the code block.

Imagine that you have a Jira Issue that contains these comments:
- Hello
- World
- Greetings
- Hi
 
For the Break functionality, lets say that you want to stop the iteration if the current comment is "World". Here is the template for that:
#{for comments}
Current Comment: ${Comments[n].Body}
#{if (%{'${Comments[n].Body}'.equals('World')})}
#{break}
#{end}
Current Comment Author: ${Comments[n].Author}
#{end}
In this case, Xporter for Jira will print the comment "Hello" and it´s author. Next it will print the comment Body "World" but since the Conditional expression is true, it will stop the iteration all together and not print anything else.
Note: Anything after the #{break} mapping will not be printed in the exported document.
 
For the Continue functionality, lets say that you want to skip to the next iteration if the current comment is "World", bypassing the Author mapping for this iteration. Here is the template for that:
#{for comments}
Current Comment: ${Comments[n].Body}
#{if (%{'${Comments[n].Body}'.equals('World')})}
#{continue}
#{end}
Current Comment Author: ${Comments[n].Author}
#{end}
In this case, Xporter for Jira will print the comment "Hello" and it´s author. Next it will print the comment Body "World" but since the Conditional expression is true, it will continue to the next iteration, not printing the Author of the "World" comment.

This iteration allows you to iterate over all project versions from the project which the issues belong to. The notation is: