The Interface

This interface uses the Simple Object Access Protocol (SOAP), which is a data interchange protocol based on XML. One of the primary purposes of SOAP is to provide language-independent remote procedure calls between a client and a server with less overhead than traditional remote-object systems. To accomplish this, SOAP uses HTTP to transport calls and responses, meaning that it can be easily integrated into existing web infrastructure without adding a lot of complexity. The SOAP specification can be found at http://www.w3.org/TR/SOAP/. The SOAP interface is described by a Web Services Description Language (WSDL) document, which provides information about data types, functions, and other interface details to the client.

Access

Since SOAP uses HTTP to transport calls and responses, the client will access this interface through the same server that provides the web-based user interface to Timesheet. If the client can access the web server portion of the Journyx installation, it can use the SOAP interface. This eliminates the need for special firewall / network configuration.

SOAP client libraries are available for most popular programming languages. This interface is developed to be compatible with the Apache Axis library for Java and Microsoft SOAP 3.0 for Visual Basic, but any other SOAP client that understands WSDL with complex types should be usable. Journyx does not supply any SOAP client tools, but you can obtain the tools mentioned above from the following websites:

Apache Axis: http://ws.apache.org/axis/

Microsoft SOAP: http://msdn.microsoft.com/webservices/building/soaptk/

Please see the example package (distributed separately) for more information on using the jxAPI with these clients, sample code showing how to use jxAPI data types and functions, and the required type conversion DLL for Microsoft SOAP.

Data Types

SOAP is a language-independent protocol, with its own object model and data types. Typically, a client library handles the mapping between SOAP and a specific language, so that in general, using the SOAP API is not much different than calling into “native” libraries or modules. The WSDL service description is used by the client software to map native types to their SOAP representation.

The following mappings between SOAP types and native types are used in this interface:

Lists are represented by standard SOAP arrays, and records are represented by complex types defined in the WSDL service description. In most SOAP clients, these will be mapped to an appropriate construct in the client language. In Java, using the Axis library, this means that lists are standard Java arrays, and records are Java objects of an appropriate class, with bean-like accessor methods for their contents. In Visual Basic, using the MS-SOAP library, lists are standard arrays and records are COM objects defined in a type mapping DLL (supplied as part of the examples package).

WSDL Service Description

The WSDL service description is required by SOAP client software so that it can map SOAP types and services to constructs in the client language. A WSDL document is automatically generated by the Journyx Timesheet server when it is installed, and is available through its web server at the following URL:

http://server/doc_root/jxapi.wsdl

This WSDL document includes a pointer to the actual SOAP server URL, so that normally you will not have to reference it directly in your client unless you wish to connect to a Timesheet server other than the one the WSDL document was obtained from. The SOAP server URL is always:

http://server/doc_root/jtcgi/jxapi.pyc

For example, if Timesheet is installed on the machine test.journyx.com at port 3333, the URL of the WSDL document would be http://test.journyx.com:3333/jxapi.wsdl. It is recommended to always include the port number even when Timesheet is running on the default web port (80).

The doc_root is optional, but is often used when more than one logical “site” runs on the same host and port, or when Journyx, Inc. is hosting Timesheet as an Application Service Provider (ASP). In most cases, there will be no “document root” on locally hosted sites, and the doc_root part of the URL is not used.

Exception (Error) Handling

Unless otherwise specified, all errors or internal Python exceptions will be reported by the return of a SOAP Fault response, so that a successful return indicates that no error has occurred (unless the method specification states otherwise. ) In most languages, the client library will translate this into an exception, which will then be channeled through the native error handling mechanism. If the client language does not support exceptions, it is the application programmer’s responsibility to check for a fault condition after each call to a SOAP object.

In Java with the Axis library, SOAP faults are translated to an AxisFault exception. In Visual Basic with the MS-SOAP library, you can check the err variable to see if a fault has occurred, and inspect the faultcode, faultstring, faultactor, and detail attributes of the proxy object to determine the nature of the fault.