BizAPI

BizAPIs are units of application logic providing business data and services to other applications.
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.

Note: Simplified a BizAPI is just an alias for an operation within a handler (web service). While the BizAPI defines the mentioned additional characteristics (direction, type), in many places when we're talking about BizAPI it is also possible to use operations not being defined as BizAPIs.

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: It is also possible to directly define PL/SQL method for inbound flows without using any BizAPI.

• Outbound : A BizAPI that handles outgoing messages from IFS Applications.
  These messages are sent from PL/SQL using the PLSQL Access Provider.

  
  Typically the PL/SQL business logic will create a message containing only key values and the BizAPI Java implementation gets and adds the rest of the information. 
  The complete message can be created directly in PL/SQL but this may lead to performance problems for large messages when using the old, deprecated, PLSQLAP_Record_API. Alternatively the message can be created in PL/SQL as an XML document or using the new, PLSQLAP_Document_API. (There is also a simplified way for sending 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 normally don't use message queues (see also Persisting of Synchronous Messages).
• 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 background execution.

These combinations define four different categories.

Note: The four flows presented below are just typical usage examples. Message Routing is a very powerful mechanism and allows creation of other types of scenarios as well, e.g. combinations of inbound and outbound flows, address chaining, etc.

Message flow for an Inbound BizAPI

1. A Connect Reader receives the message, calls the Message Processor and waits for a response from the queue system.
2. The Message Processor calls Message Router to determine which BizAPI or PL/SQL method 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 Processor 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. If defined, the Connect Reader can create a new message (outbound) containing the receipt that can be routed separately to an arbitrary destination.
5. The Batch Processor receives a JMS message about the message being inserted to the queue, picks up the message and calls Message Processor that 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 (if used) calls the actual business logic stored procedure and sends the response back to the Message Processor. If response is ok, the message state is changed to FINISHED, otherwise to FAILED.
8. If second link in destination address chain is defined (Response Address), the response will be transformed (if any transformer is defined), put into a SOAP envelope (if defined) and sent to the defined destination.

Message flow for an Inbound Request BizAPI

1. A Connect Reader receives the message, calls the Message Processor and waits for a response.
2. The Message Processor calls Message Router to determine which BizAPI or PL/SQL method to invoke and if any transformers should be applied.
3. The Message Router resolves all optional destination addresses.
4. The Message Processor 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 (if used) calls the actual business logic stored procedure and returns the response.
7. If several links in destination address chain are defined, the response will be passed through all links before sending back to the caller.
8. The Connect Reader receives the response from the main address in the last address chain link.

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 document/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 phase performed by the PL/SQL Access Provider. If the queue name cannot be resolved and due to many rules that may satisfy the message, it will be posted to the UNROUTED queue. If there are no routing rules that may satisfy the message, it will be poster to the ERROR queue and the message state will be set to FAILED.

   Note: Failure to find a queue for an in-order message will throw an exception rather then putting the message to the ERROR queue.

2. The Batch Processor receives a JMS message about the created application message, picks up it and invokes the outbound BizAPI by calling Message Processor. Typically the message 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 Processor is calling the Message Router to resolve destination addresses based on contents of the in and out data to and from the BizAPI and also content of the application message created by the PL/SQL Access Provider.
4. The output 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 Connect Sender sends the message to the destination using its native protocol. If response is OK, message state is changed to FINISHED, otherwise FAILED. Some senders are designed to resend the message in case of failure.
7. If second link in destination address chain is defined (Response Address), the response will be transformed (if any transformer is defined), put into a SOAP envelope (if defined) and sent to the defined destination, for example another BizAPI (inbound).

Message flow for an Outbound Request BizAPI

Implementation based on HTTP

1. The document/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 Message Processor that in turn calls corresponding outbound BizAPI.
3. Message Processor calls the Message Router, which determines the Connect Sender(s) to run and if any transformers and/or envelope(s) should be applied.
4. The Message Processor executes the destination address(es) and waits for the response.
5. The message will be transformed, if necessary.
6. The message will be embedded into an envelope, if necessary.
7. The Connect 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 Connect Sender used in this scenario.
8. If several links in destination address chain are defined, the response will be passed through all links before sending back to the caller. The received response will be then the response from the main address in the last address chain link.

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

Implementation based on Oracle AQ

Read more about Invoking Messages.

1. The document/record is created using the PL/SQL Access Provider and the Invoke_Outbound_Request_BizAPI stored procedure of the PL/SQL Access Provider is invoked, which then waits for the response.
2. The Invoke_Outbound_Request_BizAPI stored procedure creates an Application Message, which is tagged as synchronous message. The message is posted to the DEFAULT queue.
3. After the message has been created, the stored procedure will wait for an AQ JMS message on a dedicated Response AQ JMS queue.
4. The Batch Processor receives a JMS message about the created application message, picks up it and calls Message Processor, which, in turn, calls corresponding outbound BizAPI.
5. After BizAPI execution the Message Processor will call the Message Router to resolve destination addresses based on contents of the in and out data to and from the BizAPI and also content of the application message created by the PL/SQL Access Provider.
6. The Message Processor executes the destination address(es) and waits for response.
7. The message will be transformed, if necessary.
8. The message will be embedded into an envelope, if necessary.
9. The Connect Sender sends the message to the destination using its native protocol. Typically HTTP or REST.
10. If several links in destination address chain are defined, the response will be passed through all links before sending back to the caller. The received response will be then the response from the main address in the last address chain link.
11. The response Message Body is added to the Application Message and saved.
12. Message Processor is posting a response JMS message on the Response AQ JMS queue.
13. The stored procedure in PL/SQL Access Provider receives the response JMS message and retrieves the response Message Body, which is returned to the caller.

Persisting of Synchronous Messages

A synchronous Application 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 (or main addresses in an address chain), the entire message is marked as failed and the caller is notified about that. If the main address(es) 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 permanently 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 normally 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.

Furthermore the new implementation of message invocation in PLSQL Access Provider will also cause all synchronous outbound 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.