SOAP Integrations with IFS

SOAP stands strongly in the market even two decades and alongside with other modern integration protocols. Even today it’s the go-to messaging protocol for many enterprise integrations and companies frequently use SOAP for their web services. It’s no exception for IFS Applications and IFS provides wide range of web services both inbound and outbound.

In this blog post, I’m trying to explain some concepts and terminology behind SOAP integrations with IFS. Main topics will be discussed here are

1. BizAPIs and IFS SOAP Gateway
2. Synchronous/Asynchronous Messaging
3. SOAP Message Routing in IFS
4. Integration Example with Postman

Hope you will enjoy and learn something new!

1. BizAPIs and IFS SOAP Gateway

1.1 What is a BizAPI…?

BizAPI is the IFS terminology for an operation within a service handler (web service). Basically, BizAPI is the unit which you shall call via integration to get the work done.

1.2 IFS SOAP Gateway

SOAP Gateway is the web integration entry point in IFS Applications. Its purpose is to listens to HTTP requests and dispatches them to business logic for processing.

Listening URL for SOAP Gateway has changed in IFS application versions and it follows the format below.

• Apps10 and IFS Cloud – https://<SERVER&gt;:<PORT>/int/soapgateway
• Apps9 and below – http(s)://<SERVER>:<PORT>/fndext/soapgateway

Best thing about SOAP Gateway is that the message doesn’t have to be SOAP format. Yes, it sounds confusing but it actually accepts any XML document which is properly authorized. In IFS Cloud version it seems you can also send a JSON document to SOAP Gateway also but I have still not tried it. It may be a good topic for another blog post 🙂

1.3 Interface Browser

From Apps9 onwards, all the Web Services and BizApis deployed in the IFS instance can be viewed by locating the interface browser which can be reached via

http(s)://<SERVER>:<PORT>/interfacebrowser

Interface Browser provides technical interface specifications of service APIs exposed in IFS. Greatest challenge service integrators face is to find the correct web service or BizApis for the need and mostly you’ll need an IFS expert to help with that. Once you find the list of BizApis, finding other information is not that hard and doesn’t require much IFS knowledge to proceed.

List of web services are different depending on the installed components in your IFS instance. Once you select the web service from the list, details page gives more information about the WSDL and different implementations.

Application Server WS tab carries information about the JAX-WS implementation of the web service operations and IFS Connect WS tab provides more information relates to SOAP protocol.

1.4 BizApi Types

There are four BizApi types in IFS

• Inbound (asynchronous)
• Inbound Request (synchronous)
• Outbound (asynchronous)
• Outbound Request (synchronous)

Outbound BizApis are used to send data from IFS to other systems and it won’t be discussed further in this post, but if you’d like to know more about outbound integrations please leave a comment so I will work on that.

You can find what type of the BizApi you are dealing with in the interface browser. Go to the IFS Connect WS tab and there you can find small icon describing the type of the BizApi.

2. Synchronous/Asynchronous, What’s the difference?

For me, IFS classification of Inbound and Inbound synchronous is confusing and how I interpret is as a recommendation to implement the integration. From the above example, GetCustomers must be synchronous since the requester expects a return value. But with CreateCustomers, one can expect an answer or not, therefore it can be implement as synchronous or asynchronous according to the requirement.

Also note that a synchronous request waits until the response is received. If you are calling a BizApi which has heavy logic to process, it could overload the middleware server or request can timeouts. Usually performance degrading happens over the time so it’s important to choose wisely at the design phase rather than dealing with problems later.

2.1 Inbound Synchronous

A message can processed synchronously using two ways.

• Using SOAPAction HTTP header

When a SOAP message includes SOAPAction http header in the format of urn:soap_access_provider:<BizAPI_Name> it will skip message routing and call the BizApi directly. With this method, you can’t use IFS transformers to transform the message content, therefore the message content should match the BizApi schema.

• Using message routing without queuing

When the IFS SOAP gateway receives a message without SOAPAction http header, it will be directed to message router. A matching inbound routing rule which

• route from SOAP_SIMPLE or SOAP_IFS or any other SOAP formats defined in IFS Connect
• with destination address BizApi
• Queue = None

should be defined to process the incoming message synchronously. With this method, request and response transformers can be defined in the routing address.

Note that the synchronous messaging does not save as a Application message in IFS, therefore tracing the message should be handled in the requester. However in Apps10, it’s possible to save the synchronous messages using a J2EE property ifs.persistSynchronousMessages.

2.2 Inbound Asynchronous

In order to process a inbound SOAP request asynchronously, a matching inbound routing rule with

• route from SOAP_SIMPLE or SOAP_IFS or any other SOAP formats defined in IFS Connect
• with destination address BizApi
• Queue = One of the message queues

should be defined to process the incoming message asynchronously. With this method, request and response transformers can be defined in the routing address.

3. SOAP Message Routing in IFS

A SOAP message contains following elements [1]

• Envelope – Defines the start and the end of the message. It is a mandatory element.
• Header − Contains any optional attributes of the message used in processing the message, either at an intermediary point or at the ultimate end-point. It is an optional element.
• Body − Contains the XML data comprising the message being sent. It is a mandatory element.
• Fault − An optional Fault element that provides information about errors that occur while processing the message.

We can use header attributes or any other attribute in the body to route the message to its destination.

3.1 Message Routing with SOAP Header

In order to route message based on headers, you need to use IFS defined format called SOAP_IFS or define a custom envelope if you already have a defined SOAP message format.

Read more about SOAP_IFS

In order to route messages with SOAP_IFS format, you need to define an Inbound routing rule with Route From as SOAP_IFS. Then IFS specific SOAP header attributes will be listed under the content based conditions.

You can also define your own SOAP envelope and use it for routing. There you can define own header element and map to IFS specific attributes.

More about custom envelopes

3.2 Message Routing with SOAP Body

Other way to route the message is using one or more XML tag/attributes in the payload (body). In order to do this, create a Inbound routing rule as above and use Route from as SOAP_SIMPLE. Under the Content based condition, use any XML tag which can be used to uniquely identify the message. If you wish to search by attribute name, it should be preceded with “@”. It can be specified alone or after tag name. It is also possible to specify nested tags using slashes (“/”) as level separators. To work with a same search name (XML tag name) more than once in a same content based routing rule, you should specify the search condition using nested tags.

You can combine several conditions in order to create a unique condition.

4. Testing SOAP Integrations with Postman

In this example we will create an integration setup in IFS to receive supplier invoice though SOAP gateway as XML.

First, we need to find the correct BizAPI we need to invoke. Open Interface Browser and in the BizApi tab, search for keyword supplier. This will list related BizApis. What we are interested here is RECEIVE_SUPPLIER_INFO. By clicking on the BizApi would show more information such as IN/OUT document formats and web service information.

• Download the sample input XML and save to be used in the next steps.
• Open Postman (or install it from https://www.postman.com/downloads/)
• Create a new HTTP request. Change the HTTP verb to POST
• put the SOAP Gateway url in the URL field.
• In the Authorization tab, select Type as Basic Auth, enter user id/password which has FND_CONNECT permission set granted

In the Body tab, select raw XML. Construct SOAP message from sample XML we downloaded above by putting the content inside <soap:Body>

Eg:

<?xml version="1.0"?>
<soap:Envelope
xmlns:soap="http://www.w3.org/2003/05/soap-envelope/"
soap:encodingStyle="http://www.w3.org/2003/05/soap-encoding">
    <soap:Body>
        <INVOICE xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:ifsworld-com:schemas:inbound_distribution_transactions_receive_supplier_invoice_request">
            <CURRENCY_CODE>ABC</CURRENCY_CODE>
            <CUSTOMER_COMMUNICATION_ID>ABC</CUSTOMER_COMMUNICATION_ID>
            <CUSTOMER_NAME>ABC</CUSTOMER_NAME>
            <CUSTOMER_NO>ABC</CUSTOMER_NO>
            ...
            ...
        </INVOICE>
    </soap:Body>
</soap:Envelope>

4.1 Synchronous using SOAPAction HTTP header

To make a Synchronous request, go to the Headers tab and add a new header named SOAPAction and value as urn:soap_access_provider:RECEIVE_SUPPLIER_INVOICE

Invoke the request to see the results. With the sample message, you should get a soap fault with error details like below.

4.2 Asynchronous using SOAPAction HTTP header

You can send the message asynchronously by just using the SOAPAction header by using the /post suffix (Eg: SOAPAction = urn:soap_access_provider:RECEIVE_SUPPLIER_INVOICE/post)

Then the application message will be posted to the DEFAULT queue for processing

4.3 Synchronous using routing rules

• Go to Routing Addresses, Create New
• Select Destination Address = BizAPI and in the BIZAPI Address field, select the correct BizAPI. Save the routing address.

• Go to Routing Rules, In the Inbound tab, press Create New.
• Set Route from as SOAP_SIMPLE, Queue as None
• In the Content based conditions, here we search for INVOICE tag in the XML
• Click in the Destination Address link and select the routing address we created in above step, Save

• Go to the Postman request, delete the SOAPAction header we added in previous attempt.

4.4 Asynchronous using routing rules

To process messages asynchronously using asynchronously, simply add a queue in the routing address

Using Postman, send a request without any SOAPAction Header. received response indicate that the request is posted to the queue which we mentioned in the routing rule.

Hope you find this useful. Share the post and comments your thoughts/questions, always happy to help!

References

[1] – https://www.tutorialspoint.com/soap/soap_message_structure.htm