Skip to main content

Read or change an episode’s production plan, change how a new plan starts, and run code when a plan is finalised

Premium Advanced Podcast Workflow

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_id may 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 …/plan answers { plan, publish_date, today, summary }. plan is null without one, else { tasks, finalised, finalised_label }, each task also carrying its status (see Read and set the status of a task in an episode’s production plan, and run code when one changes). publish_date is the episode’s date in the site’s time zone (Y-m-d), null for a draft with no date; today is today there; summary is the plan’s figures, null without a plan.
  • POST …/plan starts a plan from the preset tasks; 409 benecaster_podcast_workflow_plan_exists if the episode has one.
  • PUT …/plan sends { tasks }, the whole list in order, checked as the preset list is (400 benecaster_podcast_workflow_invalid_task_list with data.index). A task whose id is already in the plan keeps its preset_id. Without a plan it is 404 benecaster_podcast_workflow_no_plan.
  • PUT …/plan/finalised sends { finalised: true|false }, the Workbench’s Finalise plan and Back to draft: 400 benecaster_podcast_workflow_invalid_finalised, or 404 benecaster_podcast_workflow_no_plan. A finalised plan’s tasks can still be changed.
  • All need benecaster_rest_permission_admin and 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 as GET does.

Hooks.

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 );

View on GitHub →

Hooks Used

Need this built rather than just documented? See our services →