Skip directly to search Skip directly to A to Z list Skip directly to navigation Skip directly to page options Skip directly to site content

Lessons Learned Implementing SOAP Interface

The Transport Layer Expert Panel, in support of their recommendation of SOAP (Simple Object Access Protocol) as the standard for immunization data exchange, collected lessons learned from Hewlett Packard and the State of Oregon who have implemented the SOAP interface.


When implementing a SOAP interface in an Immunization Information System, software engineers who had worked in a SOAP environment before faced unique issues specific to the healthcare domain while meeting the interoperability needs of the diverse scale and platforms of different providers.

Client secure sockets layer (SSL), although conforming to prevailing healthcare standards and providing a high performance authentication layer, presented challenges such as prohibitive cost, added installation complexity, and potential IT policy issues with custom certificates. Requiring all providers to purchase commercially CA-signed certificates would add significant cost barriers; therefore, the custom CA certificate signing provided a low-cost alternative.

"Both Wisconsin and Oregon adopted the custom certificate approach. In the event that a particular IT department had policies to only allow commercial certificate authorities, the web server was configured to work with access control lists to reference each assigned client certificate. So, we found there were workarounds in either case. Wisconsin removed the client certificate management away from provider offices by creating a web service client bundle for easier installation and implementation at a provider office."

On the platform side, there can be compatibility issues when implementing security between web services stacks. Consulting with successful registry implementations is recommended to save time and hassle for an initial web services implementation.

Wisconsin demonstrated a real need to continue to support the sending of batch files; however MTOM worked nicely for that purpose, allowing upload and download of batch files with very good performance.

State of Oregon

Oregon solicited advice and lessons learned from early web services adopters so that other IIS partner sites could benefit from their conversion efforts. Oregon received funding to pilot web services with a limited number of sites. The funding was time-limited, requiring projects to be completed in a seven-month period. This affected all aspects of the project. Experiences will vary given different environments and circumstances.

Biggest challenges for providers (anticipated and unanticipated) included:

  • Delayed timelines for testing and IIS system downtime.
    • Web service development occurred concurrent with provider EHR enhancements on a very tight schedule.
    • Providers were impacted by delays in web service deliverables.
  • Inconsistencies in documentation and platforms.
    • Local IIS requirements may differ from CDC Implementation Guide.
    • Differences in batch and real-time HL7 data exchange parsing also caused issues.
  • Underestimating internal ability to modify EHR.
  • Underestimating time needed to fulfill requirements.
  • EHR vendor schedule effect on provider milestones accomplishment.
  • Certificate management and testing.
  • Operationalizing "on the fly".
  • Variation between systems (even when the same EHR).
 Top of Page

How were these challenges addressed by providers?

  • Use of middleware when the EHR was not a viable option for real-time HL7 messaging.
  • Adoption of interfaces by providers that were unable to modify the EHR to capture immunization data specific to Oregon’s IIS requirements. In some cases, interfaces were preferred over internal data screens.
  • Early and open discussions with the EHR vendor if system modifications will be made.
  • Plan for delays and testing and have an internal project team to oversee and troubleshoot that includes both program and tech staff.
  • Confirmation by provider organizations (from the EHR perspective) that required messaging contents are supported. Awareness of organizational workflow plans for verifying patient immunization status and mechanisms for communicating status changes to the IIS system.
  • Awareness of options and resources available to support a secure HL7-formatted text body in a SOAP request message sent through a web service client while being able to process an HL7-formatted text body in a SOAP response message.
  • Options for creation and management of security keys and certificates. Ability to determine support for these needs at the EHR or middleware level early on in the process to help streamline overall implementation efforts.
 Top of Page

From the field –tips from providers:

At the end of the pilot project, Oregon asked participants, "If you could give three tips to another organization, what would those be?" Responses from six organizations follow:

Provider 1:

  1. Consider paying for training or experienced consultants that have actually done this type of work before.
  2. It always takes longer than you think it will take to build the systems you want to build.
  3. Ask lots of questions and seek out other organizations that are already doing similar work with similar products for advice and feedback.

Provider 2: We recommend the following three tips to avoid some of the issues it encountered during the project:

  1. Test connectivity between the EHR and IIS as early in the process as possible to ensure ample time for troubleshooting.
  2. Allocate sufficient in-house staff time to ensure the project stays on track and to facilitate the work with third-party vendors.
  3. Allow for more (operational) time to implement both query and response messaging. (This recommendation comes as a result of the connectivity difficulties.)

Provider 3:

  1. Prepare your EHR system with functional data placement. Specifically, ensuring that each vaccine data point (site, route, dose, given by, VFC, etc) is in fact mapped to corresponding observation terms one for one. This will avoid the need for complete data clean up or extensive programming to extract and sort needed field data.
  2. Allow your team adequate time and complete access to ALERT technical support and if possible IIS vendor technical support.
  3. Be sure to plan for system downtime from both sides of the interface. Whether the downtime issues are caused on IIS’s side or with your EHR program, this can greatly impact the scheduled time your team has allotted to this project.

Provider 4:

  1. Start with clean, functional data.
  2. Be sure to give your organization ample time for thorough testing and staff training.
  3. Research and hire good, reliable resources to assist with the project.

Provider 5:

  1. Be flexible. Schedules change and milestones come and go but always do what you can with what you have.
  2. Involve your end users in the process and encourage them to "own" it, so it doesn't become another one of those dreaded IT projects.
  3. When you're done, and we’re almost there, celebrate your accomplishment.

Provider 6:

  1. Plan enough time.
  2. Use an experienced consultant.
  3. Test, test, test!

See SOAP Web Services for additional implementation resources.

 Top of Page