I wanted to take a minute to post about an update that we are making to our API in regards to entering and managing time off in Workfront.I wanted to take a minute to post about an update that we are making to our API in regards to entering and managing time off in Workfront. Workfront continues to build out the Operational System of Record (OSR). Part of that means integrations with your other Systems of Record. The HR system of record will likely hold the time off for users. Instead of expecting double entry from users, we should encourage organizations towards integrating that data (either with Fusion or on their own). The API endpoint to support that integration has not traditionally been the easiest to work with. That is changing with our next software patch. With the updated API endpoint for Time Off (/reservedtime), you will be able to enter time off into Workfront as individual reservedtime objects, multiple objects in a single post, or edit existing objects. None of this was possible in the past. It functions much like all of the other objects, such as interacting with tasks and projects. When posting a new reservedtime object, your post can contain a body that looks like this: POST:
https://{domain}.my.workfront.com/attask/api/v11.0/reservedtime BODY: { "startDate": "2019-07-27T00:00:00-0600", "endDate": "2019-07-29T23:59:00-0600", "userID": "5d3604cd00001746e88139892a03fd22", "extRefID": "IDfromHRIS" } The date stamp can include times of day (full day is midnight to 23:59), as well as a timezone offset. I highly recommend that you set the timezone offset to match the timezone for the user who is taking the time off. I also recommend that you set the extRefID to be a matching ID from the corresponding system from where the time off is originated, or if Workfront is the originator, the ID to where we are sending it. You can post multiple reservedtime objects for individual or multiple users like this: POST:
https://{domain}.my.workfront.com/attask/api/v11.0/reservedtime BODY: [ { "startDate": "2019-07-27T00:00:00-0600", "endDate": "2019-07-29T23:59:00-0600", "userID": "5d3604cd00001746e88139892a03fd22", "extRefID": "IDfromHRIS" }, { "startDate": "2019-08-15T00:00:00-0600", "endDate": "2019-08-16T23:59:00-0600", "userID": "5d3604cd00001746e88139892a03fd22", "extRefID": "IDfromHRIS" } ] If you attempt to add time off for a user, and that user already has time off that spans somewhere within the startDate and endDate that you have included, you will receive an overlap error that looks like this: 2019-07-19T22:00:00:000-0600 - 2019-07-28T21:59:00:000-0600 overlaps with existing ReservedTime with ID of 5d38a61c0000520053ac6ab4ca257abb We specifically included the ID of the existing reservedtime object as the last 32 characters of the message so that within your scripting, you can anticipate that error and simply submit a new edit (PUT) for that record with the new dates, if that's what you are needing to do. On that note, you can now edit reservedtime objects using the standard PUT method. It would look something like this: PUT:
https://{domain}.my.workfront.com/attask/api/v11.0/reservedtime BODY: [ { "ID": "5d3604cd00001746e88139892a03fd22", "startDate": "2019-07-27T00:00:00-0600", "endDate": "2019-07-29T23:59:00-0600", "extRefID": "IDfromHRIS" }, { "ID": "5d360222000013654944e3860ae7da5e", "startDate": "2019-08-15T00:00:00-0600", "endDate": "2019-08-16T23:59:00-0600", "extRefID": "IDfromHRIS" } ] The only thing you cannot edit on an existing reservedtime object is the userID. Delete also works as you would expect: DELETE:
https://{domain}.my.workfront.com/attask/api/v11.0/reservedtime/5d3604cd00001746e88139892a03fd22 Finally, you can also search for reservedtime objects just like the rest of our API search capabilities. Example: GET:
https://{domain}.my.workfront.com/attask/api/v11.0/reservedtime/search?startDate=2019-08-15T00:00:00... I look forward to your feedback as you start to use this new API capability and hope to see that entering time off in Workfront is more seamless for you and your users. Josh Hardman Product Manager, Workfront
