Skip to content

Sample App Connect Enterprise Application

Audience: Architects, Application developers, Administrators

Timing: 20 minutes

Overview

The sample ACE application that we will build in this tutorial will integrate with an existing backend SOAP service and expose it as a RESTful Web Service.

In this section, we are going to:

  • Review the backend SOAP service.
  • Review the sample ACE application that integrates with the backend SOAP service.

The SOAP backend service

The SOAP backend takes payload to create Customer Details. It responses with:

  • status indicating whether the request was successful.

  • customer_id identification number assigned to the customer record.

SOAP Service

Backend SOAP Service

Note

This sample service does not persist customer details data. It simply returns the status and a customer ID.

The XSD for all the data models can be found here: customer_details.xsd. The (generated) WSDL can be found here: customerDetails.wsdl. As specified in the data model, there are two validations active:

  1. Payload must contain a service_header.

  2. Customer phone number must comply with regex [0-9]{3}-[0-9]{7}.

An example payload can look like:

<SOAP-ENV:Envelope xmlns:SOAP-ENV='http://schemas.xmlsoap.org/soap/envelope/'>
  <SOAP-ENV:Body>
    <cus:customerDetailsRequest xmlns:cus='http://ibm.com/CustomerDetails/'>
      <cus:customer_details>
        <cus:service_header>
          <cus:brand>IBM</cus:brand>
        </cus:service_header>
        <cus:personal_details>
          <cus:name_details>
            <cus:first_name>John</cus:first_name>
            <cus:last_name>Doe</cus:last_name>
          </cus:name_details>
          <cus:contact_details>
            <cus:phone>555-5555555</cus:phone>
            <cus:address>123 Main Street</cus:address>
          </cus:contact_details>
        </cus:personal_details>
      </cus:customer_details>
    </cus:customerDetailsRequest>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

And the SOAP server will respond with, for example:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Header/>
   <SOAP-ENV:Body>
      <ns2:customerDetailsResponse xmlns:ns2="http://ibm.com/CustomerDetails/">
         <ns2:status>success</ns2:status>
         <ns2:customer_id>55ed3857-0f19-4250-a36f-de42f2db96b2</ns2:customer_id>
      </ns2:customerDetailsResponse>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

As for validation, without service_header, response would be:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Header/>
   <SOAP-ENV:Body>
      <SOAP-ENV:Fault>
         <faultcode>SOAP-ENV:Client</faultcode>
         <faultstring xml:lang="en">Validation error</faultstring>
         <detail>
            <spring-ws:ValidationError xmlns:spring-ws="http://springframework.org/spring-ws">cvc-complex-type.2.4.a: Invalid content was found starting with element 'cus:personal_details'. One of '{"http://ibm.com/CustomerDetails/":service_header}' is expected.</spring-ws:ValidationError>
         </detail>
      </SOAP-ENV:Fault>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

and without properly formatted phone number, the response would be:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Header/>
   <SOAP-ENV:Body>
      <SOAP-ENV:Fault>
         <faultcode>SOAP-ENV:Client</faultcode>
         <faultstring xml:lang="en">Validation error</faultstring>
         <detail>
            <spring-ws:ValidationError xmlns:spring-ws="http://springframework.org/spring-ws">cvc-pattern-valid: Value '555-555' is not facet-valid with respect to pattern '[0-9]{3}-[0-9]{7}' for type '#AnonType_phonecontact_detailspersonal_detailscustomer_details'.</spring-ws:ValidationError>
            <spring-ws:ValidationError xmlns:spring-ws="http://springframework.org/spring-ws">cvc-type.3.1.3: The value '555-555' of element 'cus:phone' is not valid.</spring-ws:ValidationError>
         </detail>
      </SOAP-ENV:Fault>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Following is a video walk through of the SOAP service in action:

ACE application

With App Connect Enterprise, we create a REST message flow that integrates with the backend SOAP service. The flow takes a JSON payload, converts the payload to SOAP envelop, invokes the backend SOAP service, converts the SOAP response to JSON and returns to the client.

ACE REST Service

ACE REST Service

Source code of the message flow can be found here: create-customer.

Data models for the RESTful API can be found here: openapi.json.

Following is the subflow that defines our transformation and integrates with the SOAP service:

ACE flow

ACE subflow

JSONtoSOAP is a mapping node that maps the JSON payload to to a SOAP Envelop. The left hand side takes customer_details as defined in the data model (see customer_details in OpenAPI) and the right hand side takes customerDetailsRequest (see customerDetailsRequest) as defined by the WSDL of the SOAP service.

toJSONHappy

JSON to SOAP mapping

Set up destination is a custom Java Node that reads the URL of the backend SOAP service from a user-defined policy. This way, the URL of the SOAP service is not hard-coded in the flow. Instead, the URL is fed into the flow from a configuration at deployment time. URL is then fed into the SOAP Request node. An example of this policy can be found here: backendurl.policyxml.

SOAP Request makes the call to the SOAP backend service, using the Payload from the JSONtoSOAP node and URL from Set up destination. From henceforth, there are two paths, a "happy" path where request is successful and an "unhappy" path where the request was not successful.

SOAP Extract, SOAP Extract Fault extract out the SOAP envelop from the response of the SOAP Request node.

HTTP Header, HTTP Header Fault set the header for the responses. When request is successful it sets the response to 200, 400 otherwise.

ToJSON, fault_mapping are mapping nodes that map the SOAP messages to JSON. For the successful path, the left hand side takes takes customerDetailsResponse (see customerDetailsResponse) as defined by the WSDL of the SOAP service and the right hand side takes customer_details_response as defined in the data model (see customer_details_response in OpenAPI) and the right hand side:

toJSONHappy

Mapping for successful call

For the un-successful path, the left hand side takes takes SOAP Fault (see SOAP fault) and the right hand side takes fault as defined in the data model (see [fault][json] in OpenAPI).

toJSONHappy

Mapping for faulty call

Following is a video walk through of the ACE application:

Congratulations!

You have now an understanding of the backend service that will be used by our ACE flow.

This section of the tutorial is now complete. In the following section, we are going to use deploy the backend service using ArgoCD.

Back to top