Skip to content

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.

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='||&nbsp;result_key_);<br/><br/>Transaction_SYS.Modify_Stream_Message(lu_name_,<br/>      'STREAMHEADER: Your Report Is Ready' , <br/>      'STREAMMSG: Report -  :P1 Is Now Ready ',<br/>      Report_Definition_API.Get_Report_Title(report_id_));<br/><br/>END Background_Procedure;<br/><br/>

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