JText failure handling
For the JText connector, the following types of errors
can occur:
Table 11. JText error types
Type of error |
Description |
Business object delimiter failures |
Business object delimiter failures occur when
the EndBODelimiter attribute in the top-level meta-object is set to a valid
value, and the event file contains the specified delimiter at the
end of each business object, but the data itself uses the delimiter
value in its text. When the connector encounters the delimiter value
in the text, it sends a partial business object string to the formatter,
which fails processing. In this case, the connector writes the event
to the filename_timestamp.fail file, which contains records for all business objects that
encountered delimiter failures. |
Subscription errors |
Can occur if the connector can find the business
object delimiter and retrieve the business object name, but the
business object is not subscribed. In this case, an event is sent
to the filename_timestamp.unsub file, which contains records for all unsubscribed business
objects. |
Formatting errors |
Can occur if the connector finds the delimiter
with a business object name that does not match the input business
object name, or the format in the business object file does not
match the format of the meta-object. An event is sent to the filename_timestamp.fail file, which contains records for all business objects that failed
formatting. |
Sending errors |
Can occur if the connector tries to send a business
object when the integration broker is down. If the Send operation
fails, an event is sent to the filename_timestamp.fail file, which contains records for all business objects that
were not successfully sent. |
Event log file
The connector logs information about successfully processed
business objects to the event.log file. If the connector goes down before it processes all
business objects in an event file, it uses this log file during recovery
to ensure that it sends each business object only once to the integration
broker.
The format of the log file is:
EventFileName::1,2,n
where EventFileName is the name of the current event file, and each number represents
the sequence number of a successfully processed business object
in that file.
For example, assume that the connector has successfully processed
three of the first four business objects in the Customer.in file, and that the second business object failed processing.
Assume also that the connector has not yet finished processing Customer.in. In this case, the event.log file might look like the following:
Linux:
$ProductDir/JText/Event/Customer.in:: 1,3,4
Windows:
C:\JText\Event\Customer.in:: 1,3,4
i5/OS:
/QIBM/UserData/WebBIICS/JText/Event/Customer.in:: 1,3,4
If the connector went down before processing the entire Customer.in file, at startup the connector uses the information in the
log file to resume processing the event file at the point where
it had stopped processing. The connector reads the log to get the
name of the event file to be recovered and the latest business-object sequence
number. Then the connector begins sending to the integration broker
all business objects in the event file whose sequence number is
greater than the last number in the log file. For example, given
the file above, the connector begins processing the fifth business
object in the Customer.in file.
The connector keeps the contents of the log file in memory to
enhance performance. It accesses the file on disk only to update
it with a new entry. The connector reads the log file only at recovery
time.
For information on how the connector uses the event.log file in the recovery process, see Failure recovery.
Failure recovery
Note:
The following recovery steps do not apply
if a disk failure occurs or a disk is full.
To recover from failures during event notification, the connector
does the following:
- The connector processes business object strings from the event
file. When it successfully processes an entry, the connector logs
the entry in the event.log file. It also writes it to a file in the archive directory (specified
in the ArchiveDir meta-object attribute).
- If none of the business objects in the event file have failed
processing, the connector archives the successfully processed ones
in an archive file with the extension specified in the SuccessArchiveExt attribute.
- If any of the business objects in the event file have failed
processing, the connector archives the successfully processed ones
in an archive file with the extension specified in the PartialArchiveExt attribute.
- After it has written business objects to the file specified
in the SuccessArchiveExt attribute, if any business object fails processing, the connector
changes the extension of this file to the one specified in PartialArchiveExt.
The delivered default values for these extensions are .success and .partial.
- If errors occur, the connector does the following:
- Subscription errors-- the connector creates the archive
file in the archive directory with the extension specified in the UnsubscribedArchiveExt meta-object attribute. The delivered default value for this extension
is .unsub.
- Formatting errors or sending errors--the connector creates
the archive file in the archive directory with the extension specified
in the FailArchiveExt meta-object attribute. The delivered default value for this
extension is .fail.
- Business object delimiter errors--the connector creates
the archive file in the archive directory with the extension specified
in the FailArchiveExt attribute. It also backs up the event file by moving it to the
archive directory and changing its extension to the one specified
in OriginalArchiveExt.
The connector does not log the failed business objects to event.log.
- After the connector processes all business objects in an event
file, it clears the event.log file and begins writing entries to it from the next event
file.
- If the connector goes down before it processes all business
objects in an event file, it uses the information in event.log to determine where to begin processing during the recovery
process. When it comes back up, the connector checks whether there
are any entries in the log file.
- If there are no entries, the connector sends all business objects
in the event file to the integration broker.
- If there are entries, the connector uses this information to
resume processing an event file at the point where it had stopped
processing. The connector reads the log to get the name of the event
file to be recovered and the latest business-object sequence number.
Then the connector sends to the integration broker all business
objects in the event file whose sequence number is greater than
the last number in the log file. For example, if the event file
contains 15 business objects and the last sequence number in the
log file is 8, the connector sends the last seven business objects
to the integration broker.
Using the log file prevents the connector from sending the same
event multiple times to the integration broker. The connector keeps
the log file in memory to enhance performance. The connector accesses
the file on disk only to update it with a new entry, and reads the
log file only at recovery time.
If you set the EventRecovery configuration
property to retry, the connector at startup automatically recovers outstanding
events from a previously processed file. However, if you set this property
to abort, the connector terminates during startup if there are any
events to be recovered.
- To recover from errors that occurred during the event notification
process, you must restart the connector. Before doing this, however,
do the following:
- Examine the files that the connector created for failed and
unsubscribed business objects. Make appropriate corrections so that
the business object strings can be successfully processed when the connector
starts.
- Copy appropriate files from the archive directory to the event
directory and change all .fail or .unsub extensions to the extension specified in the EventExt attribute (by default, .in). To facilitate record-keeping, rename these files in a meaningful
way. For example, rename Customer.unsub to Customer_unsub_resubmit.in.
- You may need to perform additional steps manually to recover,
depending on the type of failure that has occurred.
The following guidelines can help you determine what recovery
steps to take, based on the type of error that occurred.
Recovery from business object
delimiter errors
The connector writes the business object to an archive
file in the archive directory, giving it the extension specified
in the FailArchiveExt meta-object attribute. To handle recovery for such a failure,
do the following:
- Ensure that the event file contains the business object delimiter,
that the delimiter is correct, and that it does not contain the
delimiter value in the data itself as text. If the use of the delimiter
is not correct, correct it.
- Review the connector's log file (specified in the LogFileName configuration
attribute) to determine other reasons why the process failed.
- Copy the file from the archive directory to the event directory
and change the .fail extension to the extension specified in the EventExt attribute (by default, .in). To facilitate record-keeping, rename the file in a meaningful
way. For example, rename Customer.fail to Customer_delimiter_error.in.
Recovery
from subscription errors
The connector writes the business object to a file located
in the archive directory, giving it the extension specified in the UnsubscribedArchiveExt meta-object attribute. To handle recovery for such a failure,
do the following:
- Open the archived file, find that business object string, and
verify that the business object name and verb are subscribed. Make
appropriate corrections if necessary.
- Ensure that the integration broker is running.
- Copy the file from the archive directory to the event directory
and change the .unsub extension to the extension specified in the EventExt attribute (by default, .in). To facilitate record-keeping, rename the file in a meaningful
way. For example, rename Customer.unsub to Customer_unsub_resubmit.in.
Recovery
from formatting errors
The connector writes the business object to a file located
in the archive directory, giving it the extension specified in the FailArchiveExt meta-object attribute. To handle recovery for such a failure,
do the following:
- Open the archived file and verify that:
- The business object string format matches the expected format
in the meta-object. If there is a mismatch, either change the format
type in the meta-object or in the business object string.
- The formatting syntax of the business object string is correct.
If it is incorrect, correct it.
- Copy the file from the archive directory to the event directory
and change the .fail extension to the extension specified in the EventExt attribute (by default, .in). To facilitate record-keeping, rename the file in a meaningful
way. For example, rename Customer.fail to Customer_fail_formatting.in.
Recovery
from sending errors
The connector writes the business object to a file located
in the archive directory, giving it the extension specified in the FailArchiveExt meta-object attribute. To handle recovery for such a failure,
do the following:
- Verify that all components of the business-integration system
are running.
- Copy the file from the archive directory to the event directory
and change the .fail extension to the extension specified in the EventExt attribute (by default, .in). To facilitate record-keeping, rename the file in a meaningful
way. For example, rename Customer.fail to Customer_fail_sending.in.
- Restart the connector.
Data handlers and supported
business objects
If the connector returns an error stating that the data
handler has not been configured, verify that the meta-object for
the data handler is included in the list of supported business objects.
The most common error returned by the connector states that the
BOPrefix is not set.
The list of supported business objects for the DHFormatter should
include the following:
- MO_JTextConnector_Default
- MO_JTextConnector_BusObjName (meta-objects created for specific business objects)
- Business objects that are to be read from or written to a file.
- The meta-object for the data handler (which is specified in
the DataHandlerConfigMO attribute of the MO_JTextConnector_Default meta-object).
