This elisp script provides a series of macros that are helpful for managing workflows in Emacs org-mode. When using these macros, it is possible to use org-mode in such a way that it functions like a kanban board where one can move projects between different stages inside a workflow with ease. When combined with org-attach for attachment management, and org-download for drag-and-drop functionality, these macros simplify using org-mode for the management of complicated and interconnected projects.
A common scenario in project management is to have a group of projects of particular types that move between different pre-defined stages within a workflow. For example, in an academic group, a common workflow would be manuscript development which would have the following stages.
- Idea
- Outline
- Draft
- Internal Review
- External Review
- Accepted
- Rejected/Recycling
Each manuscript could be categorized as being inside of one of these stages at any given time, from conception to the time that it is published or archived. It is then natural if using org-mode to structure a workflow having a parent heading called Manuscripts, with each stage being a sub-heading. Living under these sub-headings would be a sub-sub-heading that would represent each manuscript project. There you could keep a running set of notes, links to files, etc. that are helpful in keeping organized while working on each manuscript. It would look like the following structure:
Manuscripts
–> Idea
–>–> Manuscript A
–>–>–> Notes and content for Manuscript A
–> Outline
–>–> Manuscript B
…
–> Rejected/Recycling
–>–> Manuscript Z
The problem with using vanilla org-mode is that moving sub-headings between stages is a bit of a pain. To move the heading one either needs to copy and paste the entire project heading, or do a series of maneuvers to get it to the next/previous stage. Furthermore, if one uses org-attach to attach documents to each manuscript project, the directory structure is not convenient or organized without a lot of discipline from the user. This is where org-workflow comes in.
Org-workflow provides quick macros for moving projects from one stage to the next in a single step. It also provides macros for bubbling projects up to the top of the list or sinking them to the bottom. Beyond these convenience macros, there are also macros for generating and setting up new projects in a very consistent way. When creating a project with org-workflow, it is automatically assigned a unique ID and attachment directory having an automated flat naming structure that is human readable when compiled. For instance, by assigning the heading for Manuscripts above with a :PROJ-TYPE: MANUSCRIPTS property, org-workflow would then know to provide each manuscript project within the workflow with its own unique attachment directory having the naming convention PROJECT-ATTACHMENTS/ORG-FILE-NAME/MANUSCRIPTS-XXXX where XXXX is a user-selected filename for the project. By using org-workflow, one can easily move and track projects and their progress, while keeping a dynamic table of contents to all attached files that is all plain text for preservation and with minimal effort from the user.
For a better illustration of how you can use org-workflow for your own project management needs, see the examples below showing org-workflow in action.
- Put the
org-workflow.elfile into a subfolder of your.emacs.ddirectory. For instance~/.emacs.d/lisp/org-workflow/org-workflow.el - Edit your
init.elor.emacsfile adding the line(add-to-list 'load-path "~/.emacs.d/lisp/org-workflow") - Restart Emacs.
It is easy to modify your init.el or .emacs init file to provide helpful keybindings to the macros provided by org-workflow.
The code below provides an example of a custom setup, including a custom project template and associated keybindings. You can use this to modify and extend your own personal setup.
;;Load the org-workflow package
(require 'org-workflow)
(define-key org-mode-map (kbd "C-c M-<down>") 'org-workflow-move-subtree-to-bottom)
(define-key org-mode-map (kbd "C-c M-<up>") 'org-workflow-move-subtree-to-top)
(define-key org-mode-map (kbd "M-S-<up>") 'org-workflow-move-level-up)
(define-key org-mode-map (kbd "M-S-<down>") 'org-workflow-move-level-down)
(define-key org-mode-map (kbd "C-c C-<return>") 'org-workflow-new-project)
;; Conference project template:
(setq conference-project-subtitle-list
'("Title:"
"Abstract"
"Conference Dates:"
"Talk Date:"
"Talk Time:"
"Duration:"
"Notebook"
"Tasks"
)
)
(defun my-conference-template ()
(interactive)
(org-workflow-template-builder conference-project-subtitle-list)
)
(define-key org-mode-map (kbd "C-c w c") 'my-conference-template)
For drag-and-drop attachments, you can use org-download. Here is an example setup.
;;Setup org-download for drag-n-drop images into org files
(use-package org-download
:ensure t
:defer t
:init
;; Add handlers for drag-and-drop when Org is loaded.
(with-eval-after-load 'org
(org-download-enable)))
(setq org-download-method 'attach)
(setq org-attach-use-inheritance t)
Below we describe each macro provided by org-workflow.
Moves subtree at point to the bottom of the list of subtrees at the same level under a parent heading.
Same as org-workflow-move-subtree-to-bottom but for moving the subtree at point to the top.
This moves the current project at point up one level to the previous stage in a workflow.
Same as org-workflow-move-level-up but for moving the project down one level to the next stage.
Generates a project under the workflow stage at point.
This macro does the following:
- Calls the user to enter a title string. This string is used to title the project heading.
- Calls the user to enter a folder title. This title is used as a short title for the project attachment folder.
- It then creates the project heading with the following properties:
:ID: RANDOMLY-GENERATED-ID-NO:DIR: PROJECT-ATTACHMENTS/BUFFER-NAME/PROJ-TYPE-FOLDER-TITLE-YYYY-MM-DD-HH-MM- Note the
PROJ-TYPEstring comes from this property from any parent heading above the project. - If no parent heading has a defined
PROJ-TYPEproperty, then this is simply left blank.
- Note the
- Generates default subheadings
- Notebook
- Tasks
This macro takes the input (subtitle-list) as a list of strings and uses these strings to create default subheadings for a new project.
Other than having these modified subheading strings, all else is identical to org-workflow-new-project.
This macro converts an existing headline to a project. It detects the PROJ-TYPE property for directory naming just the same as the org-workflow-new-project function does.
It detects whether the DIR property already exists and prompts the user for what to do about it. Options are to cancel renaming the current directory (that is to cancel the operation), or to rename the current directory in the org-file and on the disk, or just in the org file (not renaming the current directory on the disk).
The latter option (nor renaming on the disk) is likely a rare scenario as it would break any existing attachment links within the subtree.
This is a macro that essentially just calls org-workflow-convert-to-project. It is named differently for convenience, but does the same operations since if the project exists, it simply keeps its ID and this triggers to change the directory name.
Note, that if the user selects to change the directory name, all contents from the old folder will be moved which will preserve links using org-attach. This should make it very convenient for one to move projects around with ease while preserving all links and directory structure.
This example uses org-download to achieve dragging and dropping of files as attachments into projects.
The settings in the .emacs init file for org-download were as follows.
;;Setup org-download for drag-n-drop images into org files
(use-package org-download
:ensure t
:defer t
:init
;; Add handlers for drag-and-drop when Org is loaded.
(with-eval-after-load 'org
(org-download-enable)))
(setq org-download-method 'attach)
(setq org-attach-use-inheritance t)
