Skip to content

Background Jobs

A Background Job is a method that can be started in the background. Usually the client take care of the transactions, but the background job acts as the client and is able to perform the transaction handling. Normally a background job is executed as soon as the database process is ready to execute it, but background jobs can also be scheduled to be executed on a specific schedule, these background jobs are called Scheduled Background Jobs.

Background jobs are managed by the interfaces in Transaction_SYS system service. Read more about the concept in Foundation1 Overview Manual.

Why use Background Jobs

If the business application contains several batch-oriented services such as handling of thousands of invoices or orders, it may be suitable to run some services in the background without keeping the user interface busy while it is processing. Foundation1 supports this by separate execution queues and services in Transaction_SYS.

Scheduled Background Jobs

The Scheduled Background Jobs differ in such a way that you need to register these methods as Tasks in IFS Solution Manager in order to execute them. After you have registered a task you can create a Scheduled Background Job.

Transactions

Background jobs are developed exactly the same way as any other method but you need to take care of the transaction handling. The transaction is normally taken care of by the client, but in this case the background job process is acting as the client. Handling of transactions is easily done by adding Commit and Rollback statements to the code if needed. Commit and rollback statements needs to be annotated.

The transaction annotation is @ApproveTransactionStatement .

This shows an example of a method that is designed as a background job:

Post a Background Job

To post a background job, use the Transaction_SYS.Deferred_Call method. In the simplest case, you only need to specify the procedure to run and the argument (e.g. attribute string) to the running procedure. Further, optional arguments, to Transaction_SYS.Deferred_Call are a describing text, which queue the job should be executed in, if the job is language independent or not and the total of number of steps to process.

It is recommended to specify the job to be language independent, i.e. set the lang_indep_ parameter to 'TRUE'. The default value is however 'FALSE' for backward compatibility reasons.

If the total amount of steps to process is set on the job, it is possible to follow the progress while it is running. Also, an estimate of remaining time is constantly updated in view V$SESSION_LONGOPS. Besides setting this value when the job is posted, it can be done by calling Transaction_SYS.Update_Total_Work at the beginning of the process as well. Each time the progress information is updated, the progress takes one step forward (or to a requested step). You can also move one or several steps forward without setting a new progress information using Transaction_SYS.Log_Progress_Longop.

Using Job Description

It is possible to specify a description of a job when initiating it through the method Transaction_SYS.Deferred_Call. This description is also included in the monitoring forms over background jobs. Use a proper description that makes it easier for the end-user to understand the purpose of the job instead of using the technical interface used in the business logic layer.

It is recommended to use method Language_SYS.Translate_Constant to enable language support.

Progress Monitoring

It is possible to specify progress information for the current job. This can be done in two ways, either as a progress information text attribute on the background job or as a list of status info updates. These texts will be displayed when monitoring the Background Jobs in Solution Manager.

Update Progress Information

Inside the code of the server process, call any of the methods Transaction_SYS.Set_Progress_Info or Transaction_SYS.Log_Progress_Info. Both methods are updating the same progress information, but Log_Progress_Info is executed as an autonomous transaction, i.e. the update is directly viewable to the end-user in difference to Set_Progress_Info where you must make a sub-commit on all the changes made so far to make the progress information viewable to the end-user.

If the total numbers of steps are set on the job, the progress takes one step forward (or to a requested step) each time the progress information is updated. You can also move one or many step forwards without setting a new progress information using Transaction_SYS.Log_Progress_Longop.

Use proper texts that give the end-user useful information when checking the progress of the job. This feature is very useful when executing heavy server processes divided in different parts including sub-commits.

It is recommended to use method Language_SYS.Translate_Constant to enable language support.

Update Status Information

Inside the code of the server process, call any of the methods Transaction_SYS.Set_Status_Info or Transaction_SYS.Log_Status_Info. Both methods are updating the same information but Log_Status_Info is executed as an autonomous transaction, i.e. the update is directly viewable to the end-user in difference to Set_Status_Info where you must make a sub-commit on all the changes made so far to make the progress information viewable to the end-user.

The progress does not automatically move any steps forward when updating status information, even if the total number of steps are set, which is a difference to Using Progress Information. Still it is possible to move one or many step forwards without setting a new progress information using Transaction_SYS.Log_Progress_Longop though.

Please use proper texts that give the end-user useful information when checking the status of the job. This interface may be used instead of implementing application business logic for this purpose. By using this feature, the server process may always trap server exceptions, logging it in the status table and then continue with the next part of the job.

It is recommended to use method Language_SYS.Translate_Constant to enable language support.

The status information handles the setting of the status for the completed job.

The parameter info_type_ has the default value 'WARNING' for backward compatibility reasons. If any status info of info_type_ 'WARNING' has been applied, the job will get the state 'Warning'. If no status information or only information of type 'INFO' has been applied, the job's status will be changed to 'Ready'. Any possible exception during execution will make the job end up in state 'Error'.

Jobs with state 'Ready' will be removed from the database by the cleanup processes in Foundation1 runtime. Jobs with state 'Warning' or 'Error' will not be affected by the cleanup.

Streams for Background Jobs and Reports

If you want to notify the user about the completion of a background job/ report, you may use the Streams for Background Jobs and Reports functionality. This is discussed in detail in the develpment guide.

Using Session Information

The method Transaction_SYS.Is_Session_Deferred checks whether the current session is running deferred or not.

Event Registry Functionality

The Foundation1 environment includes two registered events in the Event Registry for background jobs. These events may be used as trigger points for the administrator in customer environment to specify actions for different behavior of certain server processes. For more information, see Foundation1 Administrator's Guide.

  • BACKGROUND_JOB_IS_PROCESSED: Background job processed.
  • BACKGROUND_JOB_IN_PROGRESS: Background job in progress and partly ready.

Including Database Tasks and Database Task chains in code

After developing the method for the background job and creating the database task or chain, it might be required to include this as part of the code and to deliver to the customer.

To do this the Database Task or Database Task Chain needs to be exported as a .ins file and place in the source code repository.

1) Exporting the content.

This can be done by calling the Batch_Schedule_Method_API.Export__ / Batch_Schedule_Chain_API.Export__method. The first parameter is an out variable which will hold the ins script data, the second is an IN parameter where you need to input the database task id or chain id. The database task id or the chain id can be seen in the relevant Solution Manager page.

Example, this is exporting the database task 84.

Copy the output and create a .ins file

2) Place in the source code repo

The ins file should be placed in the source/[component]/database folder.

NOTE: The files created in Export option in the Solution Manager pages cannot be used for this purpose as they are importing and exporting through the client.

Example

The example below consists of two different procedures:

Gen_Customer_Statistics:

This procedure simulates a calculation of customer statistics.

This example includes how to update progress information tag for the current job during execution, using Transaction_SYS.Log_Progress_Info. It also shows how to apply different status information to background jobs by calling method Transaction_SYS.Log_Status_Info.

Initiate_Statistic_Process:

This procedure uses the procedure above and runs a customer statistic generation in a background job.