Foundation1 / Overview / Integration / Connect / Bizapi / This page

BizAPI

BizAPIs are grouped by a combination of characteristics. The characteristic categories are the Message Direction and the Protocol Type. This page aims to sort out the differences between the different types of BizAPIs that exists in the set of valid combinations. 

Contents

• BizAPI categories
• Message flow for an Inbound BizAPI
• Message flow for an Inbound Request BizAPI
• Message flow for an Outbound BizAPI
• Message flow for an Outbound Request BizAPI
• Persisting of Synchronous Messages

BizAPI categories

 The first part of the BizAPI category is the message direction:

• Inbound : A BizAPI that handles incoming messages being sent to IFS Applications.
  This BizAPI type is implemented in Java using the middle tier Java Server Framework Note: This is only available on sites with an IFS Development License.
• Outbound : A BizAPI that handles outgoing messages from IFS Applications.
  These messages are sent from PL/SQL using the PLSQL Access Provider. Note: This is only available on sites with an IFS Development License.

  
  A message containing only key values should be created using PL/SQL and the BizAPI Java implementation should get and add the rest of the information. 
  The complete message can be created in PL/SQL but this may lead to performance problems when messages are large.
  (There is also a simplified way to send outbound messages without creating a BizAPI.)

The second part of the category indicates whether the BizAPI is of the type request/response.

• Request/response type:  These are messages that have a synchronous response returned and assumes a short-lived transaction. Examples are: CHECK_AVAILABILITY, LIST_PRICES. These messages are always synchronous and don't use message queues.
• Not of the request/response type: These are documents that are submitted to an application or system. They are often part of a long-lived transaction. Examples of this are RECEIVE_CUSTOMER_ORDER, SEND_ORDER_RESPONSE. These messages are always asynchronous and use message queues for batch execution.

These combinations define four different categories.

Message flow for an Inbound BizAPI

1. A connector reader receives the message, calls the Message Router and waits for a response from the queue system.
2. The Message Router determines which BizAPI to invoke and if any transformer should be applied.
3. The Message Router resolves also all optional destination addresses and the queue name.
4. The Message Router posts the message to the queue and sends back a receipt to the connect reader. If it is not possible to resolve the queue name the message is posted to the ERROR queue instead. The message state is then set to FAILED.
5. The Batch Processor receives a JMS message about the message being inserted to the queue, picks up the message and starts execution of the destination addresses.
6. The message will be transformed to IFS XML format if any transformer is to be applied.
7. The invoked BizAPI calls the actual business logic stored procedure and sends the response back to the Batch Processor. If response is ok, the message state is changed to FINISHED, otherwise to FAILED.
8. If an optional response address is defined, the response will be transformed (if any transformer is defined), put into a SOAP enveloped and sent to the defined destination.

Message flow for an Inbound Request BizAPI

1. A connect reader receives the message, calls the Message Router and waits for a response.
2. The Message Router determines which BizAPI to invoke and if any transformers should be applied.
3. The Message Router resolves all optional destination addresses.
4. The Message Router executes the destination addresses and waits for a response.
5. The message will be transformed to IFS XML format if any transformer is to be applied.
6. The called BizAPI calls the actual business logic stored procedure and returns the response back to the calling connect reader.

Note: Normally synchronous messages are not persistent, but there are situation when they can be. Read about persisting of synchronous messages.

Message flow for an Outbound BizAPI

1. The record is created by the PL/SQL Access Provider and is posted to a queue using the Post_Outbound_BizAPI stored procedure. The queue name is resolved during the pre-routing step performed by the PL/SQL Access Provider. If the queue name cannot be resolved, the message is posted to the ERROR queue instead. The message state is then set to FAILED.
2. The Batch Processor receives a JMS message about the created record, picks up the record and invokes the BizAPI. Typically the record contains only key values, thus the BizAPI fetches the additional data from the database using the sent keys and then creates and returns the message.
3. After BizAPI execution the Message Router is called to resolve destination addresses based on contents of the in and out data to and from the BizAPI and also content of the record created by PL/SQL Access Provider.
4. The out message will be transformed from IFS XML to any format if a transformer is about to be applied.
5. The message will be embedded into a SOAP envelope if necessary.
6. The connector sends the message to the destination using its native protocol. If response is OK, message state is changed to FINISHED, otherwise FAILED. Some connectors are designed to resend the message in case of failure.
7. If an optional response address is defined, the response will be transformed (if any transformer is defined) and sent to the defined destination.

Message flow for an Outbound Request BizAPI

1. The record is created using the PL/SQL Access Provider and SOAP Gateway is invoked using the Invoke_Outbound_Request_BizAPI stored procedure of the PL/SQL Access Provider, which then waits for a response.
2. SOAP Gateway invokes Batch Processor that in turn calls corresponding outbound BizAPI.
3. Batch Processor calls the Message Router, which determines the connector sender(s) to run and if any transformers and/or envelope(s) should be applied.
4. The Message Router executes the destination address and waits for a response.
5. The message will be transformed, if necessary.
6. The message will be embedded into an envelope, if necessary.
7. The connector sender sends the message to the destination using its native protocol. The response is returned back to the Invoke_Outbound_Request_BizAPI procedure. Typically HTTP is the connector sender used in this scenario.

Note: Normally synchronous messages are not persistent, but there are situation when they can be. Read about persisting of synchronous messages.

Persisting of Synchronous Messages

A synchronous message is typically defined to have only one destination address. The response from this address execution is sent back to the caller and it can be a success or failure.

But it is possible to define several destination addresses on the used Routing Rule, one of them is then the main address.
If execution of the main address fails, the entire message is marked as failed and the caller is notified about that. If the main address execution is succeeded, the caller will be notified about the success.

But in such situation it is possible that the other addresses will not succeed, but fail temporarily or permanently. Especially on temporary failure the message has to be stored to be possible to re-execute later on. But even if the execution failed it can be necessary to know why.
That's why in such situations synchronous messages are saved to the database and handled in the same way as the asynchronous ones.

A successful synchronous call will not left any tracks in the database, but some customers may wish to follow-up even synchronous messages. Setting an ifs property ifs.persistSynchronousMessages to true will cause all synchronous messages to be saved.

Because the synchronous Routing Rules don't define any queue, synchronous messages will be normally saved to the DEFAULT queue. But on permanent failure messages will be saved to the ERROR queue instead.