Views: 14424
Last Modified: 31.10.2022

Agents


Agents – process technique that permits you to launch arbitrary PHP functions (agents) with a preset frequency. Technically, agent - is an entry in a special table with the following data:
  • which code is to be executed,
  • when to execute,
  • period of execution,
  • how to set time for the next agent launch (strictly periodic or non-periodic agent).

The system automatically checks the agent's availability, requiring to be launched and executes it (if required) at the end of each page upload, after passing content to a browser.

How agent's availability was checked before the Main module version 20.5.0 release.

Note: Time accuracy of the agent launching directly depends on the steadiness and density of the site traffic. Actual agent launch time is usually a little later than specified time of the agent. Moment of launch occurs when somebody has visited a site page.
If you need to arrange for launching of any PHP functions at a definitely preset time, you have to use the standard utility cron available from most hosting providers.

In addition, resource intensive operations should not be assigned to agents, and there is a background launch option executed by cron.

In order for an agent to be executed at a set time, it must be registered in the system using the method of CAgent::AddAgent. An agent’s registration may be deleted using the function of CAgent::RemoveAgent.

If the agent function belongs to a module, this module will be automatically connected before the execution of such an agent function. Namely, the file /bitrix/modules/module ID/include.php will be connected. In this case, you have to make sure that the agent function will be available after the connection of this file.

If an agent function doesn't belong to any module, it must be located in the file /bitrix/php_interface/init.php. This file is automatically connected in the prologue.

The particularity of agent function creation is that the agent function must return a PHP code as function's return value that will be used during the next execution of this function.

List of agents, employed in the system is available at the Agents page (Settings > System Settings > Agents).

Periodic and non-periodic agents

Historically, agents are called "periodic" and "non-periodic" which also can be named as "recurring" and "non-recurring".

The user interface within the admin panel for the agent settings likewise has remained the same:

Type of agent depends on the software developer who wrote the agent's code. This developer can create an agent that could repeat an infinite amount of times. Or only 2-3 times depending on set conditions. Example of agent function recurring infinitely:

// example of agent function

function TestAgentPeriod()
{
   AddMessage2Log( "Periodic BX_CRONTAB:".BX_CRONTAB." BX_CRONTAB_SUPPORT:".BX_CRONTAB_SUPPORT );   
   return "TestAgentPeriod();";
}


function TestAgentNotPeriod()
{
   AddMessage2Log( "Non-periodic BX_CRONTAB:".BX_CRONTAB." BX_CRONTAB_SUPPORT:".BX_CRONTAB_SUPPORT );
   return "TestAgentNotPeriod();";
}

Type of agent is defined by the method for calculating time of the next agent start:

  • For Periodic, assigned time for the next start is calculated as follows: 
    Deprecated time set for agent + interval

    This method allows launching the agent for a precise number of times. For example, old email event cleaning agent launches once a day or an agent with daily site visit report.

  • Non-periodic, assigned time for the next start is calculated as follows: 
    Time of termination of the last agent launch (executed agent's return) + interval

    For example, agent for ratings recalculating is launched once per hour. However, if there were no visitors during a day, it's more logical to execute agent once or move assigned time of the next launch for an hour later after this launch. In case of strictly periodical agent, this code would have been executed all 24 hours per day.

    Absolute majority of agents are non-periodic.

Limits

When using this technology, please take into account the following:

  • The variable USER is unavailable in agents. To be more previce, it can be created at the hosting's server, however there's no guarantee that this would be an object of CUser class.
    If required, it's recommended to create the object $USER within the agent, perform an action with it and the destroy it.
  • You cannot perform authorization in agents using the method Authorize.
  • The constant SITE_ID is unavailable, because the an agent can be executed also at the section's admin page.
  • You cannot determine beforehand which language is used at the multi-language sites.
  • Agents are executed in a single thread mode with blocking at MySQL for 10 minutes. New agent call is possible only after the previous call has been processed. Database blocking can be lost, if connection with it has been severed. Ten minutes standby period - is an additional protection from repeated launch for agents that didn't perform correctly.




Chapter contents:


Courses developed by Bitrix24
Course description


Back to top ↑