The Adapt Web Services are a SOAP based API to 11 service endpoints offering interfaces for:

  1. Authentication
  2. Executing Business Objects
  3. Searching
  4. Accessing Entities
  5. Accessing Documents
  6. Calendar
  7. Tasks
  8. Journal Access
  9. Code Groups
  10. Meta Data
  11. Data Admin Requests

The full documentation for the services and all the available methods can be found here. On the whole the operation of the web services and the functionality offered by the methods is fairly straightforward and easily understood from the documentation. However a few areas to bear further description.

Licensing

The use of Web Services for integrations other than those provided by Erecruit requires the purchase of an additional license. This may be included in the initial purchase agreement, or added at anytime by contacting your Adapt representative.

WSDL

SOAP services are described using a WSDL file and many languages and IDEs will generate wrapper classes for SOAP services from a WSDL file. Beware of utility classes that use the WSDL file dynamically at runtime - these can have a serious impact on performance of your soultion and for that reason we would not recommend you use them.

Adapt is supplied with a combined WSDL file that describes all the SOAP endpoints in a single WSDL. The WSDL can be retrieved from the following URL on the Adapt system that you are integrating with:

http://<adapt_server>:<adapt_port>/WebApp/LogonServiceV1?wsdl

Where:

<adapt_server> is the IP address or DNS name of the Adapt server you want to integrate with

<adapt_port> is the port number that you normally connect to (usually 80 or 8080)

The <adapt_server> and <adapt_port> will usually be the same as users of the Adapt system use to login to Adapt.

Authentication

In order to use any of the web services an ID must first be obtained by calling the logon() method of the LogonServiceV1 service. The ID returned can then be passed to all other methods to identify the web service session. The SOAP request for an example call is shown below, for a full description see the webservices documentation:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:typ="http://webservice.bis.com/types">
   <soapenv:Header/>
   <soapenv:Body>
      <typ:logon>
         <String_1>{username}</String_1>
         <String_2>{password}</String_2>
         <String_3>{domain_name}</String_3>
         <String_4>{profile_name}</String_4>
         <String_5>{language}</String_5>
         <String_6>{time_zone}</String_6>
         <int_7>{date_format}</int_7>
         <int_8>{time_format}</int_8>
      </typ:logon>
   </soapenv:Body>
</soapenv:Envelope>

There is a corresponding logoff() method that should be used to release the web service session once it is no longer needed. The session will automatically expire after a period of inactivity (which can be modified). For developers using web services from a web page, it is expected that the page request lifecycle will first logon, then perform the web service tasks necessary to fulfill the page request and finally logoff to release the session. If this lifecycle is not followed, depending on the timeout period and the volume of users on the website, large numbers of sessions may be active concurrently consuming significant resources on the Adapt application server.

An example SOAP request to logoff a session is shown below:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:typ="http://webservice.bis.com/types">
   <soapenv:Header/>
   <soapenv:Body>
      <typ:logoff>
         <long_1>{session_id}</long_1>
      </typ:logoff>
   </soapenv:Body>
</soapenv:Envelope>

Searching and Saved Results

The Adapt Web Service interface provides methods for performing searches against the Adapt database. One way in which this can be used is to retrieve multiple columns of data in a minimum number of web service calls, for example, to display the results of job search in a tabular format. This technicque takes advantage of the getSearchResultsXML() method, which in turn requires that the results of the search have been saved.

When using this technique you should take care to delete the saved result sets when they are no longer needed, otherwise they will be retained indefinitely on the Adapt server potentially resulting in a performance issue.

One technique for cleaning up unneeded result sets would be to store the result set IDs of each search in the session, then when the session comes to an end (for example the Session_OnEnd event in ASP) iterate through the IDs and delete each one.

© Erecruit Holdings LLC