Interface FormService

  • All Known Implementing Classes:
    FormServiceImpl

    public interface FormService
    Access to form data and rendered forms for starting new process instances and completing tasks.
    Author:
    Tom Baeyens, Falko Menge (camunda)
    • Method Summary

      All Methods Instance Methods Abstract Methods Deprecated Methods 
      Modifier and Type Method Description
      java.io.InputStream getDeployedStartForm​(java.lang.String processDefinitionId)
      Retrieves a deployed start form for a process definition with a given id.
      java.io.InputStream getDeployedTaskForm​(java.lang.String taskId)
      Retrieves a deployed task form for a task with a given id.
      java.lang.Object getRenderedStartForm​(java.lang.String processDefinitionId)
      Rendered form generated by the default build-in form engine for starting a new process instance.
      java.lang.Object getRenderedStartForm​(java.lang.String processDefinitionId, java.lang.String formEngineName)
      Rendered form generated by the given build-in form engine for starting a new process instance.
      java.lang.Object getRenderedTaskForm​(java.lang.String taskId)
      Rendered form generated by the default build-in form engine for completing a task.
      java.lang.Object getRenderedTaskForm​(java.lang.String taskId, java.lang.String formEngineName)
      Rendered form generated by the given build-in form engine for completing a task.
      StartFormData getStartFormData​(java.lang.String processDefinitionId)
      Retrieves all data necessary for rendering a form to start a new process instance.
      java.lang.String getStartFormKey​(java.lang.String processDefinitionId)
      Retrieves a user defined reference to a start form.
      VariableMap getStartFormVariables​(java.lang.String processDefinitionId)
      Retrieves a list of all variables for rendering a start from.
      VariableMap getStartFormVariables​(java.lang.String processDefinitionId, java.util.Collection<java.lang.String> formVariables, boolean deserializeObjectValues)
      Retrieves a list of requested variables for rendering a start from.
      TaskFormData getTaskFormData​(java.lang.String taskId)
      Retrieves all data necessary for rendering a form to complete a task.
      java.lang.String getTaskFormKey​(java.lang.String processDefinitionId, java.lang.String taskDefinitionKey)
      Retrieves a user defined reference to a task form.
      VariableMap getTaskFormVariables​(java.lang.String taskId)
      Retrieves a list of all variables for rendering a task form.
      VariableMap getTaskFormVariables​(java.lang.String taskId, java.util.Collection<java.lang.String> formVariables, boolean deserializeObjectValues)
      Retrieves a list of requested variables for rendering a task form.
      ProcessInstance submitStartForm​(java.lang.String processDefinitionId, java.lang.String businessKey, java.util.Map<java.lang.String,​java.lang.Object> properties)
      Start a new process instance with the user data that was entered as properties in a start form.
      ProcessInstance submitStartForm​(java.lang.String processDefinitionId, java.util.Map<java.lang.String,​java.lang.Object> properties)
      Start a new process instance with the user data that was entered as properties in a start form.
      ProcessInstance submitStartFormData​(java.lang.String processDefinitionId, java.lang.String businessKey, java.util.Map<java.lang.String,​java.lang.String> properties)
      ProcessInstance submitStartFormData​(java.lang.String processDefinitionId, java.util.Map<java.lang.String,​java.lang.String> properties)
      void submitTaskForm​(java.lang.String taskId, java.util.Map<java.lang.String,​java.lang.Object> properties)
      Completes a task with the user data that was entered as properties in a task form.
      void submitTaskFormData​(java.lang.String taskId, java.util.Map<java.lang.String,​java.lang.String> properties)
      VariableMap submitTaskFormWithVariablesInReturn​(java.lang.String taskId, java.util.Map<java.lang.String,​java.lang.Object> properties, boolean deserializeValues)
      Completes a task with the user data that was entered as properties in a task form.
    • submitTaskFormData

      @Deprecated
      void submitTaskFormData​(java.lang.String taskId,
                              java.util.Map<java.lang.String,​java.lang.String> properties)
    • submitTaskFormWithVariablesInReturn

      VariableMap submitTaskFormWithVariablesInReturn​(java.lang.String taskId,
                                                      java.util.Map<java.lang.String,​java.lang.Object> properties,
                                                      boolean deserializeValues)
      Completes a task with the user data that was entered as properties in a task form.
      Parameters:
      taskId -
      properties -
      deserializeValues - if false, returned SerializableValues will not be deserialized (unless they are passed into this method as a deserialized value or if the BPMN process triggers deserialization)
      Returns:
      a map of process variables
      Throws:
      AuthorizationException - If the user has no Permissions.UPDATE permission on Resources.TASK or no Permissions.UPDATE_TASK permission on Resources.PROCESS_DEFINITION.
    • getStartFormVariables

      VariableMap getStartFormVariables​(java.lang.String processDefinitionId)
      Retrieves a list of all variables for rendering a start from. The method takes into account FormData specified for the start event. This allows defining default values for form fields.
      Parameters:
      processDefinitionId - the id of the process definition for which the start form should be retrieved.
      Returns:
      a map of VariableInstances.
      Throws:
      AuthorizationException - If the user has no Permissions.READ permission on Resources.PROCESS_DEFINITION.
    • getStartFormVariables

      VariableMap getStartFormVariables​(java.lang.String processDefinitionId,
                                        java.util.Collection<java.lang.String> formVariables,
                                        boolean deserializeObjectValues)
      Retrieves a list of requested variables for rendering a start from. The method takes into account FormData specified for the start event. This allows defining default values for form fields.
      Parameters:
      processDefinitionId - the id of the process definition for which the start form should be retrieved.
      formVariables - a Collection of the names of the variables to retrieve. Allows restricting the set of retrieved variables.
      deserializeObjectValues - if false object values are not deserialized
      Returns:
      a map of VariableInstances.
      Throws:
      AuthorizationException - If the user has no Permissions.READ permission on Resources.PROCESS_DEFINITION.
    • getTaskFormVariables

      VariableMap getTaskFormVariables​(java.lang.String taskId)

      Retrieves a list of all variables for rendering a task form. In addition to the task variables and process variables, the method takes into account FormData specified for the task. This allows defining default values for form fields.

      A variable is resolved in the following order:

      • First, the method collects all form fields and creates variable instances for the form fields.
      • Next, the task variables are collected.
      • Next, process variables from the parent scopes of the task are collected, until the process instance scope is reached.

      Parameters:
      taskId - the id of the task for which the variables should be retrieved.
      Returns:
      a map of VariableInstances.
      Throws:
      AuthorizationException -

      In case of standalone tasks:

    • if the user has no Permissions.READ permission on Resources.TASK or
    • if the user has no TaskPermissions#READ_VARIABLE permission on Resources.TASK when this config is enabled
    • In case the task is part of a running process instance:

    • if the user has no Permissions.READ permission on Resources.TASK or no Permissions.READ_TASK permission on Resources.PROCESS_DEFINITION
    • if the user has TaskPermissions#READ_VARIABLE permission on Resources.TASK or no ProcessDefinitionPermissions#READ_TASK_VARIABLE permission on Resources.PROCESS_DEFINITION when this config is enabled
    • getTaskFormVariables

      VariableMap getTaskFormVariables​(java.lang.String taskId,
                                       java.util.Collection<java.lang.String> formVariables,
                                       boolean deserializeObjectValues)

      Retrieves a list of requested variables for rendering a task form. In addition to the task variables and process variables, the method takes into account FormData specified for the task. This allows defining default values for form fields.

      A variable is resolved in the following order:

      • First, the method collects all form fields and creates variable instances for the form fields.
      • Next, the task variables are collected.
      • Next, process variables from the parent scopes of the task are collected, until the process instance scope is reached.

      Parameters:
      taskId - the id of the task for which the variables should be retrieved.
      formVariables - a Collection of the names of the variables to retrieve. Allows restricting the set of retrieved variables.
      deserializeObjectValues - if false object values are not deserialized
      Returns:
      a map of VariableInstances.
      Throws:
      AuthorizationException -

      In case of standalone tasks:

    • if the user has no Permissions.READ permission on Resources.TASK or
    • if the user has no TaskPermissions#READ_VARIABLE permission on Resources.TASK when this config is enabled
    • In case the task is part of a running process instance:

    • if the user has no Permissions.READ permission on Resources.TASK or no Permissions.READ_TASK permission on Resources.PROCESS_DEFINITION
    • if the user has TaskPermissions#READ_VARIABLE permission on Resources.TASK or no ProcessDefinitionPermissions#READ_TASK_VARIABLE permission on Resources.PROCESS_DEFINITION when this config is enabled
    • getStartFormKey

      java.lang.String getStartFormKey​(java.lang.String processDefinitionId)
      Retrieves a user defined reference to a start form. In the Explorer app, it is assumed that the form key specifies a resource in the deployment, which is the template for the form. But users are free to use this property differently.
      Throws:
      AuthorizationException - If the user has no Permissions.READ permission on Resources.PROCESS_DEFINITION.
    • getTaskFormKey

      java.lang.String getTaskFormKey​(java.lang.String processDefinitionId,
                                      java.lang.String taskDefinitionKey)
      Retrieves a user defined reference to a task form. In the Explorer app, it is assumed that the form key specifies a resource in the deployment, which is the template for the form. But users are free to use this property differently. Both arguments can be obtained from Task instances returned by any TaskQuery.
      Throws:
      AuthorizationException - If the user has no Permissions.READ permission on Resources.PROCESS_DEFINITION.
    • getDeployedStartForm

      java.io.InputStream getDeployedStartForm​(java.lang.String processDefinitionId)
      Retrieves a deployed start form for a process definition with a given id.
      Throws:
      AuthorizationException - If the user has no Permissions.READ permission on Resources.PROCESS_DEFINITION.
      NotFoundException - If the start form cannot be found.
      BadUserRequestException - If the start form key has wrong format ("embedded:deployment:" or "deployment:" required).
    • getDeployedTaskForm

      java.io.InputStream getDeployedTaskForm​(java.lang.String taskId)
      Retrieves a deployed task form for a task with a given id.
      Throws:
      AuthorizationException - If the user has no Permissions.READ permission on Resources.TASK.
      NotFoundException - If the task form cannot be found.
      BadUserRequestException - If the task form key has wrong format ("embedded:deployment:" or "deployment:" required).