/MailMerge

configs and settings using awdeorio / mailmerge

Primary LanguageShell

This repo serves 2 purposes.

  • Jira Release editor
  • MailMerge

Both are implemented around a GH Actions pipeline, found in the .github/workflows folder. Both can be used with or without each other. Future will tell how this repo will evolve.

Jira Release editor

Source of existence

In Atlassian Jira applying CRUD operations on a release in Jira is not possible without having the role of Project Administrator. At the moment of writing this is a Defect that is gathering interest for quite some years now. To overcome this, this part of the repo is created.

What this part of the repo provides functionality for, is to allow normal users to request this repo to for a CRUD operation. This happens in a interactive way, through command line asking for arguments that are needed for these CRUD operations. Behind the scenes these scripts do locally a git-commit of the users request, and finish that off with a git-push. When a git push is detected in the central repo, a pipeline finishes of the Jira manipulation through a technical QQ account. (see pre-req's)

The benefits:

  • Jira Release manipulations are been tracked now.
  • The need to give people Project Administrator rights in order to manipulate Jira Releases became due.
    From now on, people can use these client scripts and are able to manipulate Jira Releases without the need for the "Project Administrator" role. The user that will do the actual manipulations in Jira is a technical QQ-account.

Pre-req's

  • Having a personal GitHub account to tell GitHub what Jira Release manipulation you want.
  • Having this repo on your local machine. (Clone this repo to your local machine.)
    • Many explanations can be found in the corporate Confluence and the Developer Portal.
  • Having a Linux terminal available to run these client scripts.
    • Git Bash is an example, this can be found as Git for Windows in the WUSS.
    • An even better and more user friendly choice is IntelliJ Community edition, which contains several types of terminals.
    • Top notch, is of course having a Linux machine. There everything is available.
  • No additional Git knowledge required, apart from the concept how Git works. (commit locally, push to remote)
  • Jira access. The scripts provided use either a technical Q-account (server side) to update Jira JQL's. You need a technical Q-account and permission to update the Jira Releases from the json file. (see below)
    Currently, GitHub Actions of this GitHub project takes care of the automation towards Jira updating with a technical user: QQMIBI4.
    At the moment of writing, this project is for MILES4ALL Jira project only.
    In order to have this project able to update your Jira project, we'll need to extract that detail into a property file
    Like that, you would
    • give this QQMIBI4 user permission to your Jira project
    • write your own json payload file (see examples) with your queries in it, commit & push to this repo
    • GitHub Actions will update Jira with your requested Jira Release changes it finds in a changed json files it sees at git push time.

Manual Usage

  • Go to the folder where the client scripts are:
    $cd ./actions/client
  • Show the client scripts
    $ls -lst to see the client scripts if you don't know the by heart.
    • Or look with IntelliJ in the folder structure, which will provide more insights.
  • Type $bash (with the space after)
  • Start typing now the first letters of your script + hit the Tab button; e.g. 'new'+Tab.
    This is standard autocomplete functionality in Linux: you'll see the full name of the script.\Finish off by smashing the Enter key. \other examples:
    • 'bash rel'+Tab -> $bash releaseJiraVersion.sh
    • 'bash ar'+Tab -> $bash archiveJiraVersion.sh
    • 'bash unA'+Tab -> $bash unArchiveJiraVersion.sh
    • 'bash unR'+Tab -> $bash unReleaseJiraVersion.sh
    • 'bash upd'+Tab -> $bash updateJiraVersion + Type further 'D'+Tab -> $bash updateJiraVersionDescription.sh
    • 'bash upd'+Tab -> $bash updateJiraVersion + Type further 'N'+Tab -> $bash updateJiraVersionName.sh
    • 'bash upd'+Tab -> $bash updateJiraVersion + Type further 'R'+Tab -> $bash updateJiraVersionReleaseDate.sh

The client scripts will guide you through all needed information. Once finished, you'll find the GitHub Actions pipeline doing the rest for you: update/create the Jira Release as you requested.

File structure

Scripts Folders

Server scripts

./actions/server contains the heavy fork lifting.
These are the scripts that are launched by the pipeline and to the actual Jira operations for you, but with a technical QQ-account.
./actions/server/createRequestedVersions.sh Does what it suggests it does.
Create requested Releases, which is triggered from client script ./actions/client/newJiraVersion.sh. ./actions/server/updateChangedVersion.sh Does what it suggests it does.
Update Releases, which is triggered as a consequence of git manipulations in the client scripts below.

Client scripts

./actions/client is the location of all client scripts.
They are all interactive, and ask you for the needed input.
It contains is some checking in it as well, e.g. the right data format, already existing Jira releases etc...

Underlying scripts

  • ./lib/lib.sh contains all boilerplate scripts used in the client scripts.
  • ./lib/pipelib.sh contains all boilerplate scripts used in the server scripts.

MailMerge

Simple templates to send from cli, or in automation.
This project has built all needed templates to use with mailmerge.
It consists out of templates (.html) and databases (.csv).
Templates are built for the Jinja2 template engine used by mailmerge.
Databases are the files with variable content parsed into the templates to send.

In the templates the variable names are used with {{}}, e.g. {{variableName}}.
The variables names are found in the database headers.

E.g. 1 template can be used in conjunction with several possible databases.
(only 1 at the time) See Manual Usage section below for combo's.

Pre-req's

  • Python runtime installed (this can be done as one of your steps of your pipeline)
  • credentials of a team mailbox. (not mandatory)
  • mailmerge installed. (see https://github.com/awdeorio/mailmerge) on cli: $ pip install mailmerge
    And you're off to get started!

Manual Usage

Below some explanation how this project is to be used

File structure

Below the file structure to understand the remaining template snippets

  • SystemAvailability.html inherits from
    • Notification.html which is the base of all notifications.
      It has got all images on board to be shown for a notification mail.
      On its turn this inherits from
      • BaseTemplate.html which serves all mail communication needs like
        to, from, cc, subject fields etc.
  • DeploymentSingleMarket.html inherits from
    • Deployment.html which is the base of all deployment related mail communication.
      On its turn this inherits from
      • ActionRequired.html which is the base of all action required mail communication.
        It has got all images on board to be shown for an action required mail.
        On its turn this inherits from
        • BaseTemplate.html which serves all mail communication needs like
          to, from, cc, subject fields etc.
  • DeploymentMultipleMarket.html inherits from
    • Deployment.html which is the base of all deployment related mail communication.
      On its turn this inherits from
      • ActionRequired.html which is the base of all action required mail communication.
        It has got all images on board to be shown for an action required mail.
        On its turn this inherits from
        • BaseTemplate.html which serves all mail communication needs like
          to, from, cc, subject fields etc.

Maintenance

  • Templates can be added, changed etc.
    However, the purpose isn't changing the templates but rather the databases.
    With this it becomes possible to add mail communication as part of your releases.
  • CSV's are a brittle file format.
    To make it a little more robust for field content, all fields are surrounded with double quotes.
    Using ',' within the CSV fields doesn't harm anymore and becomes usable now. (e.g. multiple mail addresses)
    For this reason, avoid using Excel as editor for changing these database files.
    Locale in the west is mostly using ';' as a delimiter.
    Opening the csv databases with Excel and saving
    • removes your double quotes ' " ' !!!
    • replaces comma's ',' by semicolon ';'.!!
      Plenty of good editors are out there better suitable for the job.
      IntelliJ, Notepad++, UltraEdit to name a few.
  • Ideas future usage:
    • Using your commit message as a field for the templates.
    • Having your approval reply mail triggering a pipeline.
    • Having your mail sent when a pipeline is (successfully) finished.