Package com.sas.lsaf.workflow.processdefinition

## Interface ProcessDefinitionService

-     public interface ProcessDefinitionService

  The service that supports the deployment, suspension, and activation of process flow definitions as well as mapping process definitions for autoflow. To create a process flow from a process flow definition, the definition must be deployed and active (not suspended).

  A process flow definition is deployed from a BPMN file in the repository. See `deployProcessDefinitionFromRepository`. The BPMN file defines the elements, form properties, completion properties, and sequence flow logic. A definition can be updated by re-deploying from a BPMN file. This will create a new deployed version of the process definition. Process flows can be created only from the latest deployed definition.

  A process flow definition can be mapped by associating element attributes with other `AutoFlowLaunchable` object attributes so that process flows can be automatically created. For example, a study `TLFs` attributes can be mapped for auto flow creation.

  For information about process flow definition element attributes, such a name and type, see `getProcessDefinitionMappingMetadata()`. This returns ProcessDefinitionMappingMetadata for each `AutoFlowType`, such as TLF. It indicates for each element type, the element attribute that maps to which TLF attribute. To create or update a definition mapping, first get the process definition and then get the process definition mapping. For example,

           ProcessDefinitionInfo processDef = service.getProcessDefinitionByKey("SimpleFlow");
           ProcessDefinitionMapping defMapping = service.getProcessDefinitionMappingByType(AutoFlowType.TLF,
                   processDef.getProcessDefinitionKey());
           List<FlowElementMapping> elementMapping = defMapping.getElementMapping();

  If the process flow definition has never been mapped, the element mapping is empty. To create a mapping and enable the definition for auto flow, see the example below. For simplicity, this process flow definition has a single user task, and a mapping is created for the user task Assignee attribute only. Hard-coded attribute names are used for convenience. For the full list of attributes and their metadata, see `getProcessDefinitionMappingMetadata()` and `StudyTlfService.getTlfAttributeMetadata()`.

           Set<FlowElementDefinition> elements = service.getProcessDefinitionElements(def.getId());
           FlowElementDefinition userTask = elements.iterator().next();

           FlowElementMapping userTaskMapping = new FlowElementMapping(userTask.getElementId(), userTask.getType());
           List<AttributeMapping> attrMap = userTaskMapping.getAttributeMapping();
           attrMap.add(new AttributeMapping("Assignee", "User Assignment 1", FlowAttributeType.USER));
           elementMapping.add(userTaskMapping);

           defMapping.setEnableAutoFlowMapping(true);
           defMapping = service.updateProcessDefinitionMapping(defMapping);

  NOTE: You must set enable auto flow to true in order to save the element mapping. Once you have saved the mapping by calling `updateProcessDefinitionMapping(ProcessDefinitionMapping)`, you can check that the mapping is complete with `isMappingComplete()`. If `true`, the process flow definition is available to automatically create process flows. To find all such process flow definitions, see `getProcessDefinitionsMappedForAutoFlow(String, AutoFlowType, boolean)`.

  A mapping is considered complete when the required attributes have been specified so that a process flow can be successfully activated. In the example above, the process definition contains only a single user task, and no user task attributes are required for activation. So, once `setEnableAutoFlowMapping` is set to `true`, the mapping is complete. If the process flow definition contains elements such as `SignalEventDefintion` or `TimerEventDefinition`, that have required attributes, those elements must to be mapped before mapping is complete and flows can be automatically created.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `ProcessDefinitionInfo` | `activateProcessDefinition​(java.lang.String processDefinitionKey)` | Activates the latest deployed version of the process flow definition so that process flows can be created from it.
    `ProcessDefinitionInfo` | `deployProcessDefinitionFromRepository​(java.lang.String path, java.lang.String version, java.util.Set<java.lang.String> contextTypeIds, java.lang.String comment, boolean activate, boolean overwrite)` | Deploys the process flow definition file from the repository.
    `java.util.List<ProcessDefinitionInfo>` | `getAllProcessDefinitions()` | Gets all of the latest deployed process flow definitions.
    `ProcessDefinitionInfo` | `getProcessDefinitionById​(java.lang.String id)` | Gets the process flow definition with the specified unique identifier.
    `ProcessDefinitionInfo` | `getProcessDefinitionByKey​(java.lang.String processDefinitionKey)` | Gets the latest deployed version of the process flow definition by the specified process flow definition key.
    `java.util.Set<FlowElementDefinition>` | `getProcessDefinitionElements​(java.lang.String id)` | Gets the elements of a process flow definition.
    `ProcessDefinitionMapping` | `getProcessDefinitionMappingByType​(AutoFlowType type, java.lang.String processDefinitionKey)` | Gets the element mapping for the process flow definition based on the auto flow type.
    `java.util.List<ProcessDefinitionMappingMetadata>` | `getProcessDefinitionMappingMetadata()` | Gets the process flow definition mapping metadata that describes the elements that can be mapped to what attribute types.
    `java.util.List<ProcessDefinitionInfo>` | `getProcessDefinitionsByContextType​(java.lang.String contextTypeId)` | Gets the latest deployed process flow definitions at the context with the context type.
    `java.util.List<ProcessDefinitionInfo>` | `getProcessDefinitionsMappedForAutoFlow​(java.lang.String contextTypeId, AutoFlowType autoFlowType, boolean activeOnly)` | Gets the process flow definitions that are enabled and mapped for automatic process flow creation by the specified context type.
    `ProcessDefinitionInfo` | `suspendProcessDefinition​(java.lang.String processDefinitionKey)` | Suspends the latest deployed version of the process flow definition so that process flows cannot be created from it.
    `ProcessDefinitionMapping` | `updateProcessDefinitionMapping​(ProcessDefinitionMapping mapping)` | Updates the element mapping for the process definition based on the auto flow type.

- - ### Method Detail

    - #### getProcessDefinitionsByContextType

          java.util.List<ProcessDefinitionInfo> getProcessDefinitionsByContextType​(java.lang.String contextTypeId)
                                                                            throws ProcessFlowException

      Gets the latest deployed process flow definitions at the context with the context type.
      Parameters:
        `contextTypeId` - The context type identifier for which to get the process flow definitions.
      Returns:
        The list of process flow definitions.
      Throws:
        `ProcessFlowException` - Thrown when there is an issue getting the process flow definitions.

    - #### getAllProcessDefinitions

          java.util.List<ProcessDefinitionInfo> getAllProcessDefinitions()

      Gets all of the latest deployed process flow definitions.
      Returns:
        The list of all process flow definitions.

    - #### deployProcessDefinitionFromRepository

          ProcessDefinitionInfo deployProcessDefinitionFromRepository​(java.lang.String path,
                                                                      java.lang.String version,
                                                                      java.util.Set<java.lang.String> contextTypeIds,
                                                                      java.lang.String comment,
                                                                      boolean activate,
                                                                      boolean overwrite)
                                                               throws ProcessDefinitionDeploymentException

      Deploys the process flow definition file from the repository. If `activate` is specified as False, the process flow definition is deployed but in a suspended state, which means no process flows can be created from that process flow definition until it is activated.
      Parameters:
        `path` - The path of the process flow definition file.
        `version` - The version of the process flow definition file.
        `contextTypeIds` - The context type identifiers in which to make process flow definition available.
        `comment` - The comment that is associated with the deployment action of the process flow definition.
        `activate` - Indicates whether to activate the process flow definition so that process flows can be created from it.
        `overwrite` - Indicates whether to overwrite the existing process flow definition with the new version.
      Returns:
        The deployed process flow definition.
      Throws:
        `ProcessFlowDeploymentException` - Thrown when there is an issue when deploying the process flow definition file.
        `ProcessDefinitionDeploymentException`

    - #### activateProcessDefinition

          ProcessDefinitionInfo activateProcessDefinition​(java.lang.String processDefinitionKey)
                                                   throws ProcessDefinitionStateException,
                                                          ProcessDefinitionNotFoundException

      Activates the latest deployed version of the process flow definition so that process flows can be created from it.
      Parameters:
        `processDefinitionKey` - The process flow definition key of the process flow definition.
      Returns:
        The activated process flow definition.
      Throws:
        `ProcessDefinitionStateException` - Thrown when the process flow definition is currently activated.
        `ProcessDefinitionNotFoundException` - Thrown when the process flow definition with the specified identifier is not found.

    - #### getProcessDefinitionById

          ProcessDefinitionInfo getProcessDefinitionById​(java.lang.String id)
                                                  throws ProcessDefinitionNotFoundException

      Gets the process flow definition with the specified unique identifier.
      Parameters:
        `id` - The identifier of the process flow definition.
      Returns:
        The process flow definition.
      Throws:
        `ProcessDefinitionNotFoundException` - Thrown when the process flow definition with the specified identifier is not found.

    - #### getProcessDefinitionByKey

          ProcessDefinitionInfo getProcessDefinitionByKey​(java.lang.String processDefinitionKey)
                                                   throws ProcessDefinitionNotFoundException

      Gets the latest deployed version of the process flow definition by the specified process flow definition key. Note the key is the identifier as specified in the process flow definition file.
      Parameters:
        `processDefinitionKey` - The key of the process flow definition.
      Returns:
        The latest deployed version.
      Throws:
        `ProcessDefinitionNotFoundException` - Thrown when the process flow definition with the specified identifier is not found.

    - #### suspendProcessDefinition

          ProcessDefinitionInfo suspendProcessDefinition​(java.lang.String processDefinitionKey)
                                                  throws ProcessDefinitionStateException,
                                                         ProcessDefinitionNotFoundException

      Suspends the latest deployed version of the process flow definition so that process flows cannot be created from it.
      Parameters:
        `processDefinitionKey` - The process flow definition key of the process flow definition.
      Returns:
        The suspended process flow definition.
      Throws:
        `ProcessDefinitionStateException` - Thrown when the process flow definition is currently suspended.
        `ProcessDefinitionNotFoundException` - Thrown when the process flow definition with the specified key is not found.

    - #### updateProcessDefinitionMapping

          ProcessDefinitionMapping updateProcessDefinitionMapping​(ProcessDefinitionMapping mapping)
                                                           throws ProcessDefinitionMappingUpdateException,
                                                                  ProcessDefinitionNotFoundException

      Updates the element mapping for the process definition based on the auto flow type. For example, if you have a process flow definition with a UserTask that you want to mapped to a TLF (or other auto flow type) attribute, such as attribute User Assignment 1, you would create or update that `FlowElementMapping`.
      See `getProcessDefinitionMappingMetadata()` for more information about which elements map to which TLF attributes.
      Parameters:
        `mapping` - The process flow definition mapping for the auto flow type.
      Returns:
        The updated process flow definition element mapping.
      Throws:
        `ProcessDefinitionMappingUpdateException` - Thrown when the process definition mapping is not updated.
        `ProcessDefinitionNotFoundException`

    - #### getProcessDefinitionMappingByType

          ProcessDefinitionMapping getProcessDefinitionMappingByType​(AutoFlowType type,
                                                                     java.lang.String processDefinitionKey)
                                                              throws ProcessDefinitionNotFoundException

      Gets the element mapping for the process flow definition based on the auto flow type. The mapping indicates whether the process flow definition is enabled for auto flow mappings and what element mappings exist, if any.

      See `getProcessDefinitionMappingMetadata()` for all process flow definition element attributes and metadata. It indicates the attributes that are available for each process flow definition element type and other `information`, such as attribute name, attribute `type`, and whether it supports multiple values. In addition, it indicates the auto flow type (such as TLF) attributes map to each element attribute. For example, if you have a process definition with a UserTask, the attribute, Assignee, could be mapped to a TLF attribute of the same type, such as User Assignment 1.

      For TLF attributes and metadata, see `StudyTlfService.getTlfAttributeMetadata()`.

      Parameters:
        `type` - The auto flow type.
        `processDefinitionKey` - The key of the process flow definition.
      Returns:
        The process definition mapping for the auto flow type.
      Throws:
        `ProcessDefinitionNotFoundException` - Thrown when the process flow definition does not exist.

    - #### getProcessDefinitionMappingMetadata

          java.util.List<ProcessDefinitionMappingMetadata> getProcessDefinitionMappingMetadata()

      Gets the process flow definition mapping metadata that describes the elements that can be mapped to what attribute types.
      Returns:
        The process flow definition mapping metadata.

    - #### getProcessDefinitionsMappedForAutoFlow

          java.util.List<ProcessDefinitionInfo> getProcessDefinitionsMappedForAutoFlow​(java.lang.String contextTypeId,
                                                                                       AutoFlowType autoFlowType,
                                                                                       boolean activeOnly)

      Gets the process flow definitions that are enabled and mapped for automatic process flow creation by the specified context type. Specifying null for context type gets process flow definitions across all of the context types.
      Parameters:
        `contextTypeId` - The context type in which to get the process flow definitions. Specifying null looks across all contexts.
        `autoFlowType` - The type from which a process flow can be automatically created.
        `activeOnly` - Indicates whether to return only active process flows.
      Returns:
        The list of process flow definitions that are mapped for automatic process flow creation.

    - #### getProcessDefinitionElements

          java.util.Set<FlowElementDefinition> getProcessDefinitionElements​(java.lang.String id)
                                                                     throws ProcessDefinitionNotFoundException

      Gets the elements of a process flow definition.
      Parameters:
        `id` - The identifier of a process flow definition.
      Returns:
        The process flow element definitions.
      Throws:
        `ProcessDefinitionNotFoundException` - Thrown when the process flow definition does not exist.