25.1.9.1.3 Accepting Input Values in Parameters

Use task parameters for values the task cannot get from its Actions Source row.

Use the pre-defined APEX$TASK_PK parameter to reference the value of the Details Primary Key passed in when a task instance is created. For many use cases, it is the only parameter value you need. Assuming you have also configured the task definition's Actions Source table or query, this combination can often provide all necessary context information. However, if there are additional values unique to the pending work item that are not (yet) available as Actions Source column values, you can define explicit task parameters to accept them when the task is created.

Tip:

You can optionally make task parameters updatable. These are useful to model additional data that the task assignee must provide as part of reviewing or approving the task.

When defining a parameter, you provide a user-friendly label that can be in mixed case and include spaces. You also provide an alphanumeric static ID. You can reference any parameter's value throughout the task definition using the &STATIC_ID. or :STATIC_ID notation depending on the context. The APEX engine manages task parameter storage and makes them queryable in a generic way through the APEX_TASK_PARAMETERS dictionary view.

A simple example of a task parameter for a Salary Change approval task is the New Proposed Salary, with a Static ID of P_PROPOSED_SALARY. Until the change of salary is approved, this value only exists as part of the task instance for approvers to consider. If one of them approves the task, then a task action you define on the Completed event with Approved outcome can update the SAL column in the EMP table for the employee to the new, approved value. Assuming you configured EMP as the Actions Source table for this task, and passed in the employee's EMPNO value as the Details Primary Key when creating the task, your action code can perform this update using a simple statement like:

update emp
   set sal = :P_PROPOSED_SAL
  where empno = :EMPNO;

Tip:

Imagine you find your task definition is not logically related to any particular table in your application data model, and that you are compelled to create many parameters to capture input data for the task. This can be a sign your application data model needs a new table to track the task in question. Consider defining a new table to represent the particular request, with columns for all the data you found yourself defining task parameters for. Should that make sense for your use case, then associate this new table with your task definition as its Actions Source. After doing that, the built-in APEX$TASK_PK parameter may be the only parameter you need. Your page or workflow inserts a row into this new table, then passes its primary key to the task flow as its Details Primary Key value. A follow-on benefit is that it is simpler to query all of the data related to the task from other parts of your application.