RXNORM >> SOAP
 
Building Applications to Use the RxNorm (SOAP) API
This page describes how to build applications to use the RxNorm SOAP API. The same steps can be used for the Prescribable, RxTerms and NDF-RT APIs by substituting the appropriate service names contained in the WSDL files for those APIs.
We provide documentation for coding Java and .Net applications. Documentation for building applications in other programming languages (e.g. Perl) may be added at a later time.

Building a Java Application to use the RxNorm API

The RxNorm API provides developers with functions for retrieving RxNorm data from the most current RxNorm data set. Building applications to use the RxNorm API require initial setup of the development environment and developing code. Each of these is described in detail in this chapter.

Java Development Environment Setup

Setup of a Java developer's environment involves the following steps. All steps must be completed before application code can be compiled and built to execute requests with the RxNorm API.
  1. Obtain a Simple Object Access Protocol (SOAP) 1.2 compatible engine for web service message routing.
  2. Download the WSDL for the RxNorm API web service.
  3. Generate the client side stubs using Axis's WSDL2Java utility for the WSDL (for applications written in Java).

1. Obtaining a SOAP 1.2 Engine

Developers will require a Simple Object Access Protocol (SOAP) 1.2 compatible engine to route the web service messages to/from the RxNorm API. The client programs shown in this guide have been tested with Apache Axis Version 1.4 Follow the link to their website and download and install the version onto your development machine. The location of this download will be referred to as <AXIS_DIR> in this guide.

2. Downloading the RxNorm WSDL

The RxNorm WSDL may be downloaded from the RxNav web site. Right-click on the RxNorm Service WSDL and save the WSDL file to your development machine. The path to this file will be hereafter referred to as <RXNORM_WSDL_LOCATION>.

3. Generating Client Stubs for Java

Apache Axis is delivered with a utility to generate Java classes from a WSDL. Using WSDL2Java generates client stubs that enable communication with a defined web service.
  prompt> java -classpath  <CLASSPATH> org.apache.axis.wsdl.WSDL2Java \
      <RXNORM_WSDL_LOCATION>
The call to the utility places generated Java class files in the directory where the utility is run. The <CLASSPATH> must include the following jar files generally found in the lib directory of the Axis installation:
axis.jar
wsdl4j-1.5.1.jar
commons-logging-1.0.4.jar
commons-discovery-0.2.jar
jaxrpc.jar
saaj.jar
activation.jar
mail.jar
Other SOAP engines use different utilities to generate the client stubs. Refer to your specific SOAP engine documentation for instructions on building the client stubs using the downloaded WSDL.

Coding Java Applications to use the RxNorm API

The basic paradigm for obtaining RxNorm data from the RxNorm API web service is as follows:
  1. Establish a connection to the RxNorm API web service.
  2. Obtain the data from the RxNorm API web service.

Java Code: Establishing a Connection to the RxNorm API Web Service

The RxNorm API web service is an Axis web service running at the NLM on the RxNav production machine. The web service endpoint URI is http://mor.nlm.nih.gov/axis/services/RxNormDBService The classes generated during WSDL2Java execution must be imported into your application. For Java applications, include these import statements:
import java.net.URL;
import BeanService.*;
import gov.nih.nlm.rxnav.axis.services.RxNormDBService.*;
The following code snippet shows how to establish a connection to the RxNorm API web service.
String rxhost = "http://mor.nlm.nih.gov";
String rxURI = rxhost + "/axis/services/RxNormDBService";

// Locate the RxNorm API web service
URL rxURL = new URL(rxURI);
DBManagerService rxnormService = new DBManagerServiceLocator();
DBManager dbmanager = rxnormService.getRxNormDBService(rxURL);

Java Code: Obtaining RxNorm Data

The RxNorm API web service provides access to current RxNorm data through its calls defined in the WSDL. The code snippet below searches for a concept unique identifier (RxCUI) using exact matching of an input string. Each operation made available in the RxNorm API web service is described in detail in the RxNorm API design document.
// Get the concept unique identifier for a string
String [] rxcuis = dbmanager.findRxcuiByString("aspirin");
// print results
for (int j = 0; j < rxcuis.length; j++)
    System.out.println("RXCUI = " + rxcuis[j]);
if (rxcuis.length == 0) 
    System.out.println("No concept found");

Compiling the Java Application

When compiling the application using the RxNorm API, the CLASSPATH must include the directory into which the compiled stubs were put and the following jar files which are generally found in the lib directory of the Axis installation:
axis.jar
wsdl4j-1.5.1.jar
commons-logging-1.0.4.jar
commons-discovery-0.2.jar
jaxrpc.jar
saaj.jar
activation.jar
mail.jar


Building a .Net Application to use the RxNorm API

.Net Development Environment and Project Setup

Setup of a .Net developer's environment involves the following steps:
  1. Install a current version of Microsoft Visual Studio .Net, selecting at least these options: VB, C#, and Web development. This tutorial mainly assumes VS 2010, but 2008 is known to work with minor differences.
  2. Start up Visual Studio. If it asks for default settings, choose C# or VB, depending on your preference. In this tutorial, we use C#.
  3. From the Visual Studio menu, choose File -> New Project
    In the Left pane, choose Visual C# -> Windows
    In the Right Pane, choose either Console Application (for a command-line-driven application) or Windows Forms Application (for a GUI-driven application)
    In the "Name:" box, enter a name for your project: RxNormClient or RxNorm_GUI_Client (or any project name you want)
    A new C# file skeleton named Program.cs that contains an empty Main() method in the Program class will be generated.
  4. Do not close Visual Studio and do not close the project or the current program file. You will need to return here later to complete the project setup.

Downloading the RxNorm WSDL and Generating a Client Stub for .Net

In the steps below, Open a command prompt window and enter:
cd [your_source_dir]
"[your_wsdl_dir]\wsdl.exe" /l:CS /protocol:SOAP http://rxnav.nlm.nih.gov/RxNormDBService.xml
The following message should be displayed:
Writing file '[your_source_dir]\DBManagerService.cs'
Your client stub is in the .cs file that was just created (DBManagerService.cs in this example)

Putting the pieces together into a .Net project

  1. You can now either...
    1. Add your client stub source file to your project in Visual Studio
      • In the Solution Explorer pane, right-click the project name and choose Add -> Existing Item
        (The beauty of this option is that it allows you to step into the stub source code in Debug mode.)
    2. Compile the stub into a DLL, by first executing the command line:
            "[your_csc_dir]\csc.exe" /t:library /r:System.Web.Services.dll /r:System.Xml.dll DBManagerService.cs
              
      then adding the DLL as a Reference to your project:
      • Right-click the project name in the Solution Explorer pane
      • Choose Add Reference... then select the Browse tab.
  2. Finally, your project needs a reference to the .Net Web Services namespace before it will compile:
    • Right-click the project name in the Solution Explorer pane.
    • Choose Add Reference... then select the .Net tab.
    • Select System.Web.Services and click OK.
  3. You are now ready to code your class's Main() method in any way you wish.
 
RXNORM >> SOAP