Call-SOAPService

Advanced Customization > Info*Engine User’s Guide > Task Webject Reference > Message Webjects > Call-SOAPService

Call-SOAPService

Makes a request to a third-party Simple Object Access Protocol (SOAP) service. This webject uses an Info*Engine group and an XSL template to format a SOAP request. The webject output can be directly generated as an Info*Engine group that mimics the SOAP response body, or an XSL template can be specified to translate the SOAP response into an Info*Engine group.

If a SOAP fault occurs, then an instance of com.infoengine.exception.fatal.IERemoteException is generated.

SYNTAX

<ie:webject name="Call-SOAPService" type="MSG">
  <ie:param name="DBUSER" data="username"/>
  <ie:param name="ENDPOINT" data="url"/>
  <ie:param name="GROUP_IN" data="groupName"/>
  <ie:param name="GROUP_OUT" data="groupName"/>
  <ie:param name="PASSWD" data="password"/>
  <ie:param name="SOAP_ACTION" data="operationName"/>
  <ie:param name="XSL_URL" data="url"/>
  <ie:param name="XSL_RESPONSE_URL" data="url"/>
  <ie:param name="XSL_DBUSER" data="username"/>
  <ie:param name="XSL_PASSWD" data="passwd"/>
</ie:webject>

PARAMETERS

Required	Select	Optional
ENDPOINT		DBUSER
GROUP_IN		EXCEPTION_ON_FAULT
XSL_URL		GROUP_OUT
		PASSWD
		SOAP_ACTION
		XSL_DBUSER
		XSL_PASSWD
		XSL_RESPONSE_URL

DBUSER

The username to use to authenticate to ENDPOINT. This parameter is used in conjunction with PASSWD if the SOAP endpoint specified on the ENDPOINT parameter requires authentication. This parameter is optional.

ENDPOINT

The URL of the SOAP endpoint to which the SOAP request should be sent. This parameter is required.

EXCEPTION_ON_FAULT

Specifies whether an exception is thrown if the service responds with a SOAP fault. The default value is true. If the parameter is set to false, then no exception is thrown if a fault occurs. If XSL is being used to transform the results, then an XSL template can be used to translate the fault into Info*Engine data (including the contents of the detail element), and other actions taken. If XSL is not being used, then the webject translates the fault into an Info*Engine group. This parameter is optional.

GROUP_IN

The Info*Engine group containing data to combine with the XSL template specified on XSL_URL. This parameter is required.

GROUP_OUT

The name of the Info*Engine group representing the SOAP response. If XSL_RESPONSE_URL is specified, then it is used to translate the SOAP response into an Info*Engine group named with the GROUP_OUT value. If XSL_RESPONSE_URL is not specified, then this group contains a single element and one attribute per XML element in the response. The value of an attribute can be an object, representing element data; or an Info*Engine element, representing additional nested XML elements. The name of an attribute matches the corresponding XML element name. The default value for this parameter is SOAPResponse. This parameter is optional.

PASSWD

The password corresponding to DBUSER. This parameter is optional.

SOAP_ACTION

The value (if any) of the SOAPAction header that should be sent. This parameter is optional.

XSL_DBUSER

The username to used to authenticate to XSL_URL and XSL_RESPONSE_URL. This parameter is used in conjunction with XSL_PASSWD if the XSL templates to be used by the webject reside on a remote HTTP server that requires authentication. This parameter is optional.

XSL_PASSWD

The password corresponding to XSL_DBUSER. This parameter is optional.

XSL_RESPONSE_URL

The location of an XSL template used to process the SOAP response. The XSL template is combined with the SOAP response to create the GROUP_OUT. This parameter is optional.

Fully qualified URLs are dereferenced using Auth-Map context group data. The Auth-Map is searched for a username and password based on the domain name found in the fully qualified URL. For example, if the fully qualified URL is:

http://machine.com/infoengine/servlet/IE/tasks/createGroupData.xml

the Auth-Map context group is searched for a username and password that has an INSTANCE name of http://machine.com. If a username and password are found, BASIC authentication information is used when accessing the URL. If no username and password are found, no authentication information is sent to the remote web server.

If the data value contains the :// string, it is assumed to be a fully qualified internet URL. If the data value does not contain the string, it is assumed to be a local file relative to the current task root directory.

XSL_URL

The location of the XSL template used to generate the SOAP request. The XSL template is combined with the GROUP_IN to generate the SOAP request.

When authoring the XSL documents used to translate the SOAP request and response, if the example request and response pair for the XML documents are available they can be used as templates for the XSL. If there are no such example request and response documents available, then the XSL author needs to pay close attention to the schema provided by the web service’s WSDL document. Complying with the WSDL document is necessary to provide valid and acceptable XML to the web service. Depending on how the service is implemented, it might or might not be flexible in terms of what it accepts. However, the schema provided in the WSDL should be taken literally and be used to craft XML that validates against that schema by complying with the order, case, optionality, cardinality, and data type for all XML elements and attributes.

Fully qualified URLs are de-referenced using Auth-Map context group data. The Auth-Map is searched for a username and password based on the domain name found in the fully qualified URL. For example, if the fully qualified URL is:

http://machine.com/infoengine/servlet/IE/tasks/createGroupData.xml

This parameter is required.

EXAMPLE: TRANSLATE-GROUP AND XSL

Info*Engine SOAP comments are used in the example code for clarity. For more information on SOAP and SOAP comments, see SOAP Services.

This example uses the Translate-Group webject and XSL to simplify a SOAP response that was returned from the Call-SOAPService webject as a complex Info*Engine group.

hostlookup.xml

<%@page language="java" import="java.util.StringTokenizer,com.infoengine.
object.
            IeMultipartInputStream,java.io.ByteArrayInputStream"%>
<%@taglib uri="http://www.ptc.com/infoengine/taglib/core"
                                                     prefix="ie"%>



<ie:webject name="Create-Group" type="GRP">
  <ie:param name="ELEMENT" data="host=$(@FORM[]host[])"
                           default="www.google.com"/>
  <ie:param name="CLASS" data="parameters"/>
  <ie:param name="GROUP_OUT" data="parameters"/>
</ie:webject>

<ie:webject name="Call-SOAPService" type="MSG">
  <ie:param name="ENDPOINT"
     data="http://www.esynaps.com/webservices/YourHostInfo.asmx"/>
  <ie:param name="SOAP_ACTION"
            data="http://tempuri.org/GetHostInfoByName"/>
  <ie:param name="XSL_URL"
          data="/com/company/hostlookup/ hostlookupRequest.xsl"/>
  <ie:param name="GROUP_IN" data="parameters"/>
  <ie:param name="GROUP_OUT" data="response"/>
  <ie:param name="CLASS" data="response"/>
</ie:webject>

<ie:webject name="Translate-Group" type="GRP">
  <ie:param name="GROUP_IN" data="response"/>
  <ie:param name="XSL_URL"
         data="/com/company/hostlookup/
                                         hostlookupResponse.xsl"/>
  <ie:param name="GROUP_OUT" data="$(@FORM[]group_out[])"
                             default="output"/>
  <ie:param name="CLASS" data="lookupResponse"/>
</ie:webject>

hostlookupRequest.xsl

<?xml version='1.0'?>
<xsl:stylesheet
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"
  xmlns:wc="http://www.ptc.com/infoengine/1.0">

<xsl:template match="/wc:COLLECTION/parameters/wc:INSTANCE">
<soap:Envelope xmlns:s0="http://tempuri.org/"
  xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:xs="http://www.w3.org/2001/XMLSchema">
    <soap:Body>
      <s0:GetHostInfoByName>
        <s0:Name><xsl:value-of select="host"/></s0:Name>
      </s0:GetHostInfoByName>
    </soap:Body>
</soap:Envelope>
</xsl:template>
</xsl:stylesheet>

hostlookupResponse.xsl

<?xml version='1.0'?>
<xsl:stylesheet
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"

  xmlns:wc="http://www.ptc.com/infoengine/1.0">
<xsl:template match="/wc:COLLECTION/response/wc:INSTANCE">
<wc:COLLECTION xmlns:wc="http://www.ptc.com/infoengine/1.0">
<lookupResponse TYPE="Object" STATUS="0">
  <wc:INSTANCE>
    <xsl:for-each select="Aliases/wc:INSTANCE/Alias">
    <Alias><xsl:value-of select="current()"/></Alias>
    </xsl:for-each>
    <Name><xsl:value-of select="Name"/></Name>
    <xsl:for-each select="IPList/wc:INSTANCE/IPAddress">
    <IPAddress><xsl:value-of select="current()"/></IPAddress>
    </xsl:for-each>
  </wc:INSTANCE>
</lookupResponse>
</wc:COLLECTION>
</xsl:template>
</xsl:stylesheet>

EXAMPLE: XSL_RESPONSE_URL

This example uses the XSL_RESPONSE_URL parameter to translate the SOAP response into a group identical to that produced by the previous example:

hostlookup2.xml

<%@page language="java"           import="java.util.StringTokenizer,com.
infoengine.object.
            IeMultipartInputStream,java.io.ByteArrayInputStream"%>
<%@taglib uri="http://www.ptc.com/infoengine/taglib/core"
                                                     prefix="ie"%>



<ie:webject name="Create-Group" type="GRP">
  <ie:param name="ELEMENT" data="host=$(@FORM[]host[])"
                           default="www.google.com"/>
  <ie:param name="CLASS" data="parameters"/>
  <ie:param name="GROUP_OUT" data="parameters"/>
</ie:webject>

<ie:webject name="Call-SOAPService" type="MSG">
  <ie:param name="ENDPOINT"
     data="http://www.esynaps.com/webservices/YourHostInfo.asmx"/>
  <ie:param name="SOAP_ACTION"
            data="http://tempuri.org/GetHostInfoByName"/>
  <ie:param name="XSL_URL"
          data="/soap/document/hostlookup/hostlookupRequest.xsl"/>
  <ie:param name="XSL_RESPONSE_URL"
     data="/soap/document/hostlookup/hostlookupResponseSOAP.xsl"/>
  <ie:param name="GROUP_IN" data="parameters"/>
  <ie:param name="GROUP_OUT" data="output"/>
  <ie:param name="CLASS" data="output"/>
</ie:webject>

hostlookupResponseSOAP.xsl

<?xml version='1.0'?>
<xsl:stylesheet
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"
  xmlns:wc="http://www.ptc.com/infoengine/1.0"
  xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:dflt="http://tempuri.org/">



<xsl:template match="/soap:Envelope/soap:Body/
     dflt:GetHostInfoByNameResponse/dflt:GetHostInfoByNameResult">
<wc:COLLECTION xmlns:wc="http://www.ptc.com/infoengine/1.0">
  <output TYPE="Object" STATUS="0">
    <wc:INSTANCE>
      <Name><xsl:value-of select="dflt:Name"/></Name>
      <xsl:for-each select="dflt:Aliases/dflt:Alias">
      <Alias><xsl:value-of select="current()"/></Alias>
      </xsl:for-each>
      <xsl:for-each select="dflt:IPList/dflt:IPAddress">
      <IPAddress><xsl:value-of select="current()"/></IPAddress>
      </xsl:for-each>
    </wc:INSTANCE>
  </output>
</wc:COLLECTION>
</xsl:template>
</xsl:stylesheet>