1.1. Task trackers

First, include the required parts of the library and indicate our task trackers and specific projects:

(require '[flower.tracker.core :as tracker.core]
         '[flower.tracker.proto :as tracker.proto])

;; Our trackers definition
(def pt-trackers (let [organization-url "https://github.com/PositiveTechnologies"]
                   (tracker.core/trackers (tracker.core/start-component {})
                                          {:pt-github {:tracker-type :github
                                                       :tracker-url organization-url
                                                       :tracker-projects ["flower"]}})))

Here we created the pt-trackers hash map with :pt-github as a key and a list of flower.tracker.github.tracker.GithubTracker instances as a value (defined by :tracker-type :github). You may indicate your own tracker type (:github, :gitlab, :jira, or :tfs) in :tracker-type, your company URL for the tracker in :tracker-url, and your current projects in :tracker-projects. Make sure you specified the :auth key in start-component.

Here is a shorthand notation to create a single tracker record:

(def pt-github-tracker (tracker.core/get-tracker "https://github.com/PositiveTechnologies/flower"))

The tracker type is identified by its domain name. If it failed to get identified automatically, use the flower.tracker.core/with-tracker-type macro to set the type manually:

(require '[flower.tracker.core :as tracker.core])

(tracker.core/with-tracker-type :jira
  (def jira-tracker (tracker.core/get-tracker "https://jr.example.com/projects/EXAMPLE/summary")))

Now you are all set to check your list of issues on GitHub:

(tracker.proto/get-tasks pt-github-tracker)

The next call for this method will give you the same result at lightning speed. As we mentioned in the beginning, if you want to get new values from the task tracker, clear cache by doing this:

(require '[flower.tracker.github.common :as github.common]
         '[flower.tracker.github.task :as github.task])

(github.task/get-github-workitems-clear-cache!)
(github.common/get-github-workitems-inner-clear-cache!)

;; This time GitHub APIs will be called again. Pay attention to the API rate limit!
(tracker.proto/get-tasks pt-github-tracker)

This behavior may change in the future: these functions may be integrated into the corresponding protocols or they will become part of the context macro.

To change the state or some attributes of the the task (and implicitly clear cache) you may do the following (you should be authenticated beforehand, see next section):

(def some-task (first (tracker.proto/get-tasks pt-github-tracker)))

(tracker.proto/upsert! (assoc some-task
                              :task-title "New title"
                              :task-tags ["feature"]
                              :task-assignee "your_login_here"
                              :task-state "close"))

The same tracker.proto/upsert! function may also be used to create new task in case :task-id field was not specified. New task record may be created by doing this:

(def new-task (tracker.core/task {:tracker pt-github-tracker
                                  :task-title "Brand new shiny issue"
                                  :task-description "Very long description goes here."}))

(tracker.proto/upsert! new-task)