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:

[WebTimeSheetURL]/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
UserLoginName1	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.
TimeOffTypeName2	The name of the time off type whose balance you want returned.

¹ Required field

² Available in the GetTimeOffBalanceDataForType only.

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

Example 1 (Internal web server): http://johnsmithxp:81/timesheet/services/TimeOffBalanceReportService.asmx/GetTimeOffBalanceData?userLoginName=admin&asOfDate=June 2, 2009

Example 2 (ISAPI IIS):

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

Example 3 (Replicon-hosted/SaaS):

http://hosted.webtimesheet.com/companyx/services/TimeOffBalanceReportService.asmx/GetTimeOffBalanceDataForType?userLoginName=sally&timeoffTypeName=vacation&asOfDate=March 15, 2009

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 data 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.