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 do bear further description.

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 separate WSDL file for each service. The WSDL can be retrieved from the following URL on the Adapt system that you are integrating with:

https://<adapt_server>:<adapt_port>/webservices/<service_name>?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 (typically this is not needed as part of the URL)

<service_name> is the name of the web service that the WSDL is required for

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

 

The table below shows the services and the corresponding service names:

Service Service Name
Authentication LogonServiceV2
Business Object Executor BOExecServiceV2
Search SearchServiceV2
Entity Access EntityServiceV2
Document Access DocServiceV2
Code Groups CodeServiceV2
Tasks TaskServiceV2
Journal JournalServiceV2
Calendar CalServiceV2
Meta Data MetaDataServiceV2
Data Admin ManageRequestServiceV2

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