Accessing the UMLSKS SOAP Web Service using PHP5

There's a new SOAP web service (thankfully replacing the old TCP socket-based service which I could never get to work), but the only documentation is for the Java library they provide. The beta trial is about to end this week, but once the final service is launched the methods described below should still work.

First you have to get a UMLS license number and register for a UMLSKS account, then sign up for the beta service, which gives you a username and password that are used below. You also get a certificate for use in the SOAP calls, but that doesn't seem to be necessary yet.

The web service uses CAS for authentication, which is why the process below is a bit complicated. First it uses your username and password to fetch a permanent 'proxy grant ticket', which is cached locally. That ticket is then used to generate one-off 'proxy tickets' for subsequent requests.

A service method is then called ('suggestSpelling' in this case), with an array of parameters. These have to be dug out from the Service WSDL file, but loading it into the Generic SOAP client makes that a bit easier.

<?php
// use the Authorization WSDL to generate a CAS ticket
$client = new SoapClient('http://kswebp1.nlm.nih.gov/DocPortlet/html/Authorization.wsdl', array(
  'trace' => 1,
  //'local_cert' => 'your_certificate.cer',
  ));
  
// if a proxy granting ticket hasn't already been generated, fetch one and store it locally
$proxy_ticket_file = 'proxy-ticket.txt';
if (file_exists($proxy_ticket_file)){
  $pgt = file_get_contents($proxy_ticket_file);
}
else{
  try{
    $pgt = $client->getProxyGrantTicket('USERNAME', 'PASSWORD'); // fill in with your username and password for the web service
  } catch (SoapFault $exception) { print_r($exception); exit(); }
  
  file_put_contents($proxy_ticket_file, $pgt);
}
// use the proxy granting ticket to generate a single-use proxy ticket
try{
  $pt = $client->getProxyTicket($pgt, 'http://umlsks.nlm.nih.gov');
} catch (SoapFault $exception) { print_r($exception); exit(); }
// use the UMLSKS Service WSDL to perform actions
$umlsks = new SoapClient('http://kswebp2.nlm.nih.gov/UMLSKS/services/UMLSKSService?wsdl', array(
  'trace' => 1,
  ));
  
// print_r($umlsks->__getFunctions()); exit();
$word = 'cels'; // word to check for spelling
try{
  $response = $umlsks->suggestSpelling(array(
    'casTicket' => $pt,
    'release' => '2007AC',
    'term' => $word,
    ));      
} catch (SoapFault $exception) { print_r($exception); exit(); }
// print_r($response);
print_r($response->contents);  // an array of suggested words