Webservice for usage in your website

Follow

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

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) Query jobs

Note! Wait with deleting the old jobs untill new jobs are received. In this manner, the website will always be fixed with jobs (quering the jobs can take up to a few seconds). Working in this manner also helps in the rare occassion 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.

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://emea.salesforce.com/services/Soap/class/cxsrec/cxsPositionWebservice"/>

In this URL the part 'emea' describes the cluster you are connecting to. When the described error occurs you need to get the correct end-point for your org. To do this, the system administrator needs to login on the system and go to: Setup (or salesforce setup) -> Develop -> Apex Classes

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) When is a job posted?

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

5) 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

 

6) Checking the webservice

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

  1. Download this SoapUI (free version) from  http://sourceforge.net/projects/soapui/files/
  2. Install this on your computer
  3. Import the cxsLogin.wsdl and/or cxsPositionWebservice.wsdl into SoapUI (via File - New SOAP Project)
  4. 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>

  1. Replace [USERNAME], [PASSWORD] and [SECURITY_TOKEN] with their values (more about the security token in chapter 2)
  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>

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

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

8) 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>

9) 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);

 

10) 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.

 



Have more questions? Submit a request

Comments

  • Avatar
    Guus Meijer

    Added the custom domain URL as an alternative to the main salesforce nodes like eu1, eu5 etc.

Powered by Zendesk