MailTask User Guide

1. MailTaskUser Guide

2. Agenda • Whatis MailTask? • What constitutes Mail Template? • Where to getMailTask? • MailTasktrial version restrictions • MailTasklicenseacquisition • MailTaskactionsvisible from Jira UI • Mail Templates tabundereachproject • Actionsaccessible from ViewIssuePage • Create Mail Templateaction

3. WhatisMailTask? • MailTaskpluginisintended to be installedontoJirainstance. It’smainpurposeis to allowuserscreatetheirowncustomizable mail templateswhichcan be usedatappropriatetime to sendinformationaboutanyissue in form of the mail.The importantthinghereisthatMailTaskdoesn’ttry to sendmails by itself – it’sonlyused to prepare mail based on created mail template and start default mail clientfor real mail sending.

4. Whatconstitutes Mail Template? • By term Mail Template we meansomekind of plaintextmessage with insertedspecialtagswhichareinterpreted in specialwayby ourpluginduring mail template rendering. Suchtemplatetagsarecalled „variables” (whyvariables – becouseitsvalue in not constant and strictlydepend on issue for whichuser want to rendertemplate). • Fewexamples of mail templatesvariablesmayinclude • <issuetype/> • <priority/> • <reporter/> • <assignee/> • <summary/> • <description/>

5. Whatconstitutes Mail Template? • Allmentionedvariablesarederived from OOTB standard issuefields. Therearealsovariableswhichrepresentcustomfields. In nearfuture we areplanning to introducevariableswhichare not strictlyrelated with issue, for examplevariablesuch as „<current-time/>”, „<current-date/>”, „<project-key/>”. • In general we areplanning to providesomevariableswhichvaluewill be dynamicallycalculatedatsendingtime. User may want for exampleinclude in his mail templatesinformationaboutJira version, installedplugins and so on. • We areawarethatitmay be difficult to satisfyallusers and provideallrequiredvariablesso we areplanning to extendourmail templateengine to allowuser to installtheyownvariables as plugin. To do this we have to createeasyapi for customextending.

6. Where to getMailTask? • MailTaskpluginisavailableatAtlassian Marketplace from whereyoucanobtainmoreinformationaboutourpluginincludingdocumentation and compatibilitygridshowing for whichMailTask version can be installed on which version of Jira.Atlassian Marketplace it’salso the right place to acquirelicenceormanageexisting one. • AtlassianMarketplace pluginpage: • https://marketplace.atlassian.com/plugins/pl.com.tt.mailtask.MailTask

7. MailTasktrial version restrictions • Trial version of the MailTaskhasfullfunctionalityfor specifiedamount of time – mostly one month. • Duringthis period youcancreateand edit mail templates as well as sendingmailsrendered from mail templatesusingyourfavorite mail client. • Whentrial version expiresfunctionalitysuch as creating mail templates, editing, cloning and sendingisdisabled. Youcanalwaysdeleteexisting mail templates.

8. MailTasklicenseacquisition • MailTasklicensecan be retrieved from Atlassian Marketplace pageas well as from UPM (Universal Plugin Manager) afterinstallingplugin. YoucanretrievebothFree Trial license and commersial one usingbuttons from UPM.

9. MainTaskactionsvisible from Jira UI • MailTaskactionsareplacedundereachprojectindividually as anadditionaltabnamed „Mail Templates”. Thistabacts as mainadministrationscreenwhichallowsmanagingall mail templates per eachproject. • For exampleifuserhave 3 projectsthen for eachproject he canfindadditionaltab „Mail Templates” whichallowshim to manageall mail templates for specificproject. • Thereisalsoone another place whereyoucanfindMailTaskrelatedactions – this place is a ViewIssuepage. From this place youcancreatenew mail templates for specificissuetypewhichisderived from currentviewedissue. Youcanalso list all mail tamplates for thatissuetypeand afterchoosing one open default mail client for selectedtemplate.

10. Main Templates tab under each project • From thisscreenyoucanmanageyourexisting mail templates as well as createnewones. Youcanperformactionslike Edit, Deleteand Preview on each mail template. Thereisalsoavailablebulkaction – „Deleteselected”.

11. Main Templates tab under each project • Mail Templates tabpresentsall mail templatesregadless for whattypetheyare. Youwillsee for example mail tamplates for „Bug” issuetypealong with „New Feature”, „Improvement” and etc. • Eachrowrepresent one mail template. Columnnamesdescribewellwhatis the purpose of suchcolumn (whattype of informationitholds). • Column „TemplateName” isjustname of the template - youcanclick on it to previewsuchtemplate and seemoreinformations and realatedactions. • Column „Creator User” shows the userwhocreatedthistemplate. Youcanview profile of thisuser by onceagainclicking on itsname.

12. Actions accessible from View Issue Page • As youhaveseenyoucanmanageallyour mail templatesdirectly from „Mail Templates” tab. Youcancreatetemplatesregardless of itstype. As anopposition list of mail templatesvisible from ViewIssuePagewillcontainonly mail templateswhichareexactly the same type as issuebeingviewed. For exampleyouwillseeonly „Bug” templatesifyouareaccessing mail templates list from issuepageof thattype. • Youcanalsocreatenew mail templatesdirectly from ViewIssuePage – the differencebeetwen the same actionaccessible from „Mail Templates” tabisthatitwill by defaultcreatenewtemplate for preselectedissuetype. We makeanassumptionherethatanycreateoperation from thislevelshould by defaultcreatetemplate for the same issuetype as currentlyviewedissuehas.

13. Actions accessible from View Issue Page • Actions for MailTaskvisible from ViewIssuePageareimplemented as menu itemsas seen on the followingscreen.

14. Actions accessible from View Issue Page • „Send Mail” actionwillactually display another dialog rathersendan email. This dialog in turn display all mail templates for specificissuetype. Youcanseehowitlooks on the followingscreen.

15. Actions accessible from View Issue Page • As youcanseedisplayed dialog showsonlytemplateswhichare of type „Bug”. Youcanalsonoticethatthereareavailabletwoactions for eachrow (each mail template). Youcanpreview mail templateby clicking on „Preview” link and most importantlyyoucanrenderchoosed mail template and open renderedresultusingdefault mail client. Onceagainactionname „Send” doesn’tmeanMailTaskperformanyaction to sendthis mail by itself. InsteadMailTaskwill open suchrendered mail template in new mail windowprovided by yourdefault mail client. Thisintentionally was implemented as is and have major adventagesoverjustsendingsuch email. One of the most valuable profit of thisbehaviouristhat we canmakesomemodificationbeforesendingsuch email, we canaddanotherrecipients, we canmodifysubjectof the mail, and finaly we keepallhistoryaboutsendedmailsso we can go back to themifneeded.

16. Actions accessible from View Issue Page • Belowis the screenshotpresentingnew email windowprovided by one of popular mail clients.

17. Create Mail Templateaction • Belowyoucanseescreenwhichallowyou to createnew mail template. Previously we mentioned on whichpagesyoucanfindcreateaction. In the nextfewparagraphs we willtry to describeallfieldsvisibledurringcreating mail template. • Name • IssueType • Adduser(s) to receivers list • Adduser(s) to carboncopyreceivers list • Select issue role(s) • Definesubject • Define body • Availablefields • Makeshared

18. Create Mail Templateaction

19. Create Mail Templateaction – Fields description • Name • To this field youcanenteranythingthatwill be helpful for you to recognizeparticular mail template. This field doesn’thave to be uniqueaccrossallproject and even the same project. Internallyeach mail templateis in factrepresented by itsunique id. • IssueType • This field defines for whichissue mail templatewill be in use. Eachissuecan be of differentissuetype. In turneachissuetypecanhavedifferent set of fieldsand therefor we have to make a distinctionbetween mail templates. Mail Templatecreatedfo „Bug” issuetypecan be invalid for anotherissuetypesuch as „Improvement”. Whilecreating mail templateusercan insert somevariablesrelevant for selectedissuetypewhichrepresents OOTB issuefields. Anotherissuetypemaylack of some of thisfields– thatiswhy we define mail template per issuetype.

20. Create Mail Templateaction – Fields description • Adduser(s) to receivers list • Youcantypehereuserlogins (uniquenames), userfullnamesand useremails. Youareprovided with auto assistantdurringtypeing for convenience. This field will be maped to „To” field of your mail client. Allusersselected in this field will be considered as anreciepients of the mail renderedbasing on mail template. • Adduser(s) to carboncopyreceiverslist • Similarly as for previouslydescribed field this field alsohas auto assistfeature, but the meaning of this field isslightydifferent as itrepresentsuserswhichyou want to include in mail reciepients but oryginalymessageistargeted to someoneelse.

21. Create Mail Templateaction – Fields description • Select issue role(s) • Besides of twopreviouslydescribedfieldsusercanchoose one of fourpredefinedrolesfor which he also want to send mail. For examplethereis „Assignee” and „Reporter” role whichwhilechoosenmeansthat mail should be alsoaddressed to userwhoisassigned to specificissue and userwhohascreatedthatissue. Youcanselectmorethan one role by holding ctrlbuttonwhileselecting. • Definesubject • This field becomessubject of the mail. Youcantypehereanythingyou want in form of plaintext as well as insert somevariableswhichwill be replaced by real valuesdurring mail template rendering. Variable list can be discussedlater.

22. Create Mail Templateaction – Fields description • Definebody • This field becomes body of the mail. Similarly as for subject field youcantypehereanymessage and additionally insert somevariableswhichwill be replaced by real valueswhile rendering mail template. • Availablefields • Dropdown list of variablesavailable for insertion. Actuallythis list shows OOTB fields and CustomFieldswhichusercanuse for currentissuetype. • Makeshared • By selectingthischeckboxcreator of the mail templateallowsotherusers to usesuchtemplate. Otheruserscansendmailsusingthistemplate, but theydoesn’thavepermissions to editand deleteactions.