An Updated Primer on BMC Remedy AR System® Web Services

Version 3
    Share This:

    This week's theme:  Cool Tech Tips

    An Updated Primer on BMC Remedy AR System® Web Services

    With the ongoing, and to a large extent, new efforts that organizations are placing on "Web Service enabling" various applications within their infrastructure, this article will revisit Web Services from a BMC Remedy AR System standpoint. This article provides details on the "inner workings of a Web Service request" where AR System has published a Web Service that can be consumed by 3rd-party applications. The goal in providing this information is to help AR developers gain a better understanding of how Web Service requests are processed in AR System. But more importantly, this information should provide better context when installing and configuring various components of the AR System server and Mid-Tier, and when performing the various tasks for Web Service enabling an application. Finally, if SOAP, WSDL or W3C are acronyms that are unfamiliar, you should stop now and read a Web Services primer before continuing this article. You should also read Chapter 13 of the Action Request System 6.3: Developing AR System Applications: Advanced manual. If you've done both, go ahead and dive right in!


    Remedy introduced Web Services capabilities in the AR System platform with the release of AR System 5.1 in late 2002. Since this release, AR System developers could easily publish and consume Web Services to integrate business processes that span AR-based and other applications.

    The diagram on page 381 of the Advanced Developer's manual depicts an external application issuing a Web Service request to AR System (in this case, AR System has published a Web Service).


    Note: Click images for full screen view.

    Figure 1 – Diagram from Advanced Developers Guide


    As depicted in the above diagram, a SOAP request is received by the AR System Mid-Tier. Not shown, the Mid-Tier actually invokes the Apache AXIS servlet to process the SOAP request (This servlet is installed when installing the AR System Mid-Tier on the web server). The AXIS servlet parses the request to get the SOAP header and body information for further processing. The SOAP header contains user, password, and authentication information, which is used by the AR System server to control access and enforce permissions and security. The SOAP body contains other key information including: Web Service name, operation, XML document, and query string (if appropriate). The AR System Mid-Tier then expands the xpath expressions in the query string that will be needed to modify or retrieve the appropriate data (i.e. OpSet or OpGet, or OpGetlist). Finally, the AXIS servlet extracts the XML document formatted originally by the consuming application.


    Once the SOAP body is parsed, the AR System Mid-Tier retrieves input and output mapping information from the AR System Server (or from memory) based on the Web Service name (e.g. WS-HD-Incident). This information contains instructions on how to map the data contained in the XML document to the appropriate data fields in AR System.


    Upon receiving the appropriate mapping information from AR System, the Mid-Tier then uses the XML document, SOAP header data, operation type, query string (if appropriate) and the mapping information to construct a Java API request. This API request uses the (not well-known) ARXML API to pass the above data to the AR System Server.


    When AR System receives the API request, the AR Server parses the XML document by invoking the Xerces library. The AR Server receives the parsed data and uses this data as well as the mapping information to create the internal C routines that ultimately perform the appropriate data access / modification routines in the AR System database. The following detailed process flow depicts the above:


    Figure 2 – Detailed Process Flow


    In this response processing, AR System will take the returned data and invoke the Xerces library to format the appropriate response XML document. AR System will again use the mapping information (this time the output data mappings contained in the API request) to construct the XML document.

    Once the XML document is constructed, the AR Server passes it back to the Mid-Tier. The Mid-Tier completes the last steps of this Web Service request by invoking the AXIS servlet to send the SOAP response back to the originating requester.

    In a future tips and tricks article we will dive into the inner workings of how AR System can consume an external Web Service and more advanced issues around transaction integrity, error handling, and performance and scalability concerns.

    Good luck Web Service enabling your systems!

    ~ Rick, Product Manager, Joined 1995
    ~ Kumar, Staff Product Developer, Joined 1997
    ~ Maruthi, Staff Software Developer, Joined 1999