Webservice for usage in your website – Connexys Help

1) Overview

This article describes how to retrieve jobs from the Connexys Resource Manager for usage in your website. Connexys offers a SOAP API to query jobs.

This is a two step process:

1) Login using the cxsLogin.wsdl to get a session id

2) Get the jobs using cxsPositionWebservice.wsdl using the session id we got at step 1 and make sure you are using the correct end-point

Download both these WSDLs and use them in your website.

Instructions to find the correct end-point are stated below.

2) Login

We advise you to use a user profile with the box “Password never expires”, this user needs to use the permissionset called: “Webservice user”.

A security token has to be requested by this user. How to do this is described on: https://help.salesforce.com/apex/HTViewHelpDoc?id=user_security_token.htm&language=en.

A login call from the cxsLogin.wsdl has to be executed to the given endpoint in the cxsLogin.wsdl. This request has two parameters:

Username, the username of the user
Password, the password of the user, with the security token append directly after it

This request will return a loginResponse, the value of the sessionId field is what you require in the next step.

3) Getting the correct end-point

For most requests, the endpoint in the attached cxsPostionWebservice is correct. If it is not, you will get the faultcode sf:INVALID_SESSION_ID, even when using the sessionId just returned by a login request. To fix this we need to change the endpoint. All the way down in the used cxsPositionWebservice.wsdl there is a line:

<soap:address location="https://your.domain/services/Soap/class/cxsrec/cxsPositionWebservice"/>

To find your actual domain go to: Setup (or salesforce setup) -> My Domain.

There search for the cxsPositionWebservice and click on the WSDL link. Now you can view the WSDL and will find the correct end-point for your org in the tag <soap:address location>, near the end.

Update the url in the cxsPositionWebservice.wsdl with this.

Alternatively you can and probably should use the custom domain that applies to your org. See this article on setting up a domain if this is not yet set up for your org: https://help.salesforce.com/htviewhelpdoc?id=domain_name_overview.htm&siteLang=en_US

You can find it in Salesforce Set-up under Domain Management. See this picture:

The custom domain looks like this in most cases: 'connexys-<4 numbers>'
The soap address will then look like this:

<soap:address location="https://connexys-1234.cloudforce.com/services/Soap/class/cxsrec/cxsPositionWebservice"/>

The advantage of pointing the soap address to your custom domain is that in case of a node upgrade or org move to another instance there will be no impact on your interfaces.

4) Query jobs

Note! When working in a situation where a lot of jobs are posted on a media channel (see chapter 4 for when a job is posted). We recommend to request the jobs in batches. First read this chapter and then consult chapter 11 to read how to implement this.

Note! Wait with deleting the old jobs until new jobs are received. In this manner, the website will always be fixed with jobs (querying the jobs can take up to a few seconds). Working in this manner also helps in the rare occasion that the site is not able to connect with the webservice.

Jobs are queried using the wsdl. The getPositions request only requires one parameter. This is the cxs:sessionId which is placed in the cxsSessionHeader. There is one optional parameter in the webservice, placed within the cxs:getPositions tag: cxs:mediaChannel. Place the name or the ID of the mediaChannel to use in this parameter to get the jobs posted to this specific media channel. When omitted, you will receive all jobs posted to the default media channel.

5) When is a job posted?

The status of the job should be “Open”
“Permission to publish externally” should be checked
“Job description approved” should be checked
There should be a Job Advert for the media channel
Is the current date on or after the start date of this advert
Is the end date of this advert empty or before or on the current date

6) Quering in multiple languages

If jobs have to be queried in multiple languages, make multiple getPositions queries and use the setUserLanguage method of the webservice before each positions call.

Jobs will be repeated in each response, in the requested language. Each job will have the same value for the id field over multiple responses.

Valid values for the setUserLanguage method are the names of the language in their own language. At the moment the supported values are (limited by configuration in your org):

English
Dutch
Français
Deutsch
Slovenčina

7) Checking the webservice

To call the webservice manually the SoapUI tool van be used.

Download this SoapUI (free version) from http://sourceforge.net/projects/soapui/files/
Install this on your computer
Import the cxsLogin.wsdl and/or cxsPositionWebservice.wsdl into SoapUI (via File - New SOAP Project)
When using the login webservice, adjust the call to:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:partner.soap.sforce.com">

<soapenv:Header/>
<soapenv:Body>
  <urn:login>
      <urn:username>[USERNAME]</urn:username>
      <urn:password>[PASSWORD][SECURITY_TOKEN]</urn:password>
    </urn:login>
</soapenv:Body>
</soapenv:Envelope>

Replace [USERNAME], [PASSWORD] and [SECURITY_TOKEN] with their values (more about the security token in chapter 2)
When using the position webservice (with the correct end-point, adjust the call to:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:cxs="http://soap.sforce.com/schemas/class/cxsrec/cxsPositionWebservice">
<soapenv:Header>
     <cxs:SessionHeader>
   <cxs:sessionId>[SESSIONID]</cxs:sessionId>
     </cxs:SessionHeader>
   </soapenv:Header>
   <soapenv:Body>
    <cxs:getPositions>
    </cxs:getPositions>
</soapenv:Body>
</soapenv:Envelope>

Replace [SESSIONID] with a valid session ID, which is in the result of the login webservice
If no jobs are returned, follow the checklist in chapter 4

8) TLS 1.0 error message in SoapUI

It can happen that SoapUI gives you an error message stating that at least TLS 1.1 is required.
To fix this:
Step – 1: Navigate to C:\Program Files\SmartBear\SoapUI-5.2.1\bin folder. (or where ever your SoapUI is installed.
Step – 2 : Edit SoapUI-5.2.1.vmoptions file with any text editor.
Step – 3 : Add following entry and save the file. It will only enable TLS 1.2 protocol.
-Dsoapui.https.protocols=TLSv1.1,TLSv1.2
Step – 4 : Close and Re-launch the Soap UI.

9) Requesting another media channel

To request from another media channel, which is not the default channel. Add the <cxs:mediaChannel> tag to the <cxs:getPostions> tag. This can either be the name of the media channel or the ID of the mediachannel. This will result in:

... snip ...
   <soapenv:Body>
    <cxs:getPositions>
      <cxs:mediaChannel>Intranet</cxs:mediaChannel>
    </cxs:getPositions>
</soapenv:Body>
</soapenv:Envelope>

10) Example code (PHP)

Below is example code in PHP. We suggest using the NuSOAP library, although we can't guarantee it will work in your specific setup, several developers have reported succes with this toolkit.

// define constants

define ("salesforce_username", '');

define ("salesforce_password", '');

define ("salesforce_token", '');

define ("salesforce_wsdl", ''); //login wsdl

define ("salesforce_wsdl2", ''); //position wsdl

define ("salesforce_url", ''); // webservice url

//Disabling the WSDL cache

ini_set('soap.wsdl_cache_enabled', 0);

ini_set('soap.wsdl_cache_ttl', 0);

// simple header class

class AuthHeader{

var $sessionId;//string

function __construct($result) {

$this->sessionId = $result->result->sessionId;

}

$login_soap = new SoapClient(salesforce_wsdl, array('trace' => 1, 'features' => SOAP_SINGLE_ELEMENT_ARRAYS,'compression' => SOAP_COMPRESSION_ACCEPT | SOAP_COMPRESSION_GZIP));

try {

$result = $login_soap->login(array("username" => salesforce_username, 'password' => salesforce_password.salesforce_token));

} catch(Exception $e){

}

$positions_soap = new SoapClient(salesforce_wsdl2, array('trace' => 1));

$authHeader = new AuthHeader($result);

$header = new SoapHeader(salesforce_url,"SessionHeader", $authHeader,false);

// Unquote below to see functions

#print_r($new->getFunctions());

try {

$items = $positions_soap->__soapCall("getPositions", array(), array(), $header);

} catch(Exception $e){

}

// do something with the items

print_r($items);

11) Other available webservices
cxsContactWebservice - request all Contacts which have the "include_in_webservice__c" flag set to true, make sure you enable read access to the webservice user on the application settings object.
cxsAccountWebservice - request all Accounts (caps at 2000 elements)
cxsEventWebservice - request all Campus Events

These webservices work symetrical as the position webservice.
The WSDL can be downloaded by an user with administrator rights in setup/develop/classes and then right click and "download as" on the "WSDL" link in front of the webservice.

12) Working with a lot of jobs, or when it times out with a "CPU time limit exceeded" error
When working with a large number jobs, the webservice will time out with a "CPU time limit exceeded" error. The solution for this problem is calling the webservice in batches. Instead of calling the webservice only once as described above, the webservice has to be called multiple times.

Action path:
1 Get the ids of all open jobs. This is done by calling the "getPositionIds" method of the webservice. This one will return a list of all ids of jobs currently open to this (or the default) media channel.
2 Remove all records from your database which are not in this list of ids.
3 Split the list of these ids in batches of ids, suggested size is 100. But if you still get "CPU time limit exceeded" errors, for example because you are requesting a large number of custom fields, decrease this batch size.
4 For all the batches call the "getPositionsByIds" method of the webservice. Update any changed records. The reason all jobs are passed back, is because of performance reasons on our side.

Note! It can happen that you will get less positions then your batch size back if any got deleted between the webservice calls. This is not a problem and will be rectified in the next refresh. However, as an alternative, you can also delete records from your database which are not returned by the "getPositionsByIds" call.

Note! At the moment the maximum of job ids returned by getPositionIds 10.000. It is advised to use multiple media channels when hitting this limit.