Streams for Background Jobs and Reports

Streams for Background jobs and Reports is an extension of the Streams concept which notifies end users of a completion of a background job/ report. The support for enabling Streams notifications for Background jobs and modifying the streams message which gets display to the end user have been exposed as an API. You could look at how this functionality is implemented for Task Schedules, Report schedules and Task Chain forms. These are to be considered as reference implementations which are using this API.

Contents

• Opt-in to Streams for Background Jobs
• Modifying the Generated Streams Message via the Hooking API
• Important Considerations
• Useful Links

Opt-in to Streams for Background Jobs

Opting into Streams for Background jobs is a matter of passing the following optional parameters into TRANSACTION_SYS.Deferred_Call / BATCH_SYS.New_Batch_Schedule.

• stream_msg_on_completion_ - Set to TRUE
• stream_notes_ - Optional notes to be shown to the end user

If you have existing calls into TRANSACTION_SYS.Deferred_Call  or BATCH_SYS.New_Batch_Schedule you may use the following overloads of these procedures to opt-in to this functionality

TRANSACTION_SYS.Deferred_Call:

TRANSACTION_SYS.Deferred_Call (
   id_              OUT NUMBER,
   procedure_name_   IN VARCHAR2,
   argument_type_db_ IN VARCHAR2,
   arguments_        IN VARCHAR2,
   description_      IN VARCHAR2,
   posted_date_      IN DATE DEFAULT sysdate,
   lang_indep_       IN VARCHAR2 DEFAULT 'FALSE',
   queue_id_         IN NUMBER DEFAULT NULL,
   total_work_       IN NUMBER DEFAULT NULL,
   stream_msg_on_completion_ IN VARCHAR2 DEFAULT 'FALSE',
   stream_notes_ IN VARCHAR2 DEFAULT NULL
   );

BATCH_SYS.New_Batch_Schedule:

BATCH_SYS.New_Batch_Schedule (
   schedule_id_            OUT    NUMBER,
   next_execution_date_    IN OUT NOCOPY DATE,
   start_date_             IN OUT NOCOPY DATE,
   stop_date_              IN     DATE,
   schedule_name_          IN     VARCHAR2,
   method_                 IN     VARCHAR2,
   active_db_              IN     VARCHAR2,
   execution_plan_         IN     VARCHAR2,
   lang_code_              IN     VARCHAR2 DEFAULT Nvl(Fnd_Session_API.Get_Language, 'en'),
   installation_id_        IN     VARCHAR2 DEFAULT NULL,
   external_id_            IN     VARCHAR2 DEFAULT NULL,
   check_executing_        IN     VARCHAR2 DEFAULT NULL, 
   stream_msg_on_completion_ IN VARCHAR2 DEFAULT 'FALSE',
   stream_notes_ IN VARCHAR2 DEFAULT NULL
 );
 

Modifying the Generated Streams Message via the Hooking API

The developer may also want to modify the message shown to the end-user with customized content relevant to the process that was carried out in the background. This could be achieved by calling the Transaction_SYS.Modify_Stream_Notification hooking API from within your background process.

Streams Message Structure

In a Streams Message a developer could customize the Header, Message and the URL. The note is entered by the end user and the Avatar is set depending on the Stream type.

The Hooking API

Transaction_SYS. Modify_Stream_Notification is the primary procedure for hooking to the Stream for Background job and Reports runtime. There are also several other helper procedures if you want to modify only a small set of parameters - Modify_Stream_Message , Modify_Stream_Reference  , Modify_Stream_URL, Modify_Stream_Error_Message.

Transaction_SYS. Modify_Stream_Notification (
   reference_ VARCHAR2 DEFAULT NULL,
   url_ VARCHAR2 DEFAULT NULL,
   trans_lu_name_ VARCHAR2 DEFAULT NULL,
   header_ VARCHAR2 DEFAULT NULL,
   message_ VARCHAR2 DEFAULT NULL,
   message_parameter_ VARCHAR2 DEFAULT NULL,
   error_header_ VARCHAR2 DEFAULT NULL, 
   error_message_ VARCHAR2 DEFAULT NULL, 
   error_message_parameter_ VARCHAR2 DEFAULT NULL
)

• REFERENCE
URL of the Form Where the Stream Message Originated. Usually given as an external search. E.g.- ifswin:Ifs.Application.InfoServices.ScheduleReport?external_search=schedule_id=34. If the value for REFERENCE is not specified then this will fall back to TaskSchedule or BackgroundJobs forms if left empty.


• URL
Optional URL of an Object to be Linked. E.g. - The appropriate Report Archive entry in the case of reports. E.g.- ifswin:Ifs.Application.InfoServices.ReportArchive?key1=10319


• TRANS_LU_NAME
Required If values given for the parameters Header/Message/ErrorHeader/ErrorMessage needs to be translated. Translation constants are looked up using this LU. Leave as NULL if Stream Header/Message does not need to be translated.


• HEADER
Streams Header as a Translatable Constant E.g.- 'REPOK: Report Ready'


• MESSAGE
Streams Message as a Translatable Constant E.g. - 'REPOKMSG: Report :P1 Is Now Ready'


• MESSAGE_PARAMETER
A single parameter to be substituted in the MESSAGE Translatable Constant . This maybe NULL if the MESSAGE Translatable constant is parameterless


• ERROR_HEADER
A Translatable constant, to be used as the Streams Header in the case of a background job ending in ERROR.


• ERROR_MESSAGE
A Translatable constant, to be used as the Streams Message in the case of a background job ending in ERROR.


• ERROR_ MSG_PARAMETER
A single parameter to be substituted in the ERROR_MESSAGE Translatable Constant . This maybe NULL if the ERROR_MESSAGE Translatable constant is parameterless

Using the Hooking API

The Hooking API could be used as follows:

PROCEDURE Background_Procedure()
IS
BEGIN

Transaction_SYS.Modify_Stream_Error_Message(lu_name,
	'STREAMERRORH: Background_Procedure Error'
	'STREAMERRORM: Background_Procedure terminated due to an unknown error');

   Background_Procedure_Body();
   
Transaction_SYS.Modify_Stream_Url('ifswin:Ifs.Application.InfoServices.ReportArchive?action=get'||'&'||'key1='|| result_key_);

Transaction_SYS.Modify_Stream_Message(lu_name_,
      'STREAMHEADER: Your Report Is Ready' , 
      'STREAMMSG: Report -  :P1 Is Now Ready ',
      Report_Definition_API.Get_Report_Title(report_id_));

END Background_Procedure;

For a concrete example you could look into how it’s implemented in Reporting Archive_API. Create_And_Print_Report__ 

There are also several helper API, if you want to modify only a small set of parameters- Modify_Stream_Message ,Modify_Stream_Reference ,Modify_Stream_URL,Modify_Stream_Error_Message.

Important Considerations

•  It’s recommended to make stream_msg_on_completion_ an end user-configurable option, configurable from the form the background job is scheduled on, so that the user could turn off the notification if not needed.

• Set a generic error message at the beginning of the Background Procedure. When a specific error is encountered, overwrite  this generic error with a more specific one using  the Modify_Stream_Error_Message helper procedure.

• The hooking API spins up a parallel transaction to update the trasaction_sys_local_tab. This may cause deadlocks with the Transaction_SYS.Set_Progress_Info procedure, which acquires locks from within the Main transaction. If you're using Transaction_SYS.Set_Progress_Info its advised that you use the Transaction_SYS.Log_Progress_Info procedure to get around this problem

Useful Links

• About Streams
• Streams for Background Jobs and Reports
• Background Jobs
• Background Jobs - Development Guide
• Using Streams Panel