About

This program can be run on a cron job to create recurring cards in the Kanbanize system. While Kanbanize has support for limited "runtime policies" that can achieve this same goal, the number of runtime policies allowed is severely limited and not enough to create many different recurrence schedules.

Installation

Clone the Git repository to your machine.

git clone https://github.com/middlebury/kanbanize-recurring-cards.git

Install composer if you don't have it.

curl -sS https://getcomposer.org/installer | php

Install dependencies via composer.
```
php composer.phar install
```
Get your account-specific Kanbanize API key under Account >> API in Kanbanize. You will need this later.
Copy the config.php.example file to config.php and configure your values.

Usage

The bin/krc_cron command should be set up to run via cron no more frequently than once per hour. The command has one required argument --cron-freq-hours=<hours> which takes an integer number of hours that indicate time-window between cron runs (minimum 1 hour).

Card definitions should be placed in the cards/ directory as .json files.

You can test the schedule of card creation by using the bin/krc_test command which will run through all of your card definitions for each cron-run in the time-frame you specify and will provide a statement of when cards would be created without actually creating them. Example:

bin/krc_test --start-date=2016-01-01 --end-date=2017-01-01 --cron-freq-hours=24

Card Definitions

Add .json files to the cards/ directory that define each of your recurring cards. The hours, start_date, recurrence, and board properties are all required. The additional properties are defined by the KanbanizeAPI's create_new_task method. Custom fields are supported and can be specified by name.

{
  "hour": 8,
  "start_date": "2016-01-01",
  "recurrence": "FREQ=WEEKLY;BYDAY=MO",
  "board": 2,
  "column": "Requested",
  "title": "Check for updates to the system",
  "description": "Documentation can be found in the <a href=\"http://wiki.example.edu/system_updates\">wiki</a>.",
  "color": "794d20",
  "priority": "Average",
  "tags": "WordPress,Periodic"
}

hour - An integer from 0-23. The hour at which this recurrence should occur.
start_date - A date string of the form YYYY-MM-DD. The date on which recurrence begins. Think of this like the first date of a recurring calendar item. This may effect the offset of the recurrences if they are something like "every 2 days".
recurrence - A recurrence rule string as defined by RFC2445 (iCalendar specification) and implemented by the Recurr library.

Examples:
- FREQ=WEEKLY;BYDAY=MO - Weekly on Mondays.
- FREQ=MONTHLY;BYMONTHDAY=1 - Monthly on the first of the month.
- FREQ=MONTHLY;BYDAY=MO;BYSETPOS=1 - Monthly on the first Monday of the month.
- FREQ=YEARLY;BYMONTH=2,6,9;BYMONTHDAY=1 - 3 times per year on Feb 1, Jun 1, and Sept 1.
deadline-offset - An optional ISO-8601 duration such as P5D. This field will set a deadline field on the card offset from the current date by this much.

Templates

Templates allow you to to define sets of default values that can be inherited across your card definitions in cards that specify the template in their templates property:

{
  "templates": ["weekly"],
  "title": "Updates WP plugins and themes",
  ...
}

Here's an example of a template you might put at templates/weekly.json:

{
  "hour": 8,
  "start_date": "2016-01-01",
  "recurrence": "FREQ=WEEKLY;BYDAY=MO"
}

Template values only get applied if the value is not specified in the card definition itself or a previous template (if multiple templates are applied).

Copyright and License

Authors

Adam Franco