Chain Reaction information hand-over and usage

[webdb22]

Chain Reaction is a brilliant concept, but I'm struggling with handing over data from one event to the other. I might be missing something too obvious, I've looked into the documentation and some relevant discussions, but I can't figure out how to hand over and use the additional information (source_event, chain_code, chain_description, chain_data) which should be handed over by default.

My use case would be to switch from the current notification via email (which is an out-of.-the-box feature) to being notified via nfty. For that I've discovered a dedicated Cronicle plugin for ntfy, which works fine being used standalone. My approach would be to create one generic event for "Success" and one for "Failure", both using the ntfy Plugin. These events then would be called using the Chain Reaction options from e.g. the "Backup Event" and should get handed over data from the calling event and use it to set title, message, priority, etc. in the ntfy message to be sent.

Any code snippet for what to put in the calling event as well as in the being called event (ntfy) would be highly appreciated, thanks a lot in advance!

[jhuckaby]

It looks like nfty can be invoked with a simple HTTP request. Could you just use the "Web Hook" feature for this?

Ohhhhh I see.... nfty only supports plain text as the HTTP POST body, not JSON like Slack / Discord. Boooooooo!

Well, support for this is coming in Cronicle v2 (Orchestra). That has fully-customizable Web Hooks which can send plain text or anything you want. v2 will be out in early 2025.

In the meantime, I guess chain reactions could work for your use case, but I don't know anything about Joseph Adam's Plugins, so I don't know how to setup a chain reaction in that case.

[webdb22]

Hi Joseph,

thanks a lot for your prompt and elaborate reply! Looking forward to Orchestra and all the new features!

Meanwhile, to make this work with Cronicle, could you share some insights on how to access the data being handed over to the event via Chain Reaction? I might be missing the obvious, but I can't figure out how to e.g. set the "title", which is an input parameter to the ntfy plugin, using data from the source event. The specific ntfy plugin is just to give the big picture, I'm struggling with the basic concept of how to set a parameter in a shell plugin and then use this parameter as an input parameter in a python plugin via Chain Reaction.

[jhuckaby]

You'll have to forgive me, but I really don't know anything about how those 3rd party Plugins work. I also don't know any Python. All I can tell you is how to use the chain reaction system in Cronicle.

Job A needs to "push" data to Job B. So, Job A needs to print a JSON document to STDOUT that Cronicle detects, and "saves" that data to pass it along to Job B as its STDIN.

So Job A would print something like this (shell script example):

# Job A
echo '{"chain_data": { "custom_key": "foobar", "value": 42 }}'

And then that job completes, and launches Job B. Job B can "read" the data from the previous job by reading JSON from STDIN. Example:

# Job B
read input
echo "INPUT: $input"

You will see the chain data as part of the $input variable, in JSON format, along with a bunch of other information about the job. It is up to you to parse the JSON to extract just the data you need.

I am so sorry, but I have no idea how to make this work with Joseph Adam's 3rd party Plugins. You'll have to consult those docs or contact him to see how to pass the correct data to his Plugin.

I apologize that I cannot help further, but this is out of my knowledge area.

Good luck to you!

[webdb22]

@jhuckaby Thanks a lot for your detailed answer, explanations and hints, much appreciated! No worries about 3rd party plugins, it was just to give the full picture! Cronicle is very powerful and flexible, I've mostly struggled with lack of knowledge and basic documentation.

The good news is that after a lot of trial and error I got the basic stuff working! To document my progress, as it might be useful for someone else who is struggling with the same basics as me:

• Passing data from one job to the next is really as simple as printing to STDOUT, i.e. echo in a Shell Script Plugin.
• To assign values from Job A to parameters from Job B, simply use the parameter names in the `chain_params' object (see example below).
• Parameters are case-sensitive when passed from a Shell Script Plugin to a Python Plugin.
• The tricky part is building a valid (!) JSON document in Job A by concatenating strings, variables, etc.
• It seems that a valid JSON document must start on a new line, so any remnants from a previous echo (e.g. from debugging) or a timestamp without a CR/LF will interfere.
• There are no errors thrown, the only indication is that if there is a remnant of the to-be JSON document in Job A's log, then something is wrong.

Below is an example that works (at least for me), it runs ClamAV and passes some parameters to the next job, which is based on the Cronicle plugin for ntfy, to send out notifications via ntfy:

#!/bin/sh

# Enter your shell script code here
clamscan --infected [path-to-files-to-be-scanned]

CLAMAV_RET=$?

case $CLAMAV_RET in
  0) 
    CLAMAV_MSG="ClamAV: No virus found"
    CLAMAV_PRIO="Min";;
  1) 
    CLAMAV_MSG="ClamAV: Virus found!" 
    CLAMAV_PRIO="High";;
  *) 
    CLAMAV_MSG="ClamAV: Other error!" 
    CLAMAV_PRIO="High";;
esac

echo '{ "chain_params": { "priority": "'$CLAMAV_PRIO'", "message": "Return code: '$CLAMAV_RET'", "title": "'$CLAMAV_MSG'" } }'
echo '{ "complete": 1, "code": '$CLAMAV_RET', "description": "'$CLAMAV_MSG'" }'

If you find it useful, feel free to use the hints and examples in e.g. a "Beginner's Guide to Chain Reaction Control"!

What I haven't managed yet is to pass the output of the command called in Job A (e.g. `clamscan') to Job B, so that e.g. the "Summary" of the scan could be used as "Message Body" for Job B. Any idea how to achieve this would be appreciated!

[jhuckaby]

Thank you for all this work! I'm sorry you ran into so much trouble.

The tricky part is building a valid (!) JSON document in Job A by concatenating strings, variables, etc.
It seems that a valid JSON document must start on a new line, so any remnants from a previous echo (e.g. from debugging) or a timestamp without a CR/LF will interfere.

I will make sure that the docs call this out. I do say this, however:

"You need to make sure the JSON is compacted onto a single line, and ends with a single EOL character (\n on Unix)." -- Source: https://github.com/jhuckaby/Cronicle/blob/master/docs/Plugins.md#json-output

But I will add more details about possible interference on the line. It's really NDJSON that Cronicle is expecting, which is an exact format specification. I'll call this out in the docs too.

There are no errors thrown, the only indication is that if there is a remnant of the to-be JSON document in Job A's log, then something is wrong.

This was done deliberately, as broken JSON should not fail a job. Cronicle instead emits the content into the log instead of consuming it. Maybe I can add a warning somewhere somehow. I'll ponder this for a future version.

What I haven't managed yet is to pass the output of the command called in Job A (e.g. `clamscan') to Job B, so that e.g. the "Summary" of the scan could be used as "Message Body" for Job B. Any idea how to achieve this would be appreciated!

There's currently no built-in way to do this. What you can do, however, is pass the output from Job A as a parameter into chain_params for Job B, and then the Job B can emit it into a HTML report: https://github.com/jhuckaby/Cronicle/blob/master/docs/Plugins.md#custom-html-content

Cronicle v2 will have the concept of "workflows" where all the job outputs can be seen on one page. Coming in 2025!

[webdb22]

@jhuckaby No worries! It was a bit challenging, but that's okay!

Thanks for the additional details and explanations, and I agree that most of it is already documented. But for beginners who are not so familiar with JSON and the like, a few examples and pointing out the most common pitfalls might help to get a quick first "success experience" with "Chain Reaction"!

To reiterate, Cronicle is really a great product that "just works", thanks for all the effort you put into it!

Looking forward to Cronicle V2!