Skip to main content
Language Selector

  1. Other Languages

    (machine translation)

Planview Customer Success Center

Missing Timesheet Days API

  1. Last updated
  2. Save as PDF

Overview

The Missing Timesheet Days API is a dedicated API to retrieve missing timesheets by day for developers implementing their own time reporting compliance solutions.

Missing timesheets are considered Timesheets in Un Submitted State, or not reported at all.

Background

AdaptiveWork includes the following features:

  • Timesheets Expected From for Users (field)
  • Timesheets Complete Until for Users (field)
  • Missing Timesheet Days (API)

TimesheetsExpectedFrom (Date, User object)

This editable Date field specifies the date on which the user is expected to start logging entries in the timesheet. There is no default value.

About the TimesheetsExpectedFrom field:

  • The default value is null
  • When there is a date in the TimesheetsExpectedFrom field (i.e. when this is not null), the Timesheets Complete Until field is calculated automatically.
  • When this field is null or reset to null, the Timesheets Complete Until field is also reset to null.
  • Can have Business Rules
  • The minimal value is one year back from today

Timesheets Complete Until (Date, User object)

Once Timesheets Expected From has been set for a user, the Timesheets Complete Until field will start calculating.

A complete timesheet day is one where Submitted + Approved Timesheets = > Calendar Working Hours (equals or greater than).

When users have logged Calendar Exceptions for time off, their Working Hours are decreased. In the case of taking full days off work, no timesheets are expected for those days.

Timesheets Complete Until is calculated upon:

  • Submission or approval of timesheets
  • Re-opening of timesheets (Approved → Unsubmitted)
  • Changes to User Calendar Working Days / Hours
  • Insertion or removal of Calendar Exceptions
  • TimesheetsExpectedFrom field is updated

Missing Timesheet Days API

The API retrieves missing timesheets by day.

Parameters:

  • user
  • StartDate (inclusive)
  • EndDate (exclusive)
  • tolerance (in minutes)

Returns:

For each day where timesheets < working hours

  • User
  • Date
  • workingHours
  • reportedHours
  • missingHours

Sample Query:

GET /data/missingTimesheets?user=/User/65yb7nbdtin2jh8rk1cnm76d82043&startDate=2020-01-01&endDate=2020-01-06&tolerance=10

Returns 

{
  "user": "/User/65yb7nbdtin2jh8rk1cnm76d82043",
  "missingTimesheets": [
    {
      "date": "2020-01-01T00:00:00.0000000Z",
      "workingHours": 8.0,
      "reportedHours": 0.0,
      "missingHours": 8.0
    },
    {
      "date": "2020-01-02T00:00:00.0000000Z",
      "workingHours": 8.0,
      "reportedHours": 3.0,
      "missingHours": 5.0
    },
    {
      "date": "2020-01-03T00:00:00.0000000Z",
      "workingHours": 7.0,
      "reportedHours": 2.0,
      "missingHours": 5.0
    }
  ]
}

Updating Timesheet Data via API

Timesheets have a set lifecycle of Unsubmitted → Submitted → Approved

The Timesheet state can be changed by a workflow using the Change State action, and by API using the Lifecycle operation method. https://api.clarizen.com/V2.0/services/data/Lifecycle

When timesheets are reopened, they will revert to the Unsubmitted state.

Editable standard timesheet fields include:

  • ApprovalDate
  • AssignedApprover
  • Charged
  • Comment
  • DisableReportingTimeLimit
  • Duration
  • ExternalID
  • LastSubmittedDate
  • Overtime
  • RegularHours
  • RejectedBy
  • RejectionDate
  • RejectionNote
  • Comment

Approved Timesheet Limitations

Standard fields cannot be edited in Approved timesheets. Custom fields can be edited:

mceclip0.png

When updating Approved timesheets via API, take care not to include standard fields in the update messages, even if no changes are being made to those fields, as this will cause the update to fail.