Connectivity¶
This section describes developing application logic within the Connectivity framework service.
To understand the concepts used within Connectivity please see the Foundation1 Overview. Additionally to understand the required configuration of Connectivity in IFS Solution Manager, then please see the Administration and Configuration guide
The Connectivity_SYS package should be used for all Connectivity related development. Connectivity_SYS provides methods for posting messages in the Out Message Box, fetching messages from the In Message Box and registering application methods for receiving messages.
Sending Message¶
Sending a message includes creating the message header and message lines, and releasing the message for transfer.
Creating Message Header¶
The Message Header contains meta data which is required when processing the message. Below is the list of attributes which should be passed in an attribute string to the procedure Connectivity_SYS.Create_Message
when creating Message Headers.
- message_id NUMBER (optional - if the attribute is missing a new message id is generated). If the application needs to know the message id beforehand it can call the method
Get_Next_Out_Message_Id
and use the returned value in the attribute string toCreate_Message
. - class_id VARCHAR2(30) (message name/type - mandatory). Class id identifies the message type, it's structure and content. The class id must be registered in MessageClass.
- sender VARCHAR2(255) (optional). If no value is present then the value for the database global name returned by
General_SYS.Get_Database_Properties
is used. - exec_time DATE (optional). This is not currently used.
- application_message_id VARCHAR2(255) (optional). This can be used by the sending application to put an identifier in the message that can associate the message with an object in the sending application.
- application_receiver_id VARCHAR2(255) (optional). This can be used by the sending application to put an identifier in the message that can associate the message with a receiver identifier.
- version VARCHAR2(255) (optional). This is used by the application to make a distinction between different versions of messages which belong to a particular Message Class.
- receiver VARCHAR2(255) (mandatory). The receiver must be registered in MessageReceiver.
- format_code VARCHAR2(255) (optional). This is not currently used.
- media_code VARCHAR2(255) (optional). This can be used to classify message for the transporter system. If any transfer is done with the assistance of any integration software outside the database, then the program can fetch messages belonging to a particular media code. If the transport is done with dynamic SQL (within the same database or between linked databases) then media code is not used. The media code must be registered in MessageMedia
Creating Message Lines¶
Message lines have attributes containing the actual message. All the attributes should be passed in an attribute string to the procedure Connectivity_SYS.Create_Message_Line
.
- message_id NUMBER (mandatory).
- message_line NUMBER (mandatory). This attribute is used for sorting the message lines when delivered from the In Message Box to a receiving application.
- name VARCHAR2(255) (mandatory). This attribute is used by the receiver to identify the message line .
- c00 - c99 VARCHAR2(2000) (optional)
- n00 - n99 NUMBER (optional)
- d00 - d39 DATE (optional)
The attributes c00 - c99, n00 - n99 and d00 - d39 hold character, number and time data respectively. The sender and the receiver should agree in advance on the structure of any message.
Releasing for Transfer¶
Newly created messages are in a state of 'Posted' in the Outbox until they are released. Connectivity_SYS.Release_Message
procedure releases a message that it is available for transfer. For a message to be transferred by Connectivity the MessageClass it should have the property 'Send' set to ON/TRUE.
Receiving Message¶
When an application is able to receive messages, the method for receiving messages of a certain message class has to be registered in MessageClass. The message class attribute 'Receive' has to be set to ON/TRUE and the name of the receiving method must be registered in the attribute 'Action'.
When a new message arrives in the In Message Box then the Connectivity process checks the incoming messages to see if the message class which the message belongs to has it's attribute 'Receive set' to ON. If this is the case then the registered method is invoked with the message id used as an argument to handle the message.
The registered method uses public methods in Connectivity_SYS and the view IN_MESSAGE_LINE_PUB
to process the message in the In Message Box.
The method Connectivity_SYS.Get_Message
is used to fetch the message header. The message header is returned as an attribute string.
Attributes returned in the attribute string are:
- message_id NUMBER (message id in the receiving system)
- class_id VARCHAR2(30)
- receiver VARCHAR2(255)
- sender VARCHAR2(255)
- application_message_id VARCHAR2(255)
- received_time DATE
- version VARCHAR2(255). This is used by the application to make a distinction between different versions of messages belonging to a particular Message Class.
- sender_id VARCHAR2(255) (message id in the sending system)
- transferred_time DATE
- error_message VARCHAR2(255)
IN_MESSAGE_LINE_PUB
view should be used to query message lines.
Fields in IN_MESSAGE_LINE_PUB
:
- message_id NUMBER
- message_line NUMBER
- name VARCHAR2(255)
- c00 - c99 VARCHAR2(2000)
- n00 - n99 NUMBER
- d00 - d39 DATE
After successfully processing the message the method Connectivity_SYS.Accept_Message
is used to confirm that the message is processed. If an error has occurred then the method Connectivity_SYS.Reject_Message
is used to place the message in 'State Rejected'.
It is also possible to process each message line and set the message line to state whether it has been 'Accepted' or 'Rejected' using Connectivity_SYS.Accept_Message_Line
or Connectivity_SYS.Reject_Message_Line
. After processing the complete message, the message state is set with Connectivity_SYS.Set_In_Message_State
. The message will enter state 'PartlyAccepted' if the message contains some message lines which have been 'Accepted' with one or more message lines 'Rejected'.. A message in state 'PartlyAccepted' can be reprocessed at a later time and the lines in state 'Rejected' can be reprocessed.
Registering a Message Class¶
A message must belong to a Message Class. The method Connectivity_SYS.Create_Message_Class
can be used to register message classes.
The message class will have the attributes Send and Receive set to OFF/FALSE.
The method Connectivity_SYS.Register_Action
is used to register a method for receiving messages belonging to the message class. But if the action is already set in the call to Connectivity_SYS.Create_Message_Class
this is not needed.
These methods are intended to be used in installation scripts.