Toggl Connector

reshuffle-toggl-connector

Code | npm | Code sample

npm install reshuffle-toggl-connector

This connector uses Official Node Toggl Client package.

Reshuffle Toggl Connector

ES6 import: import { TogglConnector } from 'reshuffle-toggl-connector'

This is a Reshuffle connector that provides an Interface to the Toggl Client.

You need to get your Toggl API Token from your account. See more details here

The following example creates an API endpoint to list all entries in Toggl between from/to dates:

const { HttpConnector, Reshuffle } = require('reshuffle')
const { TogglConnector } = require('reshuffle-toggle-connectors')

const app = new Reshuffle()
const togglConnector = new TogglConnector(app, { token: 'YOUR_TOGGL_TOKEN' })
const httpConnector = new HttpConnector(app)

httpConnector.on({ method: 'GET', path: '/list' }, async (event) => {
  const keys = await togglConnector.getTimeEntries('2020-11-01T09:00:00.000Z', '2020-11-05T17:00:00.000Z')
  event.res.json(keys)
})

app.start(8000)

Table of Contents

Configuration Configuration options

DataTypes Data Types

Connector events:

TimeEntryAdded TimeTracker Added

TimeEntryModified TimeTracker Modified

TimeEntryRemoved TimeTracker Removed

Connector actions:

getTimeEntries Get TimeEntries objects

getCurrentTimeEntry Get current running TimeEntries

getTimeEntryData Get TimeEntry Data

createTimeEntry Create TimeEntry

startTimeEntry Start TimeEntry

stopTimeEntry Stop TimeEntry

updateTimeEntry Update TimeEntry

updateTimeEntriesTags Update TimeEntries Tags

deleteTimeEntry Delete TimeEntry

getUserData Get UserData

updateUserData Update UserData

resetApiToken Reset Api Token

changeUserPassword Change User Password

createClient Create Client

getClients Get Clients

getClientData Get Client's Data

updateClient Update Client

deleteClient Delete Client

SDK:

sdk Get direct SDK access

Configuration options

const app = new Reshuffle()
const togglConnector = new TogglConnector(app, {
  token: string
})

DataTypes

TimeEntry:

{
  id: number,
  wid: null | number, // Workspace ID required if pid or tid not supplied
  pid: null | number, // Project ID
  pid: null | number, // Task ID
  billable: boolean, // Default false, available for pro workspaces
  start: string, // ISO 8601 date and time e.g. '2021-01-21T09:00:00Z'
  stop: string, // ISO 8601 date and time
  duration: number,
  description: string,
  tags: Array<string>,
  at: string
}

More details about TimeEntry available here

UserData:

{
  id: number,
  email: string,
  password: string,
  timezone: string,
  fullname: string,
  send_product_emails: boolean
  send_weekly_report: boolean
  send_timer_notifications: boolean
  store_start_and_stop_time: boolean
  beginning_of_week: number // in the range of 0-6
  timeofday_format: string, // Two formats are supported:
                            // "H:mm" for 24-hour format
                            // "h:mm A" for 12-hour format (AM/PM)
  date_format: string // possible values: "YYYY-MM-DD", "DD.MM.YYYY", "DD-MM-YYYY", "MM/DD/YYYY", "DD/MM/YYYY", "MM-DD-YYYY"
}

More details about UserData available here

ClientData:

{
  id: number,
  name: string,
  wid: null | number,
  notes: string,
  at: string
}

More details about ClientData available here

ProjectData:

{
  id: number,
  name: string,
  wid: null | number,
  cid: null | number,
  active: boolean,
  is_private: boolean,
  template: boolean,
  template_id: number,
  billable: boolean,
  auto_estimates: boolean,
  estimated_hours: number,
  at: string,
  color: string,
  rate: number, 
  created_at: string
}

More details about ProjectData available here

Connector events

All the events are triggered based on changes that occurred only in TimeEntries that started during the last 9 days.

TimeEntry Added event

Event parameters:

type: 'TimeEntryAdded' - Event type for added TimeEntry

Example:

connector.on({ type: 'TimeEntryAdded' }, async (event, app) => {
  console.log('TimeEntry Added:')
  console.log('  Id:', event.id)
  console.log('  Start:', event.start)
  console.log('  Stop:', event.stop)
  console.log('  Description:', event.description)
})

This event is triggered once whenever a new TimeEntry is added to the Toggl board.

The timeEntry argument has the following format

TimeEntry Modified event

Event parameters:

type: 'TimeEntryModified' - Event type for modified TimeEntry

Example:

connector.on({ type: 'TimeEntryModified' }, async (event, app) => {
  console.log('TimeEntry Modified:')
  console.log('  Id:', event.id)
  console.log('  Start:', event.start)
  console.log('  Stop:', event.stop)
  console.log('  Description:', event.description)
})

This event is triggered once whenever the content of a TimeEntry in the Toggl board is modified.

The timeEntry argument has the following format

TimeEntry Removed event

Event parameters:

type: 'TimeEntryRemoved' - Event type for removed TimeEntry

Example:

connector.on({ type: 'TimeEntryRemoved' }, async (event, app) => {
  console.log('TimeEntry Removed:')
  console.log('  Id:', event.id)
  console.log('  Start:', event.start)
  console.log('  Stop:', event.stop)
  console.log('  Description:', event.description)
})

This event is triggered once whenever a TimeEntry is removed from the Toggl board.

The timeEntry argument has the following format

Connector actions

Get TimeEntries action

Definition:

( startDate?: string | number | Date | Moment, 
  endDate?: string | number | Date | Moment
) => object[]

Usage:

const timeEntries = await togglConnector.getTimeEntries('2021-01-01T09:00:00.000Z', '2021-01-05T17:00:00.000Z')

Get a list of TimeEntries in Toggl board. If start_date and end_date are not specified, time entries started during the last 9 days are returned. The limit of returned time entries is 1000.

Get current running TimeEntries action

Definition:

() => object

Usage:

const timeEntry = await togglConnector.getCurrentTimeEntry()

Get the current running TimeEntry.

Get TimeEntry Data action

Definition:

(teId: number | string) => object

Usage:

const timeEntry = await togglConnector.getTimeEntryData(1783760282)

Get a TimeEntry data by ID.

Create TimeEntry action

Definition:

(timeEntry: TimeEntry) => object

Usage:

const timeEntry = await togglConnector.createTimeEntry({
    start:'2020-11-20T09:00:00.000Z',
    duration : 360,
    description : 'Design meeting',
    tags : ["Design", "Meetings"]})

Create a new TimeEntry.

Start TimeEntry action

Definition:

(timeEntry: TimeEntry) => object

Usage:

const timeEntry = await togglConnector.startTimeEntry({
    start:'2020-11-20T09:00:00.000Z',
    stop : '2020-11-20T11:00:00.000Z',
    description : 'Design meeting',
    tags : ["Design", "Meetings"]})

Start a new TimeEntry.

Stop TimeEntry action

Definition:

(teId: number | string) => object

Usage:

const timeEntry = await togglConnector.stopTimeEntry(1778035860)

Stop running TimeEntry.

Update TimeEntry action

Definition:

(teId: number | string, timeEntry: TimeEntry) => object

Usage:

const timeEntry = await togglConnector.updateTimeEntry(1778035860, {
    start:'2020-11-21T09:00:00.000Z',
    stop : '2020-11-21T11:00:00.000Z',
    description : 'Postponed Design meeting',
    tags : ["Design", "Meetings"]})

Update TimeEntry data.

Update TimeEntries Tags action

Definition:

(teIds: number[] | string[], tags: string[], action: string) => object

Usage:

const timeEntry = await togglConnector.updateTimeEntriesTags([1778035860, 1778035860],['tag-1','tag-2'], 'add')

Assign and remove tags from timeEntries. action: possible values: add, remove

Delete TimeEntry action

Definition:

(teId: number | string) => object

Usage:

const timeEntry = await togglConnector.deleteTimeEntry(1778035860)

Delete timeEntry.

Get UserData action

Definition:

() => object

Usage:

const userData = await togglConnector.getUserData()

Get current UserData.

Update UserData action

Definition:

(userData: UserData) => object

Usage:

const userData = await togglConnector.updateUserData({
    id: 4898995,
    email: 'user@gmail.com',
    send_product_emails: true,
    send_weekly_report: true,
    send_timer_notifications: true
  })

Update current UserData.

Reset Api Token action

Definition:

() => string

Usage:

const token = await togglConnector.resetApiToken()

Reset current UserData API Token.

Change User Password action

Definition:

() => object

Usage:

const userData = await togglConnector.changeUserPassword(currentPassword: string, password: string)

Create Client action

Definition:

(clientData: ClientData) => object

Usage:

const clientData = await togglConnector.createClient({
    name: 'Builders LTD',
    notes: 'Important client',
    wid: 4869303
  })

Create new Client.

Get Clients action

Definition:

() => object

Usage:

const clientsData = await togglConnector.getClients()

Get all Clients data.

Get Client Data action

Definition:

(clientId: number | string) => object

Usage:

const clientData = await togglConnector.getClientData(5869111)

Get Client data by ID.

Update Client Data action

Definition:

(clientId: number | string, clientData: ClientData) => object

Usage:

const clientData = await togglConnector.updateClient(5869111, {
    name: 'Builders One LTD',
    notes: 'Very important client',
    wid: 4869303
  })

Update Client data.

Delete Client Data action

Definition:

(clientId: number) => object

Usage:

const clientData = await togglConnector.deleteClient(5869111)

Delete Client.

SDK

sdk

Definition:

(options ?: object) => object

Usage:

const toggl = await togglConnector.sdk()

Get the underlying SDK object. You can specify additional options to override or add to the required fields in the connector's configuration.