timewax-v2

Timewax API

Dependencies

Node >= 0.12

API

timewax.init(options)

Initialize the options first by supplying an options hash with the following:

options	Type	Example
endpoint	String	'https://api.timewax.com'
client	String
username	String
password	String

Usage

    var timewax = require('timewax');

    // obj to hold params for API requests
    var params = {};

    timewax.init({
      endpoint: 'https://api.timewax.com',
      client: 'MyClientName',
      username: 'U123',
      password: 'itsasecret'
    });

timewax.request(service, payload, xpathFilter, callback)

This is the generic POST request to interact with the API and can be used when a convenience method is not yet available.

arguments	Type	Example
service	String	'/resource/list/''
params	Hash	{ token: 'ASDFASFSADFASDFASF' }
		Must include a token property
xpathFilter	String	'//resources'
callback	function(err, result)	NodeJS style callback as last parameter

Convenience Methods

timewax.getAuthenticationToken(callback)

Returns valid API token which lasts for 60 minutes and carries security of the user who requested the token.

Usage

    // get a reusable API token
    timewax.getAuthenticationToken(function(err, token) {

      // cache the token on the params obj
      params.token = token

      });

timewax.resourceList(params, callback)

Returns an array of resources for given Client group in original token request.

Field	Description
resourceID	The unique ID of the resource.
code	Resource code.
fullName	Full name
lastName	Last name
firstNames	First names
infix	Infix
color	Resource color (hexadecimal value)

Usage

    // get full list of resources as a array
    timewax.resourceList(params, function(err, resources) {

      // do something with my resources
    });

timewax.getResource(params, callback)

Returns a full resource object. Params are:

Params	Description
resource	Name fullName or email

timewax.projectList(params, callback)

Returns an array of project objects like:

Field	Description
code	Project code
name	Project name
shortName	Project short name

To get the full Project Object like below, do a subsequent call to timewax.getProject:

Field	Description
valid	Indication that service was not executed successfully
code	Project code
name	Project name
shortName	Project short name
useInvoicing	yes or no. Is it possible to invoice from this project?
chargeable	yes or no. Is this project chargeable?
approveTime	yes or no. Do submitted hours need to be approved?
approveExpenses	yes or no. Do submitted expenses need to be approved?
approveCalenderEntries	yes or no. Can calendar entries beapproved?
orgUnitManagerIsApprover	yes or no.
blockEntries	yes or no. Blocks making bookings on the proejct
isTemplate	yes or no. Can this project be used as a template for new projects?
isActive	yes or no. Is the project active?
startDate	yyyymmdd. Start date of the project
endDate	yyyymmdd. End dat of the project
notes	Remarks
company	The company/customer name for this project
organisationalUnit	Name. The organizational unit where the project belongs
projectManager	Name. Project manager of the project (Resource)
currency	Project currency
parentProject	Name. The parent project (Project)
status	Project status (Attributes)
color	Project color (hexadecimal value)
externalLinkFiles	URL to an online file location
status	status (Attribute)
invoice/blockInvoice	yes or no. Block invoices for this project?
invoice/backupResponsible	Name. Who is also allowed to start the invoice run
invoice/debtor/name, address, postcode, city, country, debtorNumber and email	Adres of the debtor (company, debtor role)
invoice/invoiceLayout	Name. Invoice lay-out for the invoice
invoice/invoiceLayoutCreditnote	Name. Invoice lay-out for the credit note
invoice/invoicetypeHours	Type hours (Attributes)
invoice/invoicetypeKM	yes or no. Do kilometers have to be invoiced?
invoice/invoicetypeKMRate	Rate per kilometer
invoice/invoicetypeExpenses	yes or no. Do expenses have to be invoiced?
invoice/VATSalesHours	Name. What VAT percentage to apply for hours.
invoice/VATSalesExpenses	Name. What VAT percentage to apply for expenses.
invoice/reference1	Invoice reference 1
invoice/reference2	Invoice reference 2
invoice/reference3	Invoice reference 3
invoice/reference4	Invoice reference 4
invoice/reference5	Invoice reference 5
categories/alignment	Name. Attribute
categories/risk	Name. Attribute
categories/location	Name. Attribute
categories/complexity	Name. Attribute
categories/knowledgeAvailible	Name. Attribute
categories/budget	Name. Attribute
categories/businessType	Name. Attribute
categories/duration	Name. Attribute
categories/financialRisk	Name. Attribute
categories/decisionLevel	Name. Attribute
categories/benefits	Name. Attribute
categories/politicalSensitivity	Name. Attribute
categories/productCategory	Name. Attribute
categories/innovation	Name. Attribute
categories/portfolioAdvise	Name. Attribute
categories/priority	Name. Attribute

timewax.projectListChanged

Returns list of projects that were created or modified during a time period; params is a hash with:

Param	Type	Example
dateTo	String	'20160101' - yyymmdd
dateFrom	String	'20170101' - yyyymmdd

Returns an array of project objects like:

Field	Description
code	Project code
name	Project name
shortName	Project short name

To get the full Project Object, do a subsequent call to timewax.getProject:

Usage

    var params = {
      dateFrom: '20160101',
      dateTo: '20160201'
    };
    // get full list of projects
    timewax.projectListChanged(params, function(err, projects){

      // do something with my projects
    });

timewax.getProjectBudget(params, callback)

Returns an array of breakdowns within a project with their budgets; params above is a hash of:

Param	Type	Example
project	String	'Internal' - can be code or name

Usage

    // add any other filters or parameters the service requires

    params.project = "myProjectCode" // can be TimeWax project name or code

    timewax.getProjectBudget(params, function(err, breakdowns){

      // do something with my budgets
    });

timewax.breakdownList(params, callback)

Returns an array of breakdowns within a project; params above is a hash of:

Param	Type	Example
project	String	'Internal' - can be code or name

Usage

    // add any other filters or parameters the service requires

    params.project = "myProjectCode" // can be TimeWax project name or code

    timewax.breakdownList(params, function(err, breakdowns){

      // do something with my breakdowns
    });

timewax.entriesList(params, callback)

Returns full list of time entries for a resource; params is a hash with:

Param	Type	Example
resource	String	'089' - resource API ID
dateTo	String	'20160101' - yyymmdd
dateFrom	String	'20170101' - yyyymmdd
project	String	'089' - name or code
onlyApprovedEntires	Bool	TRUE

Entry Objects returned:

Field	Description
id	The unique id of the time line
date	The date of the booking.
resource	Resource name
resourceCode	Resource code
project	The project name of the booking.
projectCode	The project code of the booking.
breakdown	The breakdown name of the booking.
breakdownCode	The breakdown code of the booking.
breakdownParent	The name of the parent breakdown.
breakdownParentCode	The code of the parent breakdown.
status	The status of the booking.
dateUpdateStatus	The last update of the line (approved or rejected)
type	value from the field type.
reference	Value in the reference field.
timeFrom	Starting time of the booking. Format: hh:mm.
timeTo	End time for the booking. Format: hh:mm.
hours	Number of hours.
description	Description.
KM	Number of kilometers.
descriptionKM	Description of the kilometers.
rejectionRemarks	Remarks in case the booking has been rejected in approval
invoiceStatus	Has the line been invoiced?
addDate	The add date of the line
modifyDate	The modification date of the line

Usage

    params.dateFrom = "20160101" // Format: yyyymmdd
    params.dateTo = "20160601"  // Format: yyyymmdd
    params.resource = "089"     // API ID from TimeWax for resource
    params.project = "Build Phase One"      // Code or name
    params.onlyApprovedEntires = true // a boolean

    timewax.entriesList(params, function(err, entries){

      // do something with my time entries
    });

timewax.addTimeEntry(params, callback)

Returns a success or failure; params is a hash with:

Param	Type	Example
resource	String	'089' - resource API ID
date	String	'20160101' - yyymmdd
project	String	'CODEORNAME'
breakdown	String	'089' - name or code
hours	String	'7.5'
startTime	String	'09:00' - hh:mm
endTime	String	'10:00' - hh:mm
reference	String	'KJM'
description	String	'Getting Details for Login'
type	String	'PLANNING'

timewax.entriesListChanged(params, callback)

Returns full list of entries added/modified/deleted within a given period; params above is a hash of:

Param	Type	Example
resource(optional)	String	'089' - resource API ID
dateTo	String	'20160101' - yyymmdd
dateFrom	String	'20170101' - yyyymmdd
onlyApprovedEntires (optional)	Bool	TRUE

If the returned Entry Object contains one of the following:

• a addDate: it indicates when it was added
• a modifyDate: it indicates when it was last modified
• a deleteDate: it indicates when it was deleted

timewax.projectPlanningList(params, callback)

Returns project breakdown details into a Gannt chart structured data; params above is a hash of:

Param	Type	Example
project	String	'089' - code or name
version	String	'NEWESTV2' - planning version

This service returns an array of objects like:

Field	Description
project	Name of the project
projectCode	Project code
breakdown	breakdown name
breakdownCode	breakdown code
version	breakdown name
startdate	Start date for this plan line
enddate	End date for this plan line
duration	Duration in days
comments	Additional comment
estimate	Estimate number of days
label	Additional label