Read or change an episode’s production plan, change how a new plan starts, and run code when a plan is finalised
An episode’s production plan is its own copy of the show’s preset tasks (see Read or change a show’s preset task list, and run code when a show saves it), stored on the episode as post meta _benecaster_workflow_plan: { tasks: [ { id, name, offset_days, duration_days, preset_id, status } ], finalised, finalised_at }. preset_id is the preset task it came from, '' for a one-off; status is the task’s status (see below); finalised_at is UTC.
A new draft, pending or future episode on a show with Podcast Workflow on gets a plan when Benecaster fires benecaster_episode_created; a published or private one does not. The plan is copied once: later changes to the preset list never reach it. Due dates stay relative to the publish date (offset_days, and duration_days ending on the due date); calendar dates are worked out in the site’s time zone for display and never stored.
A plan moves with its episode, and there is nothing to hook. The plan is read by episode id alone, and moving an episode to another show changes only its post_parent, so the plan, its task statuses and its finalised state go with it. Podcast Workflow registers no benecaster_episode_move_after listener, on purpose; do not add one that copies, clears or restarts a plan.
- Moved to a show where Podcast Workflow is on, that show’s Workbench shows the same plan, and the old show’s routes refuse the episode with
409 benecaster_podcast_workflow_other_show. - Moved to a show where it is off, the plan is kept untouched and shown nowhere; that show’s routes answer
403 benecaster_podcast_workflow_off_for_show. Moved back, or with the add-on switched on there, it shows again as it was. - A moved plan’s
preset_idmay name a task the new show’s preset list does not have.
Routes, all on /benecaster-podcast-workflow/v1/shows/{show_id}/episodes/{episode_id}/plan:
GET …/plananswers{ plan, publish_date, today, summary }.planis null without one, else{ tasks, finalised, finalised_label }, each task also carrying itsstatus(see Read and set the status of a task in an episode’s production plan, and run code when one changes).publish_dateis the episode’s date in the site’s time zone (Y-m-d), null for a draft with no date;todayis today there;summaryis the plan’s figures, null without a plan.POST …/planstarts a plan from the preset tasks;409 benecaster_podcast_workflow_plan_existsif the episode has one.PUT …/plansends{ tasks }, the whole list in order, checked as the preset list is (400 benecaster_podcast_workflow_invalid_task_listwithdata.index). A task whoseidis already in the plan keeps itspreset_id. Without a plan it is404 benecaster_podcast_workflow_no_plan.PUT …/plan/finalisedsends{ finalised: true|false }, the Workbench’s Finalise plan and Back to draft:400 benecaster_podcast_workflow_invalid_finalised, or404 benecaster_podcast_workflow_no_plan. A finalised plan’s tasks can still be changed.- All need
benecaster_rest_permission_adminand the Workbench’s per-show checks (404 benecaster_podcast_workflow_show_not_found,403 benecaster_podcast_workflow_off_for_show,404 benecaster_podcast_workflow_episode_not_found,409 benecaster_podcast_workflow_other_show). Each answers asGETdoes.
Hooks.
- benecaster_podcast_workflow_plan_from_preset, a filter,
( array $tasks, int $episode_id, int $show_id ): the tasks a new plan starts with. A row that is not a valid task is dropped. - benecaster_podcast_workflow_before_save_plan and benecaster_podcast_workflow_after_save_plan, actions
( int $episode_id, array $plan, int $show_id ), around every write. - benecaster_podcast_workflow_before_finalise_plan and benecaster_podcast_workflow_after_finalise_plan, actions
( int $episode_id, bool $finalised, int $show_id ), around finalising (falseis Back to draft), fired only on a change.
Code
<?php
// Add a one-off task to every plan started on show 12.
add_filter( 'benecaster_podcast_workflow_plan_from_preset', function ( array $tasks, int $episode_id, int $show_id ): array {
if ( 12 === $show_id ) {
$tasks[] = [ 'id' => 'my-plugin-legal-check', 'name' => 'Legal check', 'offset_days' => -3, 'duration_days' => 1, 'preset_id' => '' ];
}
return $tasks;
}, 10, 3 );
add_action( 'benecaster_podcast_workflow_after_finalise_plan', function ( int $episode_id, bool $finalised, int $show_id ): void {
if ( $finalised ) {
my_plugin_post_to_team_chat( $episode_id );
}
}, 10, 3 );
Hooks Used
Need this built rather than just documented? See our services →