sitemap.xml llms.txt
Skip to main content

Tasks

Tasks are units of work that you can schedule to be executed by Epicenter. Tasks can fire on a repeating cron schedule, at a specific date and time, or after a configured offset from the moment of creation.

Tasks are useful whenever your simulation needs something to happen independent of participants' actions. For example, you might use a task to advance the model on a fixed deadline, or to update a group's status.

Trigger​

The task trigger specifies the scheduling of the task:

  • Offset task trigger: The task's operation will start running the specified amount of time after the task is created.
  • Date task trigger: Specifies a date-time value when the operation should run.
  • Cron task trigger: A string in standard Cron format. Schedules a repeating task.

Payload​

The task payload defines the operation Epicenter performs when the task executes. Every task has exactly one payload, which is one of two types.

  • An HTTP request: A call made to a page in your Epicenter application or to the proxy. This could be used to trigger events in the application if your users are playing a real-time game. For example, your model may step forward at regular time intervals rather than in response to a participant's decision. The target field controls where the HTTP request is sent:
    • APPLICATION (the default) routes the request to your project's application server at /app.
    • PROXY routes it to your project's proxy server at /proxy.
  • A group-status task: An update to the status of a group. The status object contains a code and a message.

Scope​

Every task is created with a scope that determines which entity the task belongs to.

Task status​

Epicenter tracks the current status of every task throughout its lifecycle. A task moves through the following statuses:

  • initialized: The task has been created and is waiting to be triggered.
  • triggered: The task has fired, and the operation is in progress.
  • succeeded: The task completed successfully.
  • failed: The task fired, but the operation did not complete successfully.
  • cancelled: The task was deleted before it could complete.
  • terminated: The task reached its fail-safe termination deadline.

Retry policy​

The retry policy controls what Epicenter does when a task fails.

  • The default policy, DO_NOTHING, leaves a failed task in its failed state without retrying.
  • The FIRE_ON_FAIL_SAFE policy schedules a retry within the task's fail-safe execution window.
Note

The fail-safe termination is a date and time after which the task is permanently terminated regardless of its retry policy.

Task history​

Epicenter keeps a task history with a record of success or failure and an optional result description. You can retrieve up to the 100 most recent executions for a task.

The lifespan of a task after it stops running is 18 months. Afterward, the task is deleted from history without a trace.

Learn more

To view task history, call the getHistory() function.

Cancelling a task​

To cancel a scheduled task, use the Task adapter's destroy() function.

Learn more

For a more comprehensive list of task properties, see the TaskReadOutView object description in the developer reference.

The Epicenter libs functions that manage tasks are described in Task functions.