How do I set up my Career Centre API?

Where do I find my web service?

On your server the web service is accessible in the ‘ws’ sub folder of your main 3hats URL. So if you access your Perform Zone system using:
http://yourcompany.performzone.com/performzone/

Then your web service would be located at:
http://yourcompany.performzone.com/performzone/ws/server.php

If you go to that link using your own URL you will see a general web service description and list of functions. Not all of these functions are relevant to the web site – they are used by other systems and not covered in this document. They also need to be accessed in a different way.

How do I setup the web service?

Firstly you need to contact Perform Zone technical support – there may be a charge to make the web site section of the web service accessible. Technical support will switch on the web site parts of the service (covered in this document below), and provide you with an ‘Access Key’. This key must be sent with every request that goes to the web service to authenticate you as being allowed to access these services.

This key should be kept private, only given to web developers working on your site.

How do I call the web service?

The web service uses the standard SOAP protocol, one of the most common used on the web. This uses XML to transport data in an easily understandable format.

There are many libraries in many programming languages that make it easy to use SOAP – we will provide examples in the PHP language; these should be easy to convert to other languages.

Basically to access the web service you make calls to the services endpoint providing your access key, and any data required by the specific service call. The service will then process this and provide a response with data, or an error code and message. You can then parse this information and display whatever you need to, however you want.

If you are using PHP there is a library called ‘nusoap’ which makes it very easy to make SOAP web service calls. Here is an example of calling the basic job information web service (GetJobInfo) using PHP and nusoap:

// this should point to your nusoap main include file.

require_once(‘nusoap.php’);

$client = new nusoap_client(‘http://myserver.threehats.com.au/3hats/ws/server.php’);

// Call the SOAP method

$result = $client->call(‘GetJobInfo’,

array(

‘accesskey’ => ‘my_access_key’,

‘JobID’ => 48

)

);

// Display the result

print_r($result);

The above code, once the correct values have been entered, will return the details of the job with ID of ’48’ in your Perform Zone system.

Here is the XML the SOAP service sends through from the above code:

<?xml version=”1.0″ encoding=”ISO-8859-1″?>

<SOAP-ENV:Envelope

SOAP-ENV:encodingStyle=”http://schemas.xmlsoap.org/soap/encoding/” xmlns:SOAP-ENV=”http://schemas.xmlsoap.org/soap/envelope/” xmlns:xsd=”http://www.w3.org/2001/XMLSchema” xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”

xmlns:SOAP-ENC=”http://schemas.xmlsoap.org/soap/encoding/”>

<SOAP-ENV:Body>

<ns2113:GetJobInfo xmlns:ns2113=”http://tempuri.org”>

</ns2113:GetJobInfo>

</SOAP-ENV:Body>

</SOAP-ENV:Envelope>

If you are familiar with SOAP messages the above should look pretty clear.

The ‘result’ returned will be an array of job detail information – for example:

$result[‘jobtitle’] will be the position title of the job in your Perform Zone system.

Here is the SOAP XML response which comes from the web service:

<?xml version=”1.0″ encoding=”ISO-8859-1″?>

<SOAP-ENV:Envelope

<SOAP-ENV:Body>

<ns1:GetJobInfoResponse xmlns:ns1=”http://tempuri.org”>

<jobtitle xsi:type=”xsd:string”>A test of advertising</jobtitle>

</return>

</ns1:GetJobInfoResponse>

</SOAP-ENV:Body>

</SOAP-ENV:Envelope>

Error Responses

Every response the web service returns will have 2 fields; ‘error’ and ‘errorcode’. ‘error’ is a plain text description of the error that occurred, ‘errorcode’ is an integer code referring to the error (more detailed explanations of errors can be seen in the appendix of this document).

If no error, then errorcode will equal ‘0’ (zero).

In the above example code if there was no job 48, the response would include:

$result[‘error’] = “Job with that ID does not exist.”

$result[‘errorcode’] = 110