About Streams for Background Jobs and Reports¶
Concept Overview¶
Streams for Background jobs and Reports leverages the Streams concept to notify end users of a completion of a background job/ report. In its current state it’s only implemented for Task Schedules, Report schedules and Task Chains. However the API makes it quite easy for anybody to signal a completion of any background job to the end -user.
How it works¶
Background jobs are typically of two types; One time background jobs (jobs posted through Transaction_SYS.Deferred_Call) and schedules (Posted through Batch_Sys. New_Batch_Schedule or Batch_Schedule_API.New__). The lifecycle these background jobs are controlled by the Transaction_SYS.Process_All_Pending scheduler job, which runs your background job and updates its completion state. This state information is used by the Streams for Background jobs runtime to notify the end user of job completion events (which could also be error state if the job encounters an error). This functionality is opt in for application developers. Additionally, one could customize the message which gets generated using one of the Modify API which "hooks" into the Streams for Background jobs. The procedure opting-in and using the hooking API is described in the following sections.
Opt-in Procedure¶
Opting into Streams for Background jobs is a matter of modifying existing function calls to include the following optional parameters.
- stream_msg_on_completion_ - Set to TRUE
- stream_notes_ - Optional notes to be shown to the end user
It’s also recommended to make this 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. Refer to the development guide for more details on the Opt-in procedure for Streams for Background jobs and Reports.
The Hooking API¶
In addition to opting into this functionality one 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. Refer to the development guide for more details on the Hooking API for Streams for Background jobs and Reports.