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
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.
- A Connect Reader receives the message, calls the Message
Processor and
waits for a response from the queue system.
- The Message Processor calls Message Router to determine which BizAPI or PL/SQL method to invoke and if any transformer
should be applied.
- The Message Router resolves also all optional destination addresses and
the queue name.
- 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.
- 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.
- The message will be transformed to IFS XML format if any transformer is
to be applied.
- 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
.
- 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.
- A Connect Reader receives the message, calls the Message
Processor and
waits for a response.
- The Message Processor calls Message Router to determine which BizAPI or PL/SQL method to invoke and if any
transformers should be applied.
- The Message Router resolves all optional destination addresses.
- The Message Processor executes the destination addresses and waits for a
response.
- The message will be transformed to IFS XML format if any transformer is
to be applied.
- The called BizAPI (if used) calls the actual business logic stored procedure and
returns the response.
- If several links in destination
address chain are defined, the response
will be passed through all links before sending back to the caller.
- 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.
- 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.
- 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.
- 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.
- The output message will be transformed from IFS XML to any format if a
transformer is about to be applied.
- The message will be embedded into a SOAP envelope if necessary.
- 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.
- 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).
Implementation based on HTTP
- 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.
- SOAP Gateway invokes Message Processor that in turn calls corresponding outbound BizAPI.
- 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.
- The Message Processor executes the destination address(es) and waits for
the
response.
- The message will be transformed, if necessary.
- The message will be embedded into an envelope, if necessary.
- 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.
- 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.
Read more about
Invoking Messages.
- 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.
- 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.
- After the message has been created, the stored procedure will wait for
an AQ JMS message on a dedicated Response AQ JMS queue.
- 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.
- 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.
- The Message Processor executes the destination address(es) and waits for
response.
- The message will be transformed, if necessary.
- The message will be embedded into an envelope, if necessary.
- The Connect Sender sends the message to the destination using its
native protocol. Typically HTTP or REST.
- 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.
- The response Message Body is added to the Application Message
and saved.
- Message Processor is posting a response JMS message on the
Response AQ JMS queue.
- 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.
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.