class TogglV8::API

Clients

↑ top

Public Instance Methods

create_client(params) click to toggle source
# File lib/togglv8/clients.rb, line 15
def create_client(params)
  requireParams(params, ['name', 'wid'])
  post "clients", { 'client' => params }
end
delete_client(client_id) click to toggle source
# File lib/togglv8/clients.rb, line 28
def delete_client(client_id)
  delete "clients/#{client_id}"
end
get_client(client_id) click to toggle source
# File lib/togglv8/clients.rb, line 20
def get_client(client_id)
  get "clients/#{client_id}"
end
get_client_projects(client_id, params={}) click to toggle source
# File lib/togglv8/clients.rb, line 32
def get_client_projects(client_id, params={})
  active = params.has_key?('active') ? "?active=#{params['active']}" : ""
  get "clients/#{client_id}/projects#{active}"
end
update_client(client_id, params) click to toggle source
# File lib/togglv8/clients.rb, line 24
def update_client(client_id, params)
  put "clients/#{client_id}", { 'client' => params }
end

Dashboard

↑ top

Public Instance Methods

dashboard(workspace_id) click to toggle source
# File lib/togglv8/dashboard.rb, line 10
def dashboard(workspace_id)
  get "dashboard/#{workspace_id}"
end

Project Users

↑ top

Public Instance Methods

create_project_user(params) click to toggle source
# File lib/togglv8/project_users.rb, line 17
def create_project_user(params)
  requireParams(params, ['pid', 'uid'])
  params[:fields] = "fullname"  # for simplicity, always request fullname field
  post "project_users", { 'project_user' => params }
end
delete_project_user(project_user_id) click to toggle source
# File lib/togglv8/project_users.rb, line 28
def delete_project_user(project_user_id)
  delete "project_users/#{project_user_id}"
end
update_project_user(project_user_id, params) click to toggle source
# File lib/togglv8/project_users.rb, line 23
def update_project_user(project_user_id, params)
  params[:fields] = "fullname"  # for simplicity, always request fullname field
  put "project_users/#{project_user_id}", { 'project_user' => params }
end

Projects

↑ top

Public Instance Methods

create_project(params) click to toggle source

Public: Create a new project

params - The Hash used to create the project (default: {})

:name            - The name of the project (string, required, unique for client and workspace)
:wid             - workspace ID, where the project will be saved (integer, required)
:cid             - client ID (integer, not required)
:active          - whether the project is archived or not (boolean, by default true)
:is_private      - whether project is accessible for only project users or for all workspace users (boolean, default true)
:template        - whether the project can be used as a template (boolean, not required)
:template_id     - id of the template project used on current project's creation
:billable        - whether the project is billable or not (boolean, default true, available only for pro workspaces)
:auto_estimates  - whether the estimated hours is calculated based on task estimations or is fixed manually (boolean, default false, not required, premium functionality)
:estimated_hours - if auto_estimates is true then the sum of task estimations is returned, otherwise user inserted hours (integer, not required, premium functionality)
:at              - timestamp that is sent in the response for PUT, indicates the time task was last updated
:color           - id of the color selected for the project
:rate            - hourly rate of the project (float, not required, premium functionality)
:created_at      - timestamp indicating when the project was created (UTC time), read-only

Examples

toggl.create_project({ :name => 'My project', :wid => 1060392 })
=> {"id"=>10918774,
 "wid"=>1060392,
 "name"=>"project5",
 "billable"=>false,
 "is_private"=>true,
 "active"=>true,
 "template"=>false,
 "at"=>"2015-08-18T10:03:51+00:00",
 "color"=>"5",
 "auto_estimates"=>false}

Returns a Hash representing the newly created Project.

See Toggl Create Project

# File lib/togglv8/projects.rb, line 74
def create_project(params)
  requireParams(params, ['name', 'wid'])
  post "projects", { 'project' => params }
end
delete_project(project_id) click to toggle source

[Delete a project](github.com/toggl/toggl_api_docs/blob/master/chapters/projects.md#delete-a-project)

# File lib/togglv8/projects.rb, line 90
def delete_project(project_id)
  delete "projects/#{project_id}"
end
delete_projects(project_ids) click to toggle source

[Delete multiple projects](github.com/toggl/toggl_api_docs/blob/master/chapters/projects.md#delete-multiple-projects)

# File lib/togglv8/projects.rb, line 107
def delete_projects(project_ids)
  return if project_ids.nil?
  delete "projects/#{project_ids.join(',')}"
end
get_project(project_id) click to toggle source

[Get project data](github.com/toggl/toggl_api_docs/blob/master/chapters/projects.md#get-project-data)

# File lib/togglv8/projects.rb, line 80
def get_project(project_id)
  get "projects/#{project_id}"
end
get_project_tasks(project_id) click to toggle source

[Get project tasks](github.com/toggl/toggl_api_docs/blob/master/chapters/projects.md#get-project-tasks)

# File lib/togglv8/projects.rb, line 100
def get_project_tasks(project_id)
  get "projects/#{project_id}/tasks"
end
get_project_users(project_id) click to toggle source

[Get project users](github.com/toggl/toggl_api_docs/blob/master/chapters/projects.md#get-project-users)

# File lib/togglv8/projects.rb, line 95
def get_project_users(project_id)
  get "projects/#{project_id}/project_users"
end
update_project(project_id, params) click to toggle source

[Update project data](github.com/toggl/toggl_api_docs/blob/master/chapters/projects.md#update-project-data)

# File lib/togglv8/projects.rb, line 85
def update_project(project_id, params)
  put "projects/#{project_id}", { 'project' => params }
end

Tags

↑ top

Public Instance Methods

create_tag(params) click to toggle source
# File lib/togglv8/tags.rb, line 11
def create_tag(params)
  requireParams(params, ['name', 'wid'])
  post "tags", { 'tag' => params }
end
delete_tag(tag_id) click to toggle source
# File lib/togglv8/tags.rb, line 21
def delete_tag(tag_id)
  delete "tags/#{tag_id}"
end
update_tag(tag_id, params) click to toggle source

ex: update_tag(12345, { :name => “same tame game” })

# File lib/togglv8/tags.rb, line 17
def update_tag(tag_id, params)
  put "tags/#{tag_id}", { 'tag' => params }
end

Tasks

↑ top

Public Instance Methods

create_task(params) click to toggle source
# File lib/togglv8/tasks.rb, line 22
def create_task(params)
  requireParams(params, ['name', 'pid'])
  post "tasks", { 'task' => params }
end
delete_task(task_id) click to toggle source
# File lib/togglv8/tasks.rb, line 36
def delete_task(task_id)
  delete "tasks/#{task_id}"
end
delete_tasks(task_ids) click to toggle source
# File lib/togglv8/tasks.rb, line 49
def delete_tasks(task_ids)
  return if task_ids.nil?
  delete "tasks/#{task_ids.join(',')}"
end
get_task(task_id) click to toggle source
# File lib/togglv8/tasks.rb, line 27
def get_task(task_id)
  get "tasks/#{task_id}"
end
update_task(task_id, params) click to toggle source

ex: update_task(1894675, { :active => true, :estimated_seconds => 4500, :fields => “done_seconds,uname”})

# File lib/togglv8/tasks.rb, line 32
def update_task(task_id, params)
  put "tasks/#{task_id}", { 'task' => params }
end
update_tasks(task_ids, params) click to toggle source

———— # Mass Actions # ———— #

# File lib/togglv8/tasks.rb, line 44
def update_tasks(task_ids, params)
  return if task_ids.nil?
  put "tasks/#{task_ids.join(',')}", { 'task' => params }
end

Time Entries

↑ top

Constants

TOGGL_API_V8_URL

Attributes

conn[R]

Public Class Methods

new(username=nil, password=API_TOKEN, opts={}) click to toggle source
# File lib/togglv8/togglv8.rb, line 22
def initialize(username=nil, password=API_TOKEN, opts={})
  debug(false)
  if username.nil? && password == API_TOKEN
    toggl_api_file = File.join(Dir.home, TOGGL_FILE)
    # logger.debug("toggl_api_file = #{toggl_api_file}")
    if File.exist?(toggl_api_file) then
      username = IO.read(toggl_api_file).strip
    else
      raise "Expecting one of:\n" +
        " 1) api_token in file #{toggl_api_file}, or\n" +
        " 2) parameter: (api_token), or\n" +
        " 3) parameters: (username, password).\n" +
        "\n\tSee https://github.com/kanet77/togglv8#togglv8api" +
        "\n\tand https://github.com/toggl/toggl_api_docs/blob/master/chapters/authentication.md"
    end
  end

  @conn = TogglV8::Connection.open(username, password,
            TOGGL_API_V8_URL, opts)
end

Public Instance Methods

create_time_entry(params) click to toggle source
# File lib/togglv8/time_entries.rb, line 27
def create_time_entry(params)
  params['created_with'] = TogglV8::NAME unless params.has_key?('created_with')
  requireParams(params, ['start', 'duration', 'created_with'])
  if !params.has_key?('wid') and !params.has_key?('pid') and !params.has_key?('tid') then
    raise ArgumentError, "one of params['wid'], params['pid'], params['tid'] is required"
  end
  post "time_entries", { 'time_entry' => params }
end
delete_time_entry(time_entry_id) click to toggle source
# File lib/togglv8/time_entries.rb, line 60
def delete_time_entry(time_entry_id)
  delete "time_entries/#{time_entry_id}"
end
get_current_time_entry() click to toggle source
# File lib/togglv8/time_entries.rb, line 52
def get_current_time_entry
  get "time_entries/current"
end
get_time_entries(dates = {}) click to toggle source
# File lib/togglv8/time_entries.rb, line 76
def get_time_entries(dates = {})
  start_date = dates[:start_date]
  end_date = dates[:end_date]
  params = []
  params.push("start_date=#{iso8601(start_date)}") unless start_date.nil?
  params.push("end_date=#{iso8601(end_date)}") unless end_date.nil?
  get "time_entries%s" % [params.empty? ? "" : "?#{params.join('&')}"]
end
get_time_entry(time_entry_id) click to toggle source
# File lib/togglv8/time_entries.rb, line 48
def get_time_entry(time_entry_id)
  get "time_entries/#{time_entry_id}"
end
iso8601(timestamp) click to toggle source
# File lib/togglv8/time_entries.rb, line 64
def iso8601(timestamp)
  return nil if timestamp.nil?
  if timestamp.is_a?(DateTime) or timestamp.is_a?(Date)
    formatted_ts = timestamp.iso8601
  elsif timestamp.is_a?(String)
    formatted_ts = DateTime.parse(timestamp).iso8601
  else
    raise ArgumentError, "Can't convert #{timestamp.class} to ISO-8601 Date/Time"
  end
  return formatted_ts.sub('+00:00', 'Z')
end
start_time_entry(params) click to toggle source
# File lib/togglv8/time_entries.rb, line 36
def start_time_entry(params)
  params['created_with'] = TogglV8::NAME unless params.has_key?('created_with')
  if !params.has_key?('wid') and !params.has_key?('pid') and !params.has_key?('tid') then
    raise ArgumentError, "one of params['wid'], params['pid'], params['tid'] is required"
  end
  post "time_entries/start", { 'time_entry' => params }
end
stop_time_entry(time_entry_id) click to toggle source
# File lib/togglv8/time_entries.rb, line 44
def stop_time_entry(time_entry_id)
  put "time_entries/#{time_entry_id}/stop", {}
end
update_time_entries_tags(time_entry_ids, params) click to toggle source

Example params: {'tags' =>['billed','productive'], 'tag_action' => 'add'} tag_action can be 'add' or 'remove'

# File lib/togglv8/time_entries.rb, line 87
def update_time_entries_tags(time_entry_ids, params)
  return if time_entry_ids.nil?
  requireParams(params, ['tags', 'tag_action'])
  put "time_entries/#{time_entry_ids.join(',')}", { 'time_entry' => params }
end
update_time_entries_tags_fixed(time_entry_ids, params) click to toggle source

TEMPORARY FIXED version of API issue see github.com/toggl/toggl_api_docs/issues/20 for more info

# File lib/togglv8/time_entries.rb, line 95
def update_time_entries_tags_fixed(time_entry_ids, params)
  time_entries = update_time_entries_tags(time_entry_ids, params)
  return time_entries if params['tag_action'] == 'add'

  time_entries_for_removing_all_tags_ids = []
  [].push(time_entries).flatten.map! do |time_entry|
    unless time_entry['tags'].nil?
      time_entry['tags'] = time_entry['tags'] - params['tags']
      time_entries_for_removing_all_tags_ids << time_entry['id'] if time_entry['tags'].empty?
    end
    time_entry
  end

  remove_params = {'tags' => []}
  put "time_entries/#{time_entries_for_removing_all_tags_ids.join(',')}", { 'time_entry' => remove_params } unless time_entries_for_removing_all_tags_ids.empty?

  time_entries
end
update_time_entry(time_entry_id, params) click to toggle source
# File lib/togglv8/time_entries.rb, line 56
def update_time_entry(time_entry_id, params)
  put "time_entries/#{time_entry_id}", { 'time_entry' => params }
end

Users

↑ top

Public Instance Methods

create_user(params) click to toggle source
# File lib/togglv8/users.rb, line 68
def create_user(params)
  params['created_with'] = TogglV8::NAME unless params.has_key?('created_with')
  requireParams(params, ['email', 'password', 'timezone', 'created_with'])
  post "signups", { 'user' => params }
end
me(all=nil) click to toggle source
# File lib/togglv8/users.rb, line 23
def me(all=nil)
  # NOTE: response['since'] is discarded because it is outside response['data']
  #       (See TogglV8::API#get in lib/togglv8.rb)
  get "me%s" % [all.nil? ? "" : "?with_related_data=#{all}"]
end
my_clients(user=nil) click to toggle source
# File lib/togglv8/users.rb, line 29
def my_clients(user=nil)
  user = me(all=true) if user.nil?
  user['clients'] || {}
end
my_deleted_projects(user=nil) click to toggle source
# File lib/togglv8/users.rb, line 41
def my_deleted_projects(user=nil)
  user = me(all=true) if user.nil?
  return {} unless user['projects']
  projects = user['projects']
  projects.keep_if { |p| p['server_deleted_at'] }
end
my_projects(user=nil) click to toggle source
# File lib/togglv8/users.rb, line 34
def my_projects(user=nil)
  user = me(all=true) if user.nil?
  return {} unless user['projects']
  projects = user['projects']
  projects.delete_if { |p| p['server_deleted_at'] }
end
my_tags(user=nil) click to toggle source
# File lib/togglv8/users.rb, line 48
def my_tags(user=nil)
  user = me(all=true) if user.nil?
  user['tags'] || {}
end
my_tasks(user=nil) click to toggle source
# File lib/togglv8/users.rb, line 53
def my_tasks(user=nil)
  user = me(all=true) if user.nil?
  user['tasks'] || {}
end
my_time_entries(user=nil) click to toggle source
# File lib/togglv8/users.rb, line 58
def my_time_entries(user=nil)
  user = me(all=true) if user.nil?
  user['time_entries'] || {}
end
my_workspaces(user=nil) click to toggle source
# File lib/togglv8/users.rb, line 63
def my_workspaces(user=nil)
  user = me(all=true) if user.nil?
  user['workspaces'] || {}
end

Workspaces

↑ top

Public Instance Methods

clients(workspace_id=nil) click to toggle source
# File lib/togglv8/workspaces.rb, line 17
def clients(workspace_id=nil)
  if workspace_id.nil?
    get "clients"
  else
    get "workspaces/#{workspace_id}/clients"
  end
end
leave_workspace(workspace_id) click to toggle source
# File lib/togglv8/workspaces.rb, line 43
def leave_workspace(workspace_id)
  delete "workspaces/#{workspace_id}/leave"
end
projects(workspace_id, params={}) click to toggle source
# File lib/togglv8/workspaces.rb, line 25
def projects(workspace_id, params={})
  active = params.has_key?(:active) ? "?active=#{params[:active]}" : ""
  get "workspaces/#{workspace_id}/projects#{active}"
end
tags(workspace_id) click to toggle source
# File lib/togglv8/workspaces.rb, line 39
def tags(workspace_id)
  get "workspaces/#{workspace_id}/tags"
end
tasks(workspace_id, params={}) click to toggle source
# File lib/togglv8/workspaces.rb, line 34
def tasks(workspace_id, params={})
  active = params.has_key?(:active) ? "?active=#{params[:active]}" : ""
  get "workspaces/#{workspace_id}/tasks#{active}"
end
users(workspace_id) click to toggle source
# File lib/togglv8/workspaces.rb, line 30
def users(workspace_id)
  get "workspaces/#{workspace_id}/users"
end
workspaces() click to toggle source
# File lib/togglv8/workspaces.rb, line 13
def workspaces
  get "workspaces"
end