Add a "trigger" parameter, and update the README

README.md

@@ -53,7 +53,8 @@ Send message to specified Matrix Room, with the configured parameters
 * `text`: (string) Text to send to the Matrix room as the content.body.
 * `text_file`: (string) File containing text to send to the Matrix room as the content.body.
 * `msgtype`: *Optional.* Message type, m.notice, m.text (default: m.notice)
-* `data_file`: *Optional.* (string) Filename to post using a custom_event message type. If unset, defaults to the data_file on the resource.
+* `data_file`: *Optional.* (string) Filename to post using a custom_event message type. If unset, defaults to the data_file on the resource. If it exists, the file must contain valid JSON.
+* `trigger`: *Optional.* (string) Arbitrary test to add to a "trigger" data item on custom message types.
 * `always_notify`: If true, send a notice even if text_file and data_file are empty. If false, and a text_file is specified but empty, a notification will not be sent.
 
 ## Example
@@ -68,6 +69,7 @@ resources:
     matrix_server_url: https://matrix.org
     token: {{matrix_token}}
     room_id: {{matrix_room_id}}
+    msgtype: com.freelock.data
     data_file: data
 ```
 
@@ -95,3 +97,15 @@ resources:
 
         Result: $TEXT_FILE_CONTENT
 ```
+
+Matrix has the ability to attach and store arbitrary JSON. This can be very useful to send arbitrary results that a bot might use for further action. Freelock uses this ability to pass extensive information about various deployment environment settings, while keeping the human-readable portion brief.
+
+These extra data keys are not sent if using the default `m.notice` message type, but if you define a custom msgtype, this resource will automatically add a JSON object containing the build data -- Job name, pipeline name, build name (the sequence number within this pipeline), build id, and concourse ATC url. It will also attach the contents of a data file added to the `data` key, and a `trigger` key that is useful to easily pass info about a particular Matrix put -- e.g. 'success', 'fail', 'start', 'end', 'info' -- which your Matrix bot might find useful for handling the message.
+```
+  - put: matrix-notification
+    params:
+      msgtype: com.freelock.data
+      data_file: matrix-notification/data
+      trigger: fail
+      message: Test failure.
+```

bin/out

@@ -32,6 +32,7 @@ text_file="$(jq -r '.params.text_file // ""' < "${payload}")"
 thisdata_file="$(jq -r '.params.data_file // ""' < "${payload}")"
 [[ -n $thisdata_file && $thisthisdata_file != $data_file ]] && data_file="${thisdata_file}"
 from="$(jq -r '.params.from // ""' < "${payload}")"
+trigger="$(jq -r '.params.trigger // ""' < "${payload}")"
 text="$(jq '(.params.text // "${TEXT_FILE_CONTENT}")' < "${payload}")"
 thismsgtype="$(jq -r '.params.msgtype // ""' < "${payload}")"
 [[ -n $thismsgtype && $thismsgtype != $msgtype ]] && msgtype="${thismsgtype}"
@@ -78,6 +79,9 @@ EOF
     if [ -n "$DATA_FILE_CONTENT" ]; then
       body=$(echo -n $body | jq -c ".data=$DATA_FILE_CONTENT")
     fi
+    if [ -n "${trigger}" ]; then
+      body=$(echo -n $body | jq -c ".trigger=${trigger}")
+    fi
   fi
 
   compact_body="$(echo -n "${body}" | jq -c '.')"