Web TimeSheet Application Note

Using the Time Off Balance Web Service

The time off balance web service allows you to extract and use time off balance data from Web TimeSheet without having to directly access your database. You can use this data in external applications, such as exception ticketing systems.

Web services allow you to access XML data using HTTP protocols. That is, you can extract data by appending your Web TimeSheet URL.

Using the Time Off Balance Web Service

1. Log in to Web TimeSheet.

You must be logged in to Web TimeSheet to access the web service.

2. Modify your URL to call a web service method, using the format below:

http://[YourServerName]/timesheet/services/TimeOffBalanceReportService.asmx/[MethodName]?[Parameter1Name=Parameter1Value]&[Parameter2Name=Parameter2Value]

Where:

• Method determines what records the web service returns (akin to a report).

• Parameters limit the data returned (akin to filters in reports).

Note: Information on the available methods, and examples of URL formatting, are provided below.

Note: Method names are case sensitive, parameter names are not.

3. Press Enter. The service will return time off balance data in an XML file.

The names and values of the returned fields match fields found in the Time Off Balance report. However, there are some exceptions, outlined below.

Understanding the Time Off Balance Methods and Parameters

Two methods are available for the Time Off Balance web service:

Method	This method returns…
GetTimeOffBalanceData	A time off balance record for each time off type that the specified user can book or enter time against
GetTimeOffBalanceDataForType	A single time off balance record for the specified time off type

For each method, you define 2 or 3 parameters (depending on the method). All parameters available for a method are required.

Parameter	Description of Parameter
UserLoginName	The login name of the user whose data you want returned.
AsOfDate	The date whose balance you want returned; that is, the balance returned will be the time off balance at that date.
TimeOffTypeName¹	The name of the time off type whose balance you want returned.

1 Available in the GetTimeOffBalanceDataForType only.

Examples of Formatting the URL for a Time Off Balance Web Service Call

Example 1: http://johnsmithxp:81/timesheet/services/TimeOffBalanceReportService.asmx/GetTimeOffBalanceData?userLoginName=admin&asOfDate=March 13, 2009

Example 2:

http://smith:8083/timesheet/services/TimeOffBalanceReportService.asmx/GetTimeOffBalanceDataForType?userLoginName=john&timeoffTypeName=sick&asOfDate=February 13, 2010

Understanding the Data Fields Returned by the Web Service

Most of the fields returned by the Time Off Balance web service match – in both name and data values – fields found in the Time Off Balance report. However, to provide complete time off balance data, the web service also includes balance values that match those displayed in the time off calendar.

To allow for this, the following data relationships are used to display the web service data:

Data Source

Source Field

Web Service Field Name

Time Off Calendar

Remaining Days

Remaining Hours

RemainingDays

RemainingHours

Taken Days

Taken Hours

TakenToResetDays

TakenToResetHours

Time Off Balance Report

Time Off Remaining (Days)

Time Off Remaining (Hrs)

BalanceDays

BalanceHours

Time Off Taken (Days)

Time Off Taken (Hrs)

TakenToDateDays

TakenToDateHours

Why do time off balance values differ depending on the source?

In the Time Off Balance report, the time off balance displayed is your exact balance on the “As of” date you select. However, since the Time Off Calendar is more of a planning tool than a report, calendar balances take into account future time off booked up to the next balance reset or new policy. Balances displayed in both will be identical if you have no future time off booked.

Web TimeSheet Application Note, Using the Time Off Balance Web Service
Copyright 2009 Replicon, Inc.