API

There are several APIs to manipulate and query workflow tasks and cases.

Task and Case queries

The fluent workflow query API supports queries against all existing tasks and cases. You can write the queries in a SQL-like manner.

import ch.ivyteam.ivy.workflow.query.TaskQuery;
import ch.ivyteam.ivy.workflow.ITask;

// create a new query
TaskQuery query = TaskQuery.create()
  .aggregate().avgCustomDecimalField1()
  .where().customVarCharField1().isEqual("ivy")
  .groupBy().state()
  .orderBy().customVarCharField2().descending();
// retrieve query results
List<ITask> tasks = ivy.wf.getTaskQueryExecutor().getResults(query);

To retrieve all tasks that the current user can work on using the following code:

TaskQuery query = TaskQuery.create()
  .where().currentUserCanWorkOn()
  .orderBy().priority();
List<ITask> userWorkTasks = ivy.wf.getTaskQueryExecutor().getResults(query);

To execute a query, you need an instance of an IQueryExecutor. Retrieve it trough the ivy environment variable.

Queries are executed against a single security context by default.

Warning

You can execute queries over all security contexts on the engine and their applications in the global workflow context using the Query Executor. However, multiple security contexts cannot share a user. Therefore, the results of global queries are invalid and meaningless.

// Retrieve application specific query executors from the application context
ivy.wf.getTaskQueryExecutor().getResults(taskQuery);
ivy.wf.getCaseQueryExecutor().getResults(caseQuery);

Task and Case manipulation

The API to manipulate tasks and cases is available trough the ivy environment variable.

  • ivy.case (ICase): represents the currently executing process

  • ivy.task (ITask): represents the user’s current work unit in the currently executing process.

  • ivy.wf (IWorkflowContext): addresses all workflow tasks and cases of all users for the current security context.

  • ivy.session (IWorkflowSession): gives access to all workflow tasks and cases of the current user.

REST API

There is an REST workflow API available that allows third-party services to interact with workflow Tasks, Cases, and the like.

The workflow API is enabled by default. Disable it by setting the configuration to REST.Servlet.API: false.

1# ivy.yaml
2REST.Servlet.API: false

You can browse this API by using the API Browser.

If any REST workflow API is missing for your specific use case, keep in mind that you can provide additional APIs very easily by creating REST API service classes in your project. See Provide Your Own REST Services