Feature: Dynamically fire an action on-demand during a job: Instant Job Actions

Author: jhuckaby

docs/data.md

@@ -2890,6 +2890,7 @@ Each action has a `condition` property which specifies when it should fire.  The
 | `tag:TAGID` | Fires on job completion only when a specific tag is present on the job. |
 | `alert_new` | Fires when a new alert is triggered on a server. |
 | `alert_cleared` | Fires when an active alert has cleared. |
+| `instant` | Special condition used for firing dynamic actions on-demand during a job. |
 
 #### Action.type
 

docs/plugins.md

@@ -424,7 +424,7 @@ If you want to have xyOps delete the files for you after uploading, specify an o
 
 Note that if you send multiple messages with `files` properties, the previous list is overwritten (i.e. the latter prevails).
 
-##### Tags
+##### Job Tags
 
 To **add** tags to the current job, use the following "push" message format:
 
@@ -439,7 +439,7 @@ To **add** tags to the current job, use the following "push" message format:
 
 The `push` object is used here to instruct xyOps to "push" (append) tags onto the existing set (you cannot replace or delete tags).  The tags themselves should be valid [Tag.id](data.md#tag-id)s, and duplicates are automatically removed.
 
-##### Actions
+##### Job Actions
 
 To **add** actions to the current job, use the following "push" message format.  This example would send an email to a specific address when the job completes:
 
@@ -448,7 +448,7 @@ To **add** actions to the current job, use the following "push" message format.
 	"xy": 1,
 	"push": {
 		"actions": [
-			{ "condition": "complete", "type": "email", "email": "admin@mycompany.com", "enabled": true }
+			{ "condition": "complete", "type": "email", "email": "admin@mycompany.com", "users": [], "enabled": true }
 		]
 	}
 }
@@ -467,6 +467,19 @@ Here is another example which will launch a subsequent job when the current job
 }
 ```
 
+And if you want the action to run *instantly* (i.e. do not wait for the job to complete), use the special `instant` condition, like this:
+
+```json
+{
+	"xy": 1,
+	"push": {
+		"actions": [
+			{ "condition": "instant", "type": "channel", "channel_id": "sev1", "enabled": true }
+		]
+	}
+}
+```
+
 The `push` object is used here to instruct xyOps to "push" (append) actions onto the existing set (you cannot replace or delete actions).  See [Action Types](actions.md#action-types) for all the possible action objects you can add here.
 
 ##### Server Data

docs/tags.md

@@ -46,7 +46,7 @@ Notes:
 - Tag IDs must exist; define them first in the UI or via API.
 - Duplicate tags are removed automatically.
 
-For details on plugin I/O, see [Plugins → Tags](plugins.md#tags).
+For details on plugin I/O, see [Plugins → Tags](plugins.md#job-tags).
 
 
 ## Tag-Driven Actions

htdocs/js/pages/Base.class.js

@@ -1729,6 +1729,7 @@ Page.Base = class Base extends Page {
 		var title = ucfirst(source);
 
 		switch (source) {
+			case 'job': icon = 'timer-outline'; break;
 			case 'event': icon = 'file-clock-outline'; break;
 			case 'workflow': icon = 'clipboard-flow-outline'; break;
 			case 'alert': icon = 'bell-outline'; break;

htdocs/js/pages/Job.class.js

@@ -551,11 +551,11 @@ Page.Job = class Job extends Page.PageUtils {
 			this.getJobSnapshots();
 			this.renderPluginParams('#d_job_params');
 			this.renderEventParams();
-			this.renderJobActions();
 			this.renderJobTags();
 			this.renderMediaSlideshow();
 		}
 
+		this.renderJobActions();
 		this.setupCharts();
 		this.updateUserContent();
 		this.getJobAlerts();
@@ -1524,7 +1524,7 @@ Page.Job = class Job extends Page.PageUtils {
 		// we're only interested in actions that actually fired (and aren't hidden)
 		var actions = this.actions = (job.actions || []).filter( function(action) { return !!(action.date && !action.hidden); } );
 
-		// for workflows, some actions may be 'orphaned' and not attached to any sub-job
+		// for workflows, include all sub-job actions as well
 		if (workflow && workflow.state && workflow.nodes) {
 			find_objects( workflow.nodes, { type: 'action' } ).forEach( function(node) {
 				var state = workflow.state[node.id];
@@ -1534,6 +1534,9 @@ Page.Job = class Job extends Page.PageUtils {
 			} );
 		}
 
+		// sort actions by date ascending
+		sort_by( actions, 'date', { type: 'number', dir: 1 } );
+		
 		// decorate actions with idx, for linking
 		actions.forEach( function(action, idx) { action.idx = idx; } );
 
@@ -1546,7 +1549,7 @@ Page.Job = class Job extends Page.PageUtils {
 		var html = '';
 
 		var grid_args = {
-			rows: sort_by(actions, 'condition'), // sort in place, so idx works below
+			rows: actions,
 			cols: cols,
 			data_type: 'action'
 		};
@@ -1564,7 +1567,7 @@ Page.Job = class Job extends Page.PageUtils {
 			return [
 				'<button class="link nowrap" onClick="' + link + '"><b><i class="mdi mdi-' + disp.condition.icon + '"></i>' + disp.condition.title + '</b></button>',
 				'<i class="mdi mdi-' + disp.icon + '">&nbsp;</i>' + disp.type,
-				self.getNiceActionSource(item.source || 'event'),
+				self.getNiceActionSource(item.source || 'event') + ((item.count > 1) ? ` (x${commify(item.count)})` : ''),
 				disp.desc,
 				self.getRelativeDateTime(item.date, true),
 				'<i class="mdi mdi-clock-check-outline">&nbsp;</i>' + get_text_from_ms_round( Math.floor(item.elapsed_ms), true),
@@ -1583,12 +1586,15 @@ Page.Job = class Job extends Page.PageUtils {
 		var action = this.actions[idx];
 		var disp = self.getJobActionDisplayArgs(action); // condition, type, text, desc, icon
 		var details = action.details || "";
-		var nice_date = this.getRelativeDateTime(action.date).replace(/\&nbsp;<\/i>/g, '</i>');
+		var nice_date = this.getRelativeDateTime(action.date, true).replace(/\&nbsp;<\/i>/g, '</i>');
 
 		var header = "";
 		header += `- **Action Type:** ${disp.type}\n`;
+		header += `- **Description:** ${disp.desc}\n`;
 		header += `- **Condition:** ${disp.condition.title}\n`;
 		header += `- **Source:** ${ucfirst(action.source || 'event')}\n`;
+		if (action.id) header += `- **Node ID:** \`${action.id}\`\n`;
+		if (action.count && (action.count > 1)) header += `- **Invocations:** \`${commify(action.count)}\`\n`;
 		header += `- **Date/Time:** ${nice_date}\n`;
 		header += `- **Result:** ${action.description || 'OK'}\n`;
 
@@ -1597,6 +1603,10 @@ Page.Job = class Job extends Page.PageUtils {
 
 		details = header + details;
 
+		if (action.count && (action.count > 1)) {
+			details = details.trim() + `\n\n**Note:** This action was invoked ${commify(action.count)} separate times, but only the latest invocation details are displayed here.  See the workflow sub-jobs for each individual action invocation details.`;
+		}
+		
 		var title = "Job Action Details: " + disp.type;
 		if (action.code) title = '<span style="color:var(--red);">' + title + '</span>';
 
@@ -3472,6 +3482,13 @@ Page.Job = class Job extends Page.PageUtils {
 				this.renderJobLimits();
 				this.getJobSnapshots();
 			break;
+			
+			case 'action_append':
+				var action = pdata.action;
+				if (!this.job.actions) this.job.actions = [];
+				this.job.actions.push( action );
+				this.renderJobActions();
+			break;
 		} // switch
 	}
 

htdocs/js/pages/PageUtils.class.js

@@ -1892,6 +1892,9 @@ Page.PageUtils = class PageUtils extends Page.Base {
 			disp.condition = { title: "On " + tag.title };
 			disp.condition.icon = tag.icon || 'tag-outline';
 		}
+		else if (!disp.condition && (action.condition == 'instant')) {
+			disp.condition = { title: "Instant", icon: 'creation' };
+		}
 
 		switch (action.type) {
 			case 'email':

lib/action.js

@@ -96,7 +96,20 @@ class Actions {
 			function(action, callback) {
 				self.runJobAction(job, action, callback);
 			},
-			callback
+			function() {
+				if (self.shut) return callback();
+				
+				// wait for any instant actions to complete
+				async.whilst(
+					function() {
+						return !!Tools.findObject( job.actions, { condition: 'instant', enabled: true, active: true } ) && !self.shut;
+					},
+					function(callback) {
+						setTimeout( function() { callback(); }, 250 );
+					},
+					callback
+				); // whilst
+			}
 		); // async.each
 	}
 
@@ -155,14 +168,20 @@ class Actions {
 			if (action.code) self.logError( action.type, action.description, { job: job.id } );
 			else self.logAction( 8, action.type + ": " + action.description, { job: job.id } );
 
-			// cleanup workflow node state
+			// update workflow node state
+			// note: for multiplex/repeat/split nodes, this clobbers (latter prevails)
 			if (wf_node_state) {
 				Tools.mergeHashInto(wf_node_state, action);
 				wf_node_state.active = false;
 				wf_node_state.completed = Tools.timeNow();
+				wf_node_state.count = (wf_node_state.count || 0) + 1;
 				if (wf_conn_state) wf_conn_state.completed = Tools.timeNow();
+				self.doPageBroadcast( 'Job?id=' + job.workflow.job, 'action_append', { action } );
 			} // workflow
 
+			// notify appropriate page to refresh action table
+			self.doPageBroadcast( 'Job?id=' + job.id, 'action_append', { action } );
+			
 			callback();
 		});
 	}
@@ -264,7 +283,7 @@ class Actions {
 		if (!callback) callback = noop;
 
 		var hook_data = this.getJobHookData(job, action);
-		this.appendMetaLog(job, "Firing web hook: " + action.web_hook);
+		this.appendMetaLog(job, "Firing web hook: #" + action.web_hook);
 		this.logAction(9, "Firing job web hook for " + action.condition + ": " + action.web_hook);
 
 		// allow action to append to the text param
@@ -604,7 +623,7 @@ class Actions {
 		// add one or more tags to the job
 		if (!callback) callback = noop;
 
-		this.appendMetaLog(job, "Adding tags to job: " + action.tags.join(', '));
+		this.appendMetaLog(job, "Adding tags to job: {" + action.tags.join(', ') + "}");
 		if (!job.tags) job.tags = [];
 		job.tags = job.tags.concat( action.tags );
 
@@ -650,7 +669,7 @@ class Actions {
 			return callback();
 		}
 
-		this.appendMetaLog(job, "Taking snapshot of server: " + job.server);
+		this.appendMetaLog(job, "Taking snapshot of server: #" + job.server);
 
 		this.createSnapshot(job.server, { source: 'job' }, function(err, id) {
 			if (err) {
@@ -1125,7 +1144,7 @@ class Actions {
 			}
 		}
 
-		this.appendMetaLog(job, "Running custom action Plugin: " + plugin.id);
+		this.appendMetaLog(job, "Running custom action Plugin: #" + plugin.id);
 		this.logAction(9, "Firing action Plugin for " + action.condition + ": " + plugin.id + ": " + child_cmd);
 
 		var child = cp.exec( child_cmd, child_opts, function(err, stdout, stderr) {

lib/job.js

@@ -52,6 +52,7 @@ class Jobs {
 
 		if (!job.limits) job.limits = [];
 		if (!job.actions) job.actions = [];
+		if (!job.tags) job.tags = [];
 
 		// unique id for job
 		job.id = Tools.generateShortID('j');
@@ -1229,13 +1230,23 @@ class Jobs {
 			delete updates.tags;
 
 			// push system (for adding actions, limits, tags, etc.)
-			if (updates.push) {
+			if (updates.push && Tools.isaHash(updates.push)) {
 				for (var key in updates.push) {
-					if (!job[key]) job[key] = [];
 					if (Array.isArray(job[key])) job[key] = job[key].concat( updates.push[key] );
 				}
+				
+				// make sure all pushed actions (regardless of condition) have a source set
+				Tools.findObjects( updates.push.actions || [], { enabled: true } ).forEach( function(action) { 
+					action.source = 'job';
+				} );
+				
+				// run instant actions instantly
+				Tools.findObjects( updates.push.actions || [], { condition: 'instant', enabled: true } ).forEach( function(action) { 
+					self.runJobAction(job, action); 
+				} );
+				
 				delete updates.push;
-			}
+			} // updates.push
 
 			var context = { job, config: { base_app_url: self.config.get('base_app_url') } };
 

lib/multi.js

@@ -764,6 +764,11 @@ class Multi {
 
 			if (!self.jobDetails[job.id]) self.jobDetails[job.id] = {}; // sanity
 
+			// cancel any actions that got cut off in the middle
+			(job.actions || []).forEach( function(action) {
+				if (action.active) delete action.active;
+			} );
+			
 			// set starting jobs to 'ready', so they get re-started on the next tick
 			if (job.state == 'starting') {
 				self.logJob(6, `Changing job state from starting to ready: ${job.id}`);