Package com.thepluginpeople.jemhod.api

Interface ITemplateUtils

public interface ITemplateUtils
Utility class used while rendering velocity email templates.
Author:
Fernado Boucquez

  • Method Details

    • getUser

      com.fasterxml.jackson.databind.JsonNode getUser(Object object)
      Loads and returns the user from a json node, user or string object.
      Parameters:
      object - user object, node or account id
      Returns:
      the user object or null if the account id could not be resolved from the parameter.

    • getUserAccountId

      String getUserAccountId(Object object)
      Returns the user's account id from a json node, user or string object.
      Parameters:
      object - user object, node or account id.
      Returns:
      the accountId or null

    • getUserProfileUrl

      String getUserProfileUrl(Object object)
      Returns the user's profile url from a json node, user or string object.
      Parameters:
      object - user object, node or account id.
      Returns:
      the url or null if the account id could not be resolved

    • isJiraUser

      boolean isJiraUser(Object object)
      Returns if the user is a jira user, excluding the addon user
      Parameters:
      object - user object, node or account id.
      Returns:
      if the object is a user, excluding the addon user.

    • getUserDescription

      String getUserDescription(Object object)
      Returns the best user's representation from a json node, user or string object.
      Parameters:
      object - user object, node or account id.
      Returns:
      the user description or null if the account id could not be resolved from the parameter.

    • getUserEmailAddress

      String getUserEmailAddress(Object object)
      Returns the user email from a json node, user or string object.
      Parameters:
      object - user object, node or account id.
      Returns:
      the user email or null.

    • isUserInGroup

      boolean isUserInGroup(Object object, String groupname)
      Returns if the user's belongs to the given group name.
      Parameters:
      object - user object, node or account id.
      groupname - the group name
      Returns:
      if the user's belongs to the given group name.

    • hasProjectRole

      boolean hasProjectRole(Object object, String projectRoleName)
      Returns if a user belongs to a project role.
      Parameters:
      object - user object, node or account id.
      projectRoleName - the project role name (Users, Developers, Users, etc.).
      Returns:
      if a user belongs to a project role.

    • getUserAvatar

      String getUserAvatar(Object object, String avatarSize)
      Returns the user email from a json node, user or string object.
      Parameters:
      object - user object, node or account id
      avatarSize - the avatar size like "16x16"
      Returns:
      the user email or null.

    • getIssueTypeMetadata

      com.fasterxml.jackson.databind.JsonNode getIssueTypeMetadata(com.fasterxml.jackson.databind.JsonNode issue)
      Returns the issue type metadata for the give project and issue type id.
      Parameters:
      issue - the issue
      Returns:
      the metadata

    • getStatusCategoryHexColor

      String getStatusCategoryHexColor(String color)
      Transform the color form the status category to hex
      Parameters:
      color - the color like yellow
      Returns:
      the hex color

    • getFieldMetadata

      com.fasterxml.jackson.databind.JsonNode getFieldMetadata(com.fasterxml.jackson.databind.JsonNode issue, String fieldId)
      Returns the field with the given field id or name;
      Parameters:
      issue - the issue
      fieldId - the field id
      Returns:
      the field or null

    • getFieldId

      String getFieldId(String fieldIdOrName)
      Return the id of the file with the given id or name.
      Parameters:
      fieldIdOrName - the field id or name
      Returns:
      the id of the file with the given id or name or the parameter if the field is not found.

    • getWatchers

      List<com.fasterxml.jackson.databind.JsonNode> getWatchers()
      Return the users that are watching this ticket.
      Returns:
      a list of all the users currently watching this ticket.

    • getSprintNameFromEventValue

      String getSprintNameFromEventValue(String value)
      This method fixed incorrect sprint values from events. These values are printed version of internal Jira objects. For example:

      ["com.atlassian.greenhopper.service.sprint.Sprint@deb05e[id=1,rapidViewId=1,state=ACTIVE,name=SP Sprint 1,goal=,startDate=2017-04-26T08:42:17.180-03:00,endDate=2017-05-10T08:42:00.000-03:00,completeDate= ,sequence=1]"]

      Parameters:
      value - the printed out object from the field value.
      Returns:
      the name from the printed object. Example "SP Spring 1"

    • getWorklogById

      com.fasterxml.jackson.databind.JsonNode getWorklogById(com.fasterxml.jackson.databind.JsonNode issue, String worklogId)
      The worklog json data for the given worklog id
      Parameters:
      issue - the issue context
      worklogId - the worklog id
      Returns:
      the json node or null if it's not found.

    • getIssueTypeMetadata

      com.fasterxml.jackson.databind.JsonNode getIssueTypeMetadata(String projectKey, Long issueTypeId)
      Returns the issue type metadata for the given project and issue type id.
      Parameters:
      projectKey - the project key
      issueTypeId - the issue type id.
      Returns:
      the issue type metadata.

    • htmlEscape

      String htmlEscape(String string)
      HTML escapes the string. Useful when printing user input in html templates.
      Parameters:
      string - the string
      Returns:
      the HTML escaped version of the string

    • slackEscape

      String slackEscape(String string)
      Slack escapes the string. Useful when printing user input in slack templates.
      Parameters:
      string - the string
      Returns:
      the slack escaped version of the string

    • mattermostEscape

      String mattermostEscape(String string)
      Mattermost escapes the string. Useful when printing user input in Mattermost templates.
      Parameters:
      string - the string
      Returns:
      the Mattermost escaped version of the string

    • jsonEscape

      String jsonEscape(String string)
      JSON escapes the string. Useful when printing user input in json templates.
      Parameters:
      string - the string
      Returns:
      the JSON escaped version of the string

    • wikiToHtml

      String wikiToHtml(String wiki)
      if the wiki rendering option is enabled, it converts wiki markup to html escaping existing html elements. If not, it just html escapes the parameter. Images URLs are converted to URL data using ITemplateUtils.inlineImage method.

      eg: "Here's a <strong>quote</strong> {quote}This is great!{quote}" will be converted to:

      "<p>Here's a &lt;strong&gt;quote&lt;/strong&gt; <blockquote><p>This is great!</p></blockquote></p>"

      Parameters:
      wiki - the wiki text
      Returns:
      the wiki text as html

    • getProjectMetadata

      com.fasterxml.jackson.databind.JsonNode getProjectMetadata(com.fasterxml.jackson.databind.JsonNode issue)
      Returns the project metadata for the give issue.
      Parameters:
      issue - the issue json data
      Returns:
      the project metadata.

    • getProjectMetadata

      com.fasterxml.jackson.databind.JsonNode getProjectMetadata(String projectKey)
      Returns the project metadata of the given project key.
      Parameters:
      projectKey - the project key
      Returns:
      the project metadata.

    • getIssue

      com.fasterxml.jackson.databind.JsonNode getIssue(String issueKey)
      Loads the issue from Jira. Use it if the event doesn't provide you information you need for rendering.
      Parameters:
      issueKey - the issue key.
      Returns:
      the issue or null if the issue doesn't exist.

    • reverse

      <T> Iterable<T> reverse(Iterable<T> iterable)
      Reverses an iterable returning a copy.
      Type Parameters:
      T - the generic type
      Parameters:
      iterable - the iterable
      Returns:
      a reversed copy of the iterable.

    • isPrivateJSDComment

      boolean isPrivateJSDComment(com.fasterxml.jackson.databind.JsonNode comment)
      Return if a comment is JSD private by querying the JSD comment property in:

      https://YOURJIRASERVER.com/rest/api/2/comment/YOURCOMMENTID/properties/sd .public.comment/

      Parameters:
      comment - one JSON comment object from the event context.
      Returns:
      true if the comment is JSD private or false otherwise.

    • filterRestrictedComments

      com.fasterxml.jackson.databind.node.ArrayNode filterRestrictedComments(com.fasterxml.jackson.databind.node.ArrayNode comments)
      Filter comments according restrictions. Comments are removed if:

      1) for EMAIL users(isSentToEmailUsers() is true). when comment is restricted or JSD private.

      2) for Jira users (isSentToEmailUsers() is false) when comment is restricted and getUser() doesn't belong to the restricted role

      Parameters:
      comments - the comments
      Returns:
      the array node

    • getProjectRoles

      List<com.fasterxml.jackson.databind.JsonNode> getProjectRoles()
      Gets the project roles.
      Returns:
      the roles of the issue projects.

    • isCreatedByEmailUser

      boolean isCreatedByEmailUser()
      Checks if is created by email user.
      Returns:
      if the issue was created/updated/commented by email. if false, the issue was created/updated/commented using the Jira UI.

    • getOperationUser

      com.fasterxml.jackson.databind.JsonNode getOperationUser()
      Gets the operation user.
      Returns:
      the Jira user that created/updated/commented the issue. JEMHCloud Add-on user if issue was created/updated/comment via email.

    • hasUserRole

      boolean hasUserRole(Object user, String roleName)
      Returns if a user has a given role.
      Parameters:
      user - the user
      roleName - the role name ([jira-administrators, jira-developers, jira-users. etc.)
      Returns:
      if a user has a given role.

    • isSentToEmailUsers

      boolean isSentToEmailUsers()
      Checks if is sent to email users.
      Returns:
      if the email created is to be sent to email users or a jira users.

    • hasElements

      boolean hasElements(Iterable<?> iterable)
      Checks for elements.
      Parameters:
      iterable - an iterable
      Returns:
      if the iterable has more elements

    • getUser

      com.fasterxml.jackson.databind.JsonNode getUser()
      The Jira user recipient of this email, the addon user if the recipients are emails users or null if the email is a non issue related issue like a forwarded email.
      Returns:
      a jira user or null.

    • getUserRole

      String getUserRole()
      Gets the user role.
      Returns:
      get the user's role (Reporter, Assignee or Watcher) or null if user is null or is the addon user.

    • toJson

      String toJson(Object object)
      Prints an object as json.
      Parameters:
      object - the object
      Returns:
      the json representation of the object

    • asText

      String asText(Object object)
      Prints an object.
      Parameters:
      object - the object
      Returns:
      the string representation of the object

    • getMailTo

      String getMailTo(String senderEmailAddress, String senderPersonal, String subject)
      Returns a mailto format of the given address and personal.
      Parameters:
      senderEmailAddress - the email address
      senderPersonal - the person if any
      subject - the subject
      Returns:
      the mail to url.

    • addStaticResourceInline

      String addStaticResourceInline(long staticResourceId)
      Adds the static resource as inline image returning the cid: url to be put in an img html tag. Note that when rendering a preview, a secured s3 url is returned
      Parameters:
      staticResourceId - the id of the static resource.
      Returns:
      the cid: style url that links to the inlined attachment.

    • addStaticResourceAttachment

      void addStaticResourceAttachment(long staticResourceId)
      Adds the static resource as attachment.
      Parameters:
      staticResourceId - the id of the static resource.

    • getImageUrl

      String getImageUrl(String name)
      Returns the image url of the image with the given name in the current theme.
      Parameters:
      name - the name of the image e.g: 'theLogo'
      Returns:
      if the image exists for the current theme, the url. If theme image doesn't exist, the url of the global image. null if neither exist.

    • getThemeImageUrl

      String getThemeImageUrl(String name)
      Returns the image url of the image with the given name in the current theme.
      Parameters:
      name - the name of the image e.g: 'theLogo'
      Returns:
      if the image exists for the current theme, the url. If theme image doesn't exist, the url of the global image. null if neither exist.

    • getProjectKey

      String getProjectKey()
      Returns the shorthand project key. For example, the ticket key of IT-38 will return IT.

      Returns the shorthand project key.

      Returns:
      the shorthand key for the project that the issue belongs to.

    • getGlobalImageUrl

      String getGlobalImageUrl(String name)
      Returns the global image url of the image with the given name.
      Parameters:
      name - the name of the image e.g: 'theLogo'
      Returns:
      the url if the global image exists.

    • getImageUrl

      String getImageUrl(String name, String projectKey)
      Returns the image url of the image with the given name in the current theme.
      Parameters:
      name - the name of the image e.g: 'theLogo'
      projectKey - only images for this project or global project scope.
      Returns:
      if the image exists for the current theme, the url. If theme image doesn't exist, the url of the global image. null if neither exist.

    • getThemeImageUrl

      String getThemeImageUrl(String name, String projectKey)
      Returns the image url of the image with the given name in the current theme.
      Parameters:
      name - the name of the image e.g: 'theLogo'
      projectKey - only images for this project or global project scope.
      Returns:
      if the image exists for the current theme, the url. If theme image doesn't exist, the url of the global image. null if neither exist.

    • getGlobalImageUrl

      String getGlobalImageUrl(String name, String projectKey)
      Returns the global image url of the image with the given name.
      Parameters:
      name - the name of the image e.g: 'theLogo'
      projectKey - only images for this project or global project scope.
      Returns:
      the url if the global image exists.

    • urlEncode

      String urlEncode(String string)
      URL encodes a string.
      Parameters:
      string - .
      Returns:
      the url encoded version of the string.

    • isCreateOrInChangeLog

      boolean isCreateOrInChangeLog(com.fasterxml.jackson.databind.JsonNode context, String fieldId)
      Checks if a field has been updated in the issue updated context.
      Parameters:
      context - the json context
      fieldId - the field id
      Returns:
      if the field is in the current changelog.

    • isCreate

      boolean isCreate(com.fasterxml.jackson.databind.JsonNode context)
      Checks if webhook event is an Issue Created Event.
      Parameters:
      context - the json context
      Returns:
      if the field is an Issue Created Event.

    • getChangeLogs

      Map<Long,Map<com.fasterxml.jackson.databind.JsonNode,List<com.fasterxml.jackson.databind.JsonNode>>> getChangeLogs(com.fasterxml.jackson.databind.JsonNode context)
      get all related change logs
      Parameters:
      context - context of current template
      Returns:
      changelogs json list.

    • getChangeLogsByShowFields

      Map<Long,Map<com.fasterxml.jackson.databind.JsonNode,List<com.fasterxml.jackson.databind.JsonNode>>> getChangeLogsByShowFields(com.fasterxml.jackson.databind.JsonNode context, Collection<String> fieldIds)
      get all related change logs filtered by showfields
      Parameters:
      fieldIds - fields to show by id
      context - the json context
      Returns:
      changelogs json list filtered out fields with fieldIds.

    • getChangelogAuthors

      Set<com.fasterxml.jackson.databind.JsonNode> getChangelogAuthors()
      get all authors in change logs
      Returns:
      authors set.

    • getChangelogAuthor

      String getChangelogAuthor(com.fasterxml.jackson.databind.JsonNode changelog)
      get all authors in change logs
      Parameters:
      changelog - the json changelog to retrieve author from
      Returns:
      author of changelog.

    • getRequestParticipantAuthor

      String getRequestParticipantAuthor()
      get the latest author for a given request participant recipient in change logs
      Returns:
      author's display name as string.

    • enableDebug

      @Deprecated(forRemoval=true) void enableDebug()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Temporarily added for debugging of event changelog processing - will be removed without warning

    • getDebugMessages

      @Deprecated(forRemoval=true) String[] getDebugMessages()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Temporarily added for debugging of event changelog processing - will be removed without warning

    • indexChangeLogByField

      Map<String,List<com.fasterxml.jackson.databind.JsonNode>> indexChangeLogByField(com.fasterxml.jackson.databind.JsonNode context)
      Returns the change log indexed by field id.
      Parameters:
      context - the context
      Returns:
      a map field id to list of field's changelog

    • getChangeLogsByAuthor

      List<com.fasterxml.jackson.databind.JsonNode> getChangeLogsByAuthor(com.fasterxml.jackson.databind.JsonNode context, String authorId)
      Returns the change log indexed by author.
      Parameters:
      context - the context
      authorId - the ID of the author
      Returns:
      list of changelogs by author

    • getChangeLogFromValue

      String getChangeLogFromValue(com.fasterxml.jackson.databind.JsonNode input)
      Resolves the "from" value from a change log. If the field is a user field, the account ids in the changelog will be converted to the users' display name
      Parameters:
      input - the change log
      Returns:
      the "from" string of the changelog item

    • getChangeLogToValue

      String getChangeLogToValue(com.fasterxml.jackson.databind.JsonNode input)
      Resolves the to value from a change log. If the field is a user field, the account ids in the changelog will be converted to the users' display name
      Parameters:
      input - the change log
      Returns:
      the from string

    • includeOnly

      Map<String,Collection<com.fasterxml.jackson.databind.JsonNode>> includeOnly(Map<String,Collection<com.fasterxml.jackson.databind.JsonNode>> map, Collection<String> fieldIds)
      Returns a copy of the map where the keys not in fieldIds are excluded.

      If the fieldsId is null or empty, the original map is returned.

      Parameters:
      map - the map of field changes
      fieldIds - the whitelist of fields ids.
      Returns:
      the original map if the field id list is null or empty, if not, a map with only the keys found in the fields collection.

    • isNull

      boolean isNull(Object object)
      Checks if a VTL reference is null.
      Parameters:
      object - the VTL reference to check.
      Returns:
      true if the VTL reference is null, false if otherwise.

    • isNotNull

      boolean isNotNull(Object object)
      Checks if a VTL reference is not null.
      Parameters:
      object - the VTL reference to check.
      Returns:
      true if the VTL reference is not null, false if otherwise.

    • setNotify

      void setNotify()
      Marks an update issue template as 'not empty'. You should use it when useful information has been printed and email must be sent.

    • renderValue

      String renderValue(com.fasterxml.jackson.databind.JsonNode issue, String fieldId, Object value)
      Renders a field value according to its metadata. Most of the fields already come pre-rendered in the context. These values should be used (fromString, toString attributes) as this method will assume that.

      Example: timeoriginalestimate value 14400 will render as 4h

      Parameters:
      issue - the issue
      fieldId - the field id
      value - the value
      Returns:
      the formatted value or the original value if the custom render cannot be performed.

    • getDurationBreakdownSeconds

      String getDurationBreakdownSeconds(Object objectValue)
      Transform a time spent object like 51600 into human-readable time 23h 40m
      Parameters:
      objectValue - the number value (number, string or json node)
      Returns:
      the human-readable value.

    • getRecipientType

      RecipientType getRecipientType()
      Returns the RecipientType of the target recipient. It can be used along method setInhibitSending(boolean inhibit) to exclude recipients according their type and the current data at rendering time.
      Returns:
      the RecipientType

    • getPreviousChangeLogs

      List<com.fasterxml.jackson.databind.JsonNode> getPreviousChangeLogs(String issueKey)
      Retrieves the change log from the issue excluding the event's change log (current changes).
      Parameters:
      issueKey - the issue key
      Returns:
      the list of change logs excluding the ones provided in the event.

    • setInhibitSending

      void setInhibitSending(boolean inhibit)
      Marks the template to not be sent.
      Parameters:
      inhibit - boolean to mark/unmark template to be sent

    • setCommentRendered

      void setCommentRendered()
      Used to mark that a comment has been rendered and notification should be sent.

    • setFieldRendered

      void setFieldRendered()
      Used to mark that a field has been rendered and notification should be sent.

    • getRecipient

      String getRecipient()
      Returns the email address of the recipient if provided when rendering an email.
      Returns:
      the recipient or null if it hasn't been provided when rendering the email.

    • getSenders

      Set<String> getSenders()
      Returns:
      the email addresses of the senders if the issue was created or updated via email. It could be more than one sender as multiple issue events may be merged together.

    • isTheRecipientThePersonWhoHasExecutedTheOperation

      boolean isTheRecipientThePersonWhoHasExecutedTheOperation(com.fasterxml.jackson.databind.JsonNode context)
      Return if the rendering of the template is targeted to user that changed or commented the issue.
      Parameters:
      context - the context of the event.
      Returns:
      true if the rendering of the template is targeted to user that changed or commented the issue.

    • getRecipients

      List<String> getRecipients()
      Returns a singleton list with the recipient if provided.
      Returns:
      the list of email address recipients of the rendered email.

    • getWebhookEvent

      String getWebhookEvent()
      Gets the webhook event.
      Returns:
      webhook event type ready to be used an i18n key.

    • truncateMinute

      Date truncateMinute(Date date)
      Returns the date without truncating the minute.
      Parameters:
      date - the date
      Returns:
      same date with 0 seconds

    • getEmailOnlyUsers

      Set<String> getEmailOnlyUsers()
      Return the email addresses of email-only users identified by the custom field set within the Notification Mapping.
      Returns:
      a set of all the email-only users email addresses.

    • getPeopleInvolved

      Set<com.fasterxml.jackson.databind.JsonNode> getPeopleInvolved()
      Resolves the people involved in the issue according to the Notification Mapping configuration.
      Returns:
      a set of JsonNode user objects

    • translateValue

      String translateValue(String fieldId, String value)
      It allows user to translate values that are in English by default. The key of the translation has the pattern fieldId.value.value.

      This is useful to translate Jira static values like Improvement, Task, Critical, Minor, etc.

      If the translation is found, its value is used. Otherwise, the provided value.

      issuetype.value.Improvement=Mejora

      someFieldId.value.theValue=El Valor

      Parameters:
      fieldId - the field id.
      value - the value.
      Returns:
      the translated value or the value if there is no translation.

    • humanReadableByteCount

      String humanReadableByteCount(long bytes)
      Transform bytes into a human-readable value in B, KB or MB depending on the input.
      Parameters:
      bytes - the bytes
      Returns:
      a human-readable string

    • randomUUID

      String randomUUID()
      Generates a random UUID
      Returns:
      a random string.

    • setReplyTo

      void setReplyTo(String replyTo)
      Use this method do dynamically change the reply to email address.
      Parameters:
      replyTo - an email address that will use as the reply to

    • isIssueCreatedByEmail

      boolean isIssueCreatedByEmail(com.fasterxml.jackson.databind.JsonNode context)
      Evaluates if JEMHC created the issue in the event after processing an email. The method uses the issue's entity properties to know if the issue was created by JEMHC.
      Parameters:
      context - the context with the issue
      Returns:
      true if the issue was created by JEMHC from an email

    • getIssueProperty

      com.fasterxml.jackson.databind.node.ObjectNode getIssueProperty(String propertyKey)
      Parameters:
      propertyKey - the issue entity property key to get
      Returns:
      the value of the issue entity property
      See Also:

    • log

      void log(String message)
      Logs the message into the report.
      Parameters:
      message - the message

    • isJsdApprover

      boolean isJsdApprover()
      Use this method to determine if the current user is also a JSD approver on the issue.
      Returns:
      a boolean value stating that the user is (or isn't) an approver on this issue.

    • isNewApprover

      boolean isNewApprover()
      Use this method to see if the current user was added to the issue as an approver in this event.
      Returns:
      a boolean value stating that the user is (or isn't) a newly added approver.

    • isNewRequestParticipant

      boolean isNewRequestParticipant()
      Use this method to check if the current user was added as a request participant in this event.
      Returns:
      a boolean value stating if the current user is (or isn't) a new request participant.

    • isJsdCustomer

      boolean isJsdCustomer()
      Checks if the current user is a JSD customer
      Returns:
      true if the user is a JSD customer, false if not.

    • isJsdProject

      boolean isJsdProject()
      Check if the current project is a Service Desk project.
      Returns:
      true if the current project is a service desk project, false if not.

    • getIssueViewUrl

      String getIssueViewUrl()
      This method resolves the best Issue URL. The URL can either be the Jira issue URL e.g. https://mycompany.atlassian.net/browse/ABC-123 Portal Issue Url e.g. https://mycompany.atlassian.net/servicedesk/customer/portal/5555/ABC-123 If the current project is service desk and the user recipient is a customer, the portal url is returned. Otherwise, the standard Jira Issue Url
      Returns:
      the jira or portal issue url.

    • getItemTo

      String getItemTo(Object item)
      Retrieve a changelogItems 'to' string value
      Parameters:
      item - changelogItem JSONNode
      Returns:
      to value of item

    • getItemToString

      String getItemToString(Object item)
      Retrieve a changelogItems 'toString' string value
      Parameters:
      item - changelogItem JSONNode
      Returns:
      toString value of item

    • getItemFrom

      String getItemFrom(Object item)
      Retrieve a changelogItems 'toString' string value
      Parameters:
      item - changelogItem JSONNode
      Returns:
      toString value of item

    • getItemFromString

      String getItemFromString(Object item)
      Retrieve a changelogItems 'fromString' string value
      Parameters:
      item - changelogItem JSONNode
      Returns:
      fromString value of item