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 |