Skip to main content

Using the jxAPI With C#.NET 2.x

Warning: legacy API

This page is about the legacy SOAP-based jxAPI that is no longer updated or recommended for use in new projects. The documentation in this section may be outdated or inaccurate, and is provided for reference purposes only.

Journyx recommends using the REST-based API for new projects in most cases. However, at the current time, there are certain object types that are not available through the REST API.

Note: For .NET 3.x and newer with Visual Studio 2008 or newer, please see Using the jxAPI With C#.NET 3.x and Later for an updated guide.

Requirements​

  • A Journyx installation
  • Visual Studio 2005
  • Windows XP SP2
  • .NET Framework 2.0

Activating the jxAPI​

Note: In Journyx 8.8 and newer, the jxAPI is activated at install time, so the following process is not necessary. For Journyx versions prior to 8.8, please follow these instructions as shown.

Before you can use the jxAPI to communicate with a Journyx server, it must be activated on that server. Log in to the server as an administrator, and check the administration menu for a "jxAPI Preferences" link. Some versions of Journyx that support the jxAPI don't have this link; if it isn't there, visit the following URL, replacing the hostname and port with the proper values for your Journyx server:

http://<hostname>:<port>/jtcgi/jxapipref.pyc

Check the "jxAPI Active" checkbox and submit the form. Activating the jxAPI may take a few seconds even on a lightly loaded server, so please be patient. Once the activation is complete, take note of the jxAPI WSDL URL shown on this screen, as you will need it later.

Preparing Your C# Project​

To use the jxAPI in a C# project, you can add a Web Reference to it. From the Project menu, select "Add Web Reference…" to open the Add Web Reference dialog. In the URL field near the top of the dialog, enter the following, replacing the hostname and port with the proper values for your Journyx server:

http://<hostname>:<port>/jxapi.wsdl

After a few moments, the text field in the dialog should show that a service called "jxapi" has been found. You may change the name assigned to the jxAPI in your project by editing the "Web reference name" field. Click the "Add Reference" button to add the jxAPI reference to your project.

Connecting​

The first step in using the jxAPI is to obtain an object that represents a connection to the server. The type of this object is referencename.jxapi; that is, if the web reference you added in the previous step is called timesheet, the connection object is of type timesheet.jxapi. For example:

namespace ConsoleApplication1
{
  class Program
  {
    static void Main(string[] args)
    {
      timesheet.jxapi jxapi = new timesheet.jxapi();

      // ...
    }
  }
}

The connection object is a proxy for the entire jxAPI; it has methods corresponding to the methods in the jxAPI, and calls to it will be translated automatically to server operations.

Error Handling​

Attempts to call jxAPI methods with improper or incomplete arguments will be caught on the client side, often during program compilation. Errors occurring on the server, and certain client-side protocol errors, will be reported as SOAP faults, causing a System.Web.Services.Protocols.SoapException exception in your application. This single exception type may correspond to many different kinds of server-side error, from bad passwords to data validation errors and more. If your code catches a SoapException, you can use its methods and properties (Detail, for example) to examine the error report provided by the server.

Data Types​

In the jxAPI reference documentation, data types are referred to by generic names like "string" and "number". These correspond to specific C# types as follows:

  • a jxAPI "integer" is an int
  • a jxAPI "float" is a double
  • a jxAPI "string" is a string
  • a jxAPI "boolean" is a bool
  • a jxAPI "list" is an array (for example, a "list of int" is an int[])
  • a jxAPI "record" or "structure" is a C# object

Each record type is declared as part of the web reference. For example, a TimeRecord object is represented by a C# class timesheet.TimeRecord (if the web reference is called "timesheet").

Authentication​

Nearly all parts of the jxAPI require authentication, just as using Journyx from the web interface does. Authentication in the jxAPI is session-based; your application "logs in" with a user name and password, and receives a session key which must then be passed back to the server with every method call. For example:

timesheet.jxapi jxapi = new timesheet.jxapi();
String skey;

skey = jxapi.login("joe", "joespass", 1);

The third parameter to the login method determines whether to keep any existing sessions for this user. If it is 0, all other sessions for the user, including web logins, will be automatically terminated; if it is 1, they will be ignored.

With only a few exceptions, every method in the jxAPI takes the session key as a parameter. The jxAPI cannot be used to bypass Journyx's normal security model—most users can access only their own data, and only administrators have free reign.

Your application should always log out each session that it creates, by calling the logout method when done:

jxapi.logout(skey);

Records​

Almost everything in the Journyx database is stored as records. For example, a week of time entries which appear on a single page in the web user interface may actually correspond to several records, one for each filled grid square. Each entry in the pull-down fields (project, pay type, etc.) is a record, and so is each user.

Records, and other types of structured data used by Journyx, are represented by C# objects. The web reference that you previously generated from the server's WSDL includes a C# class for each record type used by the jxAPI. Each of these classes has properties corresponding to the fields described by the jxAPI. For example, if a record has an id attribute (as most of them do), then its C# object will have an id property that can be read and assigned to. The jxAPI Reference has a full list of the fields in each type of record, and their types.

More About Records: Time Entry​

Time entries are represented by a single record per grid square. A full row on a user's time sheet corresponds to up to seven records, one per day, each with the project, pay type, bill type, and comment set for that row.

The first step in creating a time record is to create a TimeRecord object. Simply calling "new timesheet.TimeRecord()" isn't usually the best way to do this; the C# constructor creates a completely empty record, and there are several fields that can and should be filled in with default values by the server. The getDefaultTimeRecord method asks the server for a fresh time record with default values already filled in. Finally, after the rest of the record is filled in, the addFullTimeRecord method inserts it into the Journyx database:

timesheet.TimeRecord trec;
String id;

trec = jxapi.getDefaultTimeRecord(skey);
trec.hours = 6.0;
trec.comment = "test record";
id = jxapi.addFullTimeRecord(skey, trec);

Notice that the session key is passed as the first parameter to both jxAPI calls. The getDefaultTimeRecord method implicitly creates a record referring to the current user and today's date, and addFullTimeRecord will throw an exception if the current user doesn't have permission to add this record (if, for example, the user field of the record doesn't match).

Also note that addFullTimeRecord returns an ID. The ID of a record is a unique key generated when the record is first added to the Journyx database. It can be used later to delete or modify a record:

trec = jxapi.getTimeRecord(skey, id);
trec.hours = 7.0;
jxapi.modifyTimeRecord(skey, id, trec);
jxapi.removeTimeRecord(skey, id);

Other Record Types: Common Methods​

The methods described above in the discussion of time entries have counterparts for other record types in the jxAPI. For example, there is a getDefaultExpenseRecord, addFullExpenseRecord, getExpenseRecord, and so forth, with corresponding methods for each of the core types: TimeRecord, ExpenseRecord, User, Project, Code (Task), Subcode (Pay Type), Subsubcode (Bill Type), and Group.

Project and Code Lists​

If you are creating time and expense records, you probably want to fill in the Project, Task, Pay Type, and Bill Type fields with meaningful values. (The latter are called code, subcode, and subsubcode in the TimeRecord and ExpenseRecord objects for historical reasons.) The jxAPI provides several methods to retrieve all available values for those fields:

String[] x;

x = jxapi.getProjectList(skey);
x = jxapi.getCodeList(skey);
x = jxapi.getSubcodeList(skey);
x = jxapi.getSubsubcodeList(skey);

In each case, the return value is an array of strings in which each pair of elements is the ID (to put in the corresponding field of a time or expense record) and name of a project, code, subcode, or subsubcode. Since these methods are authenticated, the returned list only includes items available to the current user.

Sheets​

A time sheet represents a batch of time entries in a date range. You do not need to explicitly create time sheets (they exist automatically based on the timekeeping periods defined by the Journyx administrator) but you should take them into account when creating time records. To retrieve the current user's time sheet for a specific date, use the getTimeSheetIDByDate method; once you have the ID, you can manipulate it:

String id;
Double hours;
String[] a;

id = jxapi.getTimeSheetIDByDate(skey, '20051001');
hours = jxapi.getTotalHoursInTimeSheet(skey, id);
a = jxapi.getDatesInTimeSheet(skey, id);
a = jxapi.getTimeRecordIDsInSheet(skey, id);

When you add a time record, you should add it to the proper sheet; likewise, when you remove a time record, you should remove it from the sheet:

String trecid, tsid;
timesheet.TimeRecord trec;

trec = jxapi.getDefaultTimeRecord(skey);
trec.hours = 6.0;
trecid = jxapi.addFullTimeRecord(skey, trec);
tsid = jxapi.getTimeSheetIDByDate(skey, trec.date);
jxapi.addTimeRecordToSheet(skey, tsid, trecid);

jxapi.removeTimeRecordFromSheet(skey, tsid, trecid);
jxapi.removeTimeRecord(skey, trecid);

Finally, you might want to submit a time sheet and, later, check its status:

jxapi.submitTimeSheet(skey, tsid);
System.Console.WriteLine(jxapi.getTimeSheetStatus(skey, tsid));

The jxAPI also contains methods for approving and rejecting sheets, Expense and Mileage sheets, and administering approval templates. For more information on these topics, see the jxAPI Reference.

Other Features​

The samples in this document show only a small part of the jxAPI's complete functionality. Most features of Journyx are accessible through the jxAPI now, or will be soon. The jxAPI Reference will contain an up-to-date list of every method and data structure it supports.