Scope: managed applications.
1. Whenever you develop a configuration, avoid time-consuming calls from the client code to the server one. We recommend that you perform all time-consuming server calls that can be executed for over 8 seconds asynchronously in standard user scenarios using a background job.
These operations include: generation of reports, bulk processing of objects, data import or export to another application, filling of large tabular sections, and other.
Otherwise, these calls may cause a loss of application functionality or a user experience problem:
- A browser can offer to stop a time-consuming scenario. This will make the application non-functional.
- A web server can stop a time-consuming 1C:Enterprise server call and return error 504 (gateway timeout).
- If an operation is time-consuming, users cannot cancel it.
- A code that processes data for a long time is a part of the object* manager module or common module. It puts its result in the temporary storage.
*Note: use a wrapper procedure in the common module to call a manager module procedure through Common.ExecuteConfigurationMethod(). Background jobs can operate with procedures and functions of common modules only.
- To execute this code on the server, a background job is started. However, you need to wait for background job completion for 0.8 seconds.
- If the job is not completed within the timeout period, control is given back to the client and an idle handler is attached in the client code to periodically check the background job state. The job polling interval increases from 1 to 15 seconds with fixed increment 1.4.
- An indicator is displayed to a user during a time-consuming operation.
For reports, the indicator is displayed in the spreadsheet document field using the StatePresentation spreadsheet document field property:
Otherwise, a locking form is displayed (WindowOpenMode = LockOwnerWindow), where a decoration with an animated picture and the Cancel button are available:
- As soon as the server sends a message notifying that the background job was completed, the result is loaded from the temporary storage and further processed.
- Reports are developed without DCS or using DCS with an overridden report generation procedure (the Generate button handler is overridden, or StandardProcessing = False is set in the OnComposeResult report module handler).
- Reports are usually generated for a long time.
Make sure that behavior of such reports is most similar to that of reports based on DCS:
- Do not lock a report form during its generation.
- A user can change settings and regenerate a report, without waiting for the report to generate.
- Once the report form is closed, report generation is stopped.
3. If Standard Subsystems Library is used in the configuration, developers can take advantage of auxiliary functions and procedures of the TimeConsumingOperations and TimeConsumingOperationsClient common modules, and the SetSpreadsheetDocumentFieldState procedure of the CommonClientServer common module.
Let's have a look at an example where a function is executed in a background job when Standard Subsystems Library is used in the configuration. The object manager module contains a function that searches for settings and returns them:
Function DefineAccountSettings(Email, Password) Export
The function is called in the object form in a background job in three steps:
1. Start a background job on the server.
2. Attach a handler of background job completion on the client.
3. Process the background job result.
// 1. Starting a background job on the server.
TimeConsumingOperation = StartSearchForAccountSettings();
// 2. Attaching a handler of background job completion.
IdleParameters = TimeConsumingOperationsClient.IdleParameters(ThisObject);
Notification = New NotifyDescription("OnCompleteSearchForSettings", ThisObject);
TimeConsumingOperationsClient.WaitForCompletion(TimeConsumingOperation, Notification, IdleParameters);
Return TimeConsumingOperations.ExecuteFunction(ExecutionParameters, "Catalogs.EmailAccounts.DefineAccountSettings",
// 3. Processing the background job result.
Procedure OnCompleteSearchForSettings(Result, AdditionalParameters) Export
If Result = Undefined Then // The user canceled the job.
If Result.Status= "Error" Then
Raise Result. BriefErrorDescription;
Settings = GetFromTempStorage(Result.ResultAddress);
4. If the configuration includes algorithms that initiate background job startup or recording of infobase data without user intervention (for example, explicit regular update of information), make sure that exclusive mode is not set for them in the current session. Otherwise, lock attempts to perform such actions. For example:
If ExclusiveMode() Then
Infobase data update upon first interactive launch of the application after configuration update.
Deletion of objects marked for deletion.
Export of infobase data into a file to go to the service.
Use of exclusive mode to reduce time required to perform bulk data change operations.
First you need to set an exclusive mode. Then you can start a background job to complete the time-consuming operation. In this case, the background job will inherit the exclusive mode set before that in the user session (see 1C:Enterprise Developer Guide).
We recommend that you lock the whole application interface during execution of this background job by opening the operation completion idle form in mode WindowOpenMode = LockWholeInterface. It is required to lock the application interface as users are no longer able to use full functionality of the application during job execution:
- If users(*) attempt to write an object, an error occurs (since the exclusive mode is set).
- In some cases, background jobs can be started in response to user actions (search in a dynamic list, input by string, report generation, and other), which will also fail.
Moreover, we do not recommend that you include controls in the time-consuming operation idle form, which can start such background jobs. For example: input fields, dynamic lists, and reports.
* Note: write errors also occur if objects are written programmatically, for example, from idle handlers. Check the exclusive mode here according to cl. 5 as well.