templating README

README.md

@@ -5,7 +5,7 @@
 * message delivery to: **msteams**, **telegram**, **e-mail**
 * gathering of job **statistics**
 * generating **hints** for users on how to tune their job scripts (see examples below)
-* **templateable** messages
+* **templateable** messages ([readme](./templates/README.md))
 * message **throttling**
 
 ---
@@ -31,6 +31,31 @@ sbatch --mail-type=ALL --mail-user="mailto:useremailA,msteams:usernameB,telegram
 
 To support future additional receiver schemes, a [connector package](connectors/) has to be developed and its [configuration block](cmd/goslmailer/goslmailer.conf.annotated_example) present in configuration file.
 
+---
+
+## Installation
+
+### goslmailer
+
+* place binary to the path of your liking
+* place [goslmailer.conf](cmd/goslmailer/goslmailer.conf.annotated_example) here: `/etc/slurm/goslmailer.conf`
+* point slurm `MailProg` to the binary
+
+### gobler 
+
+* place binary to the path of your liking
+* place [gobler.conf](cmd/gobler/gobler.conf) to the path of your liking
+* start the service (with -c switch pointing to config file)
+
+### tgslurmbot
+
+* place binary to the path of your liking
+* place [tgslurmbot.conf](cmd/goslmailer/goslmailer.conf.annotated_example) to the path of your liking
+  * config file has the same format as goslmailer, so you can use the same one (other connectors configs are not needed)
+* start the service (with -c switch pointing to config file)
+
+---
+
 ## Currently available connectors:
 
 * **msteams** webhook --mail-user=`msteams:`userid

templates/README.md

@@ -0,0 +1,90 @@
+# Templating guide
+
+Goslmailer uses golang [text/template](https://pkg.go.dev/text/template) and [html/template](https://pkg.go.dev/html/template) libraries.
+
+The connectors call `renderer.RenderTemplate` function. 
+
+Data structure you can reference in the template can be found in:
+
+* [rendererer.go](../internal/renderer/renderer.go)
+* [job_data.go](../internal/slurmjob/job_data.go)
+* [sacct.go](../internal/slurmjob/sacct.go)
+
+Example:
+
+* `{{ .Job.SlurmEnvironment.SLURM_JOB_MAIL_TYPE }}`
+* `{{ .Job.JobStats.MaxRSS | humanBytes }}`
+
+[Example telegram html template](./telegramTemplate.html)
+
+Structures:
+
+```
+struct {
+		Job     slurmjob.JobContext
+		UserID  string
+		Created string
+}
+
+type JobContext struct {
+	SlurmEnvironment
+	JobStats           SacctMetrics
+	Hints              []string
+	MailSubject        string
+	PrunedMessageCount uint32
+}
+
+type SlurmEnvironment struct {
+	SLURM_ARRAY_JOB_ID      string
+	SLURM_ARRAY_TASK_COUNT  string
+	SLURM_ARRAY_TASK_ID     string
+	SLURM_ARRAY_TASK_MAX    string
+	SLURM_ARRAY_TASK_MIN    string
+	SLURM_ARRAY_TASK_STEP   string
+	SLURM_CLUSTER_NAME      string
+	SLURM_JOB_ACCOUNT       string
+	SLURM_JOB_DERIVED_EC    string
+	SLURM_JOB_EXIT_CODE     string
+	SLURM_JOB_EXIT_CODE2    string
+	SLURM_JOB_EXIT_CODE_MAX string
+	SLURM_JOB_EXIT_CODE_MIN string
+	SLURM_JOB_GID           string
+	SLURM_JOB_GROUP         string
+	SLURM_JOBID             string
+	SLURM_JOB_ID            string
+	SLURM_JOB_MAIL_TYPE     string
+	SLURM_JOB_NAME          string
+	SLURM_JOB_NODELIST      string
+	SLURM_JOB_PARTITION     string
+	SLURM_JOB_QUEUED_TIME   string
+	SLURM_JOB_RUN_TIME      string
+	SLURM_JOB_STATE         string
+	SLURM_JOB_STDIN         string
+	SLURM_JOB_UID           string
+	SLURM_JOB_USER          string
+	SLURM_JOB_WORK_DIR      string
+}
+
+type SacctMetrics struct {
+        State        string
+        Ncpus        int64
+        Nodes        int
+        Submittime   string
+        Starttime    string
+        Endtime      string
+        CPUTimeStr   string
+        CPUTime      float64
+        TotalCPU     float64
+        TotalCPUStr  string
+        UserCPU      float64
+        SystemCPU    float64
+        ReqMem       uint64
+        MaxRSS       uint64
+        Walltime     uint64
+        WalltimeStr  string
+        Runtime      uint64
+        RuntimeStr   string
+        MaxDiskWrite uint64
+        MaxDiskRead  uint64
+}
+```