20.14.3.2 Creating a Task Definition

Create a Task Definition from the Shared Components page, under the Workflows and Automations heading.

To create a task definition:

1. Select an application.
2. Navigate to the Task Definitions page:
   1. On the application home page, select Shared Components.
   2. Under Workflows and Automations, select Task Definitions.
3. Click Create.
   The Create Task Definition wizard appears.
4. Specify the task definition name and define the metadata.
   1. Name - Enter a name for the new Task Definition.
   2. Type - Select Approval Task for tasks with an outcome, or Action Task for tasks with no outcome.
   3. Subject - Provide a subject for the task definition.
      For example, Purchase Requisition for Order &ORDER_ID., where ORDER_ID is a defined parameter of the task definition. ORDER_ID is substituted with the parameter value on task creation.
      For more on substitution strings, see Substitution Strings and Bind Variables for Tasks.
   4. Static ID - Provide a static ID for this task definition. The static ID is used when creating the task with the APEX_HUMAN_TASK package (APEX_HUMAN_TASK.CREATE_TASK).
      APEX_APPROVAL is a synonym for APEX_HUMAN_TASK.
   5. Priority - Set the priority for the task. Choose a number between 1 and 5, where 1 is Urgent and 5 is Lowest. The default priority is 3 - Medium.
   6. Potential Owner - The user who owns the task.
      To determine potential owners dynamically, edit the participants in the Task Definition Details. For approval tasks, the user who initiates the task cannot own that task, even if they are listed as a Potential Owner. For action tasks, the user who initiates the task can also complete the task.
   7. Business Admin - The user who has administrative rights on all tasks for this task definition.
      To determine business administrators dynamically, edit the participants in the Task Definition Details.
5. Click Create.
   The Task Definition details page opens.
6. Set the Task Details Page Number. If a Task Details Page already exists for this application, enter the page number here. Otherwise, select Create Task Details Page to create a new page.
   The Task Details Page allows you to view the details of the task instance when the task is selected on the Unified Task List Report. See Editing the Task Details Page.
7. Set the Actions Source - Specify the source of the data that is evaluated when the task actions execute.
   These actions are based on tables or SQL queries. An Actions SQL Query can reference the bind variable :APEX$TASK_PK to access the value of the primary key in the task detail row.
8. Set Due on Type by specifying whether the Due Date is based on an ISO/SQL interval, SQL Query, Function Body, PL/SQL Expression, or Scheduler Expression.
   • For Interval, set Due on Interval - The ISO or SQL format duration that specifies a task's deadline.
   • For SQL Query, Function Body, or Expression, set Due On - The SQL Query, Expression, or Function Body that returns a valid due date for the task.
   • For Scheduler Expression, set Due On Scheduler Expression - Use the Database Scheduler calendaring syntax to schedule a due date. For example, first Friday of the month at 4:00 p.m..
9. Set the Expiration Policy:
   • None - After the due date, the task stays in its current state, and owners can still approve or reject the task. This is the default setting.
   • Expire - After the due date, the task expires. Expired tasks cannot be approved or rejected.
   • Renew - After the due date, the task expires, and a new task is created from the same task definition. If you select Renew, set the Maximum Renewal Count to specify the maximum number of times a task is automatically renewed. A task can be renewed up to 99 times.
10. Create Participants to assign additional people to the Task Definition.
    1. Select Add Row.
    2. Edit the Participant Type to select Potential Owner or Business Administrator.
       For approval tasks, the user who initiates a task cannot approve their own task, even if they are listed as a Potential Owner. For action tasks, the user who initiates a task can own and complete their own task.
    3. Set the Value Type.
       SQL Query, Function Body, and Expression all allow users to be dynamically selected, and can return a single user name or a comma-separated list of multiple user names.
    4. Set the Value.
11. Set Parameters.
    1. Select Add Row and fill in the parameter fields.
    2. Static ID - Identifier used to reference the parameter.
    3. Label - A user-friendly name for the task parameter.
    4. Data Type - Choose String.
    5. Required - Specify whether the parameter is mandatory.
    6. Visible - Specify whether the parameter is visible in the task details page.
    7. Updatable - Specify whether the parameter can be updated in the Task Details page after the task is started.
    8. Comment (Optional) - Describe the parameter.

    Note:

    Parameters set in the Task Definition also need to be set in the page process. See Creating Tasks from Task Definitions.
12. Select Apply Changes to save all existing changes, and then click on the task definition name to continue editing.
13. Add Actions.
    1. Click Add Action.
       The Edit Action page opens.
    2. Name - Enter a name for the task definition action.
    3. Type - Select Execute Code, Send Email, or Send Push Notification.
       For Send Email, you can use predefined email templates with substitution strings. For example, you can configure a notification email to the initiator when a task is approved or rejected. For more information, see Managing Email Templates.
       If you have a plug-in set up for task definitions, you can use that plug-in here. For more information, see About Creating a Task Definition Process Plug-in.
    4. Execution Sequence - Specify the execution sequence. Actions are executed in numerical order from low to high.
    5. On Event - Select the event that triggers the action.
    6. Success Message - Enter a success message that indicates the action is successfully processed. The success message is included in the task history if the Log Messages When attribute in the Error Handling section is set to All or Success.
14. Configure the Action Type.
    • Set attributes for Execute Code:
      • Location - Specify whether your PL/SQL code is executed in the Local Database or on a REST Enabled SQL Service.
      • Language - Select the language used to evaluate the code.
      • Code - Provide the PL/SQL code to be executed.
        • Column values from the task definition action query are available as bind variables by column name, such as :EMPNO and :ENAME. For more on bind variables, see Substitution Strings and Bind Variables for Tasks. You can expand the Examples section to see code examples.
    • Set attributes for Send Email:
      • From - The email address that displays as the sender of the email.
      • To - The email recipients.
      • Cc - The carbon copy email recipients.
      • Bcc - The blind carbon copy email recipients.
      • Reply To - The email address replies are sent to. If left blank, the From email is used.
      • Email Template - Choose an email template, and set the placeholder values. For more information, see Managing Email Templates.
      • Subject - The subject of the email.
      • Body Plain Text - The text of the email. Plain text is used if the recipient's email client does not support rich text. See the in-app help text for more details.
      • Body HTML - The HTML text of the email. See the in-app help text for more details.
      • Attachment SQL - Enter a SQL statement that returns one or more BLOBs that are attached to the email as files.
    • Set attributes for Send Push Notification:
      • To - User name of the application user who receives the push notification. To receive the notification, the user must have subscribed to the application first. User name is case sensitive.
      • Title - Title of the push notification.
      • Body - Body of the push notification.
      • Link Target - URL of the page that opens when the user clicks on the push notification. This defaults to the home page of the application. You can use the &APP_ID., &SESSION., and &DEBUG. substitution strings with &COLUMN_NAME. syntax to set the row ID or primary key on the target page, or to set additional attribute values. For more information, on URL syntax, see Understanding f?p URL Syntax.
15. Set up Error Handling:
    1. Error Message - Enter an error message that can be added to the task log if the action errors while executing. The error message is included in the task history if the Log Messages When attribute in the Error Handling section is set to All or Failure. Use #SQLERRM# as a placeholder for the actual ORA error message.
    2. Stop Execution on Error - Enable if processing for the current task stops after an error. Subsequent actions are not processed, and the task goes into the ERRORED state.
    3. Log Messages When - Specify the actions that are logged in the task history. You can choose between None, Success, Failure, and All. When actions are logged in the history, they include the Success Message or Error Message text.
16. Finish configuring the Action.
    1. Condition Type - Select a condition type that must be met for this action to be executed.
    2. Build Option - Select a build option for this action. Build options determine whether or not components in an application are enabled.
    3. Comments - Enter developer notes here. These comments only display in App Builder and are not visible in the application.
17. Click Create to go back to the Task Definition.
18. Add any comments for this task definition.
19. Click Apply Changes.

APEX creates the task definition.