--- title: "Smart Extract Connector" slug: "smart-extract" updated: 2026-08-26T21:14:37Z published: 2026-08-26T21:14:37Z canonical: "docs.processmaker.com/smart-extract" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.processmaker.com/llms.txt > Use this file to discover all available pages before exploring further. # Smart Extract Connector ### Smart Extract Smart Extract is a built-in capability in ProcessMaker that enables automated document data extraction within a process. It allows documents (such as PDFs and images) to be processed automatically to identify and extract structured data points, such as fields and values, based on a configured model. Smart Extract is intended to reduce manual data entry and accelerate workflows that involve document processing. It can be added to a process directly from the Process Modeler and configured with a specific extraction model and parameters to control how documents are analyzed and parsed. Smart Extract automatically evaluates uploaded documents and applies defined extraction logic to identify relevant data. The results of the extraction are stored in Request variables and can be used in subsequent process steps, enabling automated decision-making and data-driven workflow progression without leaving the ProcessMaker Platform. ### Human-in-the-Loop (HITL) Validation Human-in-the-Loop (HITL) validation is an extension of Smart Extract that introduces a manual review step when automated extraction results do not meet predefined quality or validation criteria. Process Designers can define configurable rules that evaluate extraction confidence, completeness, or other conditions. When an extracted document fails to satisfy these rules, the process automatically routes the case to a human validation task rather than proceeding with potentially incorrect data . Operators assigned to HITL review tasks can then validate and correct the extracted data using a secure Smart Extract interface embedded directly within ProcessMaker. This approach balances the efficiency of automation with human oversight, ensuring that critical data is accurate before the process continues. Once the manual review is complete, the process resumes automatically based on the review outcome, with any corrections applied to the extracted data. > [!NOTE] > Smart Extract Environment Variables > > Smart Extract uses environment variables to configure the dashboard URL, API endpoint, authentication credentials, and Human-in-the-Loop behavior. These variables may be managed from the Environment Variables page by authorized users and are used by the Smart Extract integration at runtime. > > > > Values configured in the UI take precedence over values defined in the `.env` file. If a variable is removed from the UI, Smart Extract falls back to the value defined in `.env`. Updates apply immediately and do not require a service restart or deployment. > > > > For more information about Environment Variables, see [Default Environment Variables](/v1/docs/environment-variables#default-environment-variables). --- ## Add an Smart Extract Connector to the Process Model **Permissions** Your user account or group membership must have the following permissions to configure an Smart Extract connector to the Process model unless your user account has the **Make this user a Super Admin** setting selected: - Processes: Edit Processes - Processes: View Processes See the [Process](/v1/docs/permission-descriptions-for-users-and-groups#processes) permissions or ask your Administrator for assistance. Add an Smart Extract connector from one of the following locations in Process Modeler: - **Object Panel:** Located to the left of the Process Modeler canvas, the Object Panel contains various process model objects. - **Object Bar:** Located at the bottom of the Process Modeler canvas, the Object Bar contains [pinned](/v1/docs/process-modeler#pin-and-unpin-objects) Process model objects for quick access. Add from the Object panelAdd from the Object bar Follow these steps to add an Smart Extract connector from the Object panel to the Process model: 1. Ensure that the Object panel is visible on the left. If not, click the **Add** icon ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/fb2ceeb2-8ca4-49a7-a962-c3be2fd0aa6f.png) from the Object bar at the bottom. 2. Click the Smart Extract object ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/Smart Extract Icon.png) from the Object panel to select it. 3. Click the location in the Process model to place this connector. Follow these guidelines when placing this object: - If your process has a Pool object, the Smart Extract object cannot be placed outside of the Pool. - To place this object between two existing objects, follow [these instructions](/v1/docs/sequence-flow-element#place-an-object-between-two-process-model-objects-already-connected-with-a-sequence-flow-element). ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/Smart Extract Object Modeler.png) Follow these steps to add an Smart Extract connector from the Object bar to the Process model: 1. Ensure that the Smart Extract object ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/Smart Extract Object Pinned.png) is pinned to the Object bar. If not, see [instructions to pin it](/v1/docs/process-modeler#pin-and-unpin-objects) it. 2. In the Object bar at the bottom center, click the object's icon. 3. Click the location in the Process model to place this element. Follow these guidelines when placing this object: - If your process has a Pool object, the Smart Extract object cannot be placed outside of the Pool. - To place this object between two existing objects, follow [these instructions](/v1/docs/sequence-flow-element#place-an-object-between-two-process-model-objects-already-connected-with-a-sequence-flow-element). ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/Smart Extract Object Modeler.png) **Add boundary events** After adding an object to a process, consider adding the following events to handle exceptions: - [Boundary Timer Event](/v1/docs/boundary-timer-event) element - [Boundary Error Event](/v1/docs/boundary-error-event) element - [Boundary Signal Event](/v1/docs/boundary-signal-event) element - [Boundary Conditional Event](/v1/docs/boundary-conditional-event) element - [Boundary Message Event](/v1/docs/boundary-message-event) element **Adjust location and appearance** - [Move a Process Model Object.](/v1/docs/process-modeler#move-process-model-objects) - [Connect Two Process Model Objects with a Sequence Flow Element.](/v1/docs/sequence-flow-element#connect-two-process-model-objects-with-a-sequence-flow-element) - [Customize the Appearance of a Process Model Object.](/v1/docs/customize-the-appearance-of-a-process-model-object) - [Copy Process Model Objects into the Clipboard.](/v1/docs/process-modeler#copy-process-model-objects-into-the-clipboard) - [Clone Process Model Objects Without the Clipboard.](/v1/docs/process-modeler#clone-process-model-objects) - [Delete Process Model Objects.](/v1/docs/process-modeler#delete-process-model-objects) --- ## Settings The Smart Extract connector has the following panels that contain settings: - [**Configuration**](/v1/docs/smart-extract#configuration-panel-settings) panel - [**Loop Activity**](/v1/docs/smart-extract#loop-activity-panel-settings) panel - [**HITL Assignee**](/v1/docs/smart-extract#hitl-assignee-panel-settings) panel - [**Advanced**](/v1/docs/smart-extract#advanced-panel-settings) panel --- ### Configuration Panel Settings The Smart Extract connector has multiple settings in the **Configuration** panel. #### Edit the Connector Name A connector name is a human-readable reference for a Process model control. Process Modeler automatically assigns the name of a Process model connector with its connector type. However, a connector's name can be changed. Follow these steps to edit the name for an Smart Extract connector: 1. Select the Smart Extract connector from the Process model. 2. Click the **Show Configuration** button ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/67f55ae2-1872-49af-819e-ef4f680248e2.png) in the upper right of the Process Modeler canvas to view the **Configuration** panel. 3. In the **Name** setting, edit the selected connector's name and then press **Enter**. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/Smart Extract Name.png) #### Enter the Request Variable Containing the File(s) to be Sent During a Request, an Smart Extract connector references a [Request variable](/v1/docs/request-variable) that stores the documents for processing. This Request variable may be linked to a [File Upload](/v1/docs/file-upload-control) control, where the documents were uploaded during a Task. Follow these steps to enter the name of the Request variable that stores the documents to be processed by this Smart Extract connector: 1. Expand the **Configuration** panel if it is not presently expanded, and then locate the **Variable Name** setting. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/Smart Extract - Request Variable.png) 2. In the **Variable Name** setting, enter the Request variable name that stores the documents for processing without using [mustache syntax](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/mustache.5(5).html), then press **Enter**. 3. Otherwise, instead of entering a variable name, enable **Loop Activity** to use a custom array configured in the [multi-instance settings](/v1/docs/smart-extract#loop-activity-panel-settings). #### Configure the Smart Extract Model The **Smart Extract** connector includes configuration options that allow Process Designers to define how documents are extracted, validated, and routed for human review when necessary. Follow these steps to use the appropriate extraction model: 1. Expand the **Configuration** panel if it is not presently expanded, and then locate the **Select Model Type** setting. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/Smart Extract Model.png) 2. If not selected **Use Request Variable**, do the following: 1. In the **Select Model Type**, select the extraction model type. 2. In the **Model**, select the Smart Extract model to apply. 3. Select the **Use Request Variable** option, and enter a request variable that contains a reference to the model type and the Smart Extract model in **Select Model Type** and **Model**. Reference this Request variable without using mustache syntax. 4. In **Select Validation**, select a validation rule to Define the condition used to evaluate extraction confidence and completeness. --- ### Loop Activity Panel Settings Use the **Loop** Activity panel settings to specify how to run multiple instances of this object. The following loop modes are available: #### No Loop Mode Select the **No Loop Mode** option to perform this object's function only once. Follow these steps to specify characteristics to perform multiple instances of the object:‌ 1. Select the object from the Process model. Panels to configure this object display. 2. Expand the **Loop Activity** panel. By default, the **Loop Mode** setting is set to **No Loop Mode** and the function is performed only once. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/image(135).png) #### Loop Select the Loop option to sequentially repeat this object's function multiple times until an exit condition is `True`. This is useful when a function should be performed multiple times with the same set of data, such as, processing a credit card payment. This loop mode has the following characteristics: - The object's function is repeated until the exit condition is `True `or the maximum iterations limit is reached. - At any given time, only one instance of the object is active. The subsequent instance does not begin until the current instance completes. - The same exit condition evaluates at the end of each instance; however, value(s) of the Request variable(s) used in the exit condition can change during an instance resulting in the exit condition to eventually evaluate as `True`. - If any one instance of that function does not complete, workflow pauses. - All active instances are terminated if an interrupting boundary-type event object triggers. - An object configured in this mode shows the **Loop** icon ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/image(137).png)in Process Modeler. Follow these steps to specify characteristics to perform multiple instances of the object:‌ 1. Select the object from the Process model in which to specify multiple instance characteristics. Panels to configure this object display. 2. Expand the **Loop Activity** panel to display the **Loop Mode** Setting. 3. From the **Loop Mode** setting, select the **Loop** option. The settings for this loop mode display: ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/image(136).png) 4. In the **Maximum Iterations** setting, enter an integer value representing the maximum number of times this Task should be performed. 5. In the **Exit Condition** setting, enter a condition in FEEL syntax. When this condition is True the loop activity is halted. #### Multi-instance(Parallel) Select the **Multi-instance (Parallel)** option to perform this object's Task multiple times in parallel a fixed number of times. This is useful when performing any action in bulk, such as sending an email to several people. This loop mode has the following characteristics: - Instances of the object are governed by the size of an array-type Request variable where a new instance is created for each item in this variable. For example, an array with 10 items will create 10 parallel instances of this function that each contains data from its respective array index. - All instances begin simultaneously when this object triggers; however, they perform their function independently of each other. - The function as a whole completes when all instances are complete. - The output from each instance can either be saved in the source Request variable or a new array-type Request variable. - All active instances terminate if an interrupting boundary-type event object triggers. - A object configured in this mode shows the Multi-instance (Parallel) icon in Process Modeler. Follow these steps to specify characteristics to perform multiple instances of the object:‌ 1. Select the object from the Process model in which to specify multiple instance characteristics. Panels to configure this object display. 2. Expand the **Loop Activity** panel to display the **Loop Mode** Setting. 3. From the Loop Mode setting, select the **Multi-instance (Parallel)** option. The settings for this loop mode display: ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/image(138).png) 4. In the **Request Variable Array** setting, enter the name of an array-type Request variable. The size of this array will determine how many times this loop iterates. 5. In the **Output Data Variable** setting, enter the name of an array-type Request variable in which to store the results of all instances. Each instance of the loop saves to a separate JSON object within the array of the specified Request variable. If the **Output Data Variable** setting is not configured, then the output data replaces the source data in the **Request Variable Array.** #### Multi-instance(Sequential) Select the Multi-instance (Sequential) option to perform this object's function multiple times sequentially a fixed number of times or until an exit condition is True. This is useful when sequentially repeating a function multiple times but with a different set of data each time. This loop mode has the following characteristics: - Instances of the function are governed by the size an array-type Request variable where a new instance is created for each item in this variable. For example, an array with 10 items will create 10 parallel instances of this function that each contains data from its respect array index. - At any given time, only one instance of the function is active. The subsequent instance does not begin until the current instance completes. - At the end of each instance an exit condition evaluates and the loop activity halts if the exit condition is True. - The function as a whole completes when all instances are complete. - The output from each instance can either be saved in the source Request variable or a new array-type Request variable. - All active instances terminate if an interrupting boundary-type event object triggers. - A object configured in this mode shows the Multi-instance (Sequential) iconin Process Modeler. Follow these steps to specify characteristics to perform multiple instances of the object:‌ 1. Select the object from the Process model in which to specify multiple instance characteristics. Panels to configure this object display. 2. Expand the **Loop Activity** panel to display the **Loop Mode** Setting. 3. From the Loop Mode setting, select the **Multi-instance (Sequential)** option. The settings for this loop mode display: ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/image(139).png) 4. In the **Request Variable Array** setting, enter the name of an array-type Request variable. The size of this array will determine how many times this loop iterates. 5. In the **Exit Condition** setting, enter a condition in FEEL syntax. When this condition is True the loop activity is halted. 6. In the **Output Data Variable** setting, enter the name of an array-type Request variable in which to store the results of all instances. Each instance of the loop saves to a separate JSON object within the array of the specified Request variable. If the **Output Data Variable** setting is not configured, then the output data replaces the source data in the **Request Variable Array**. --- ### HITL Assignee Panel Settings #### Configure Human-in-the-Loop Validation Enable Human-in-the-Loop (HITL) behavior to introduce a manual review step when validation rules fail. 1. Click the **Human in the Loop** toggle to enable the behavior. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/HITL Assignee.png) 2. From the **Assignment Type** drop-down menu, select one of the following options: - **Users / Groups:** Select this option to assign the connector to a specified user or to a group member. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/HITL 1.png) From the **Assigned Users/Groups** drop-down menu, select one or more users and/or groups for this connector. The connector is assigned following this protocol: - **One user:** The connector is assigned to the selected user. - **One or more users and/or group(s):** The connector is assigned randomly to one of those users or group members. The exception is if the **Self Service** toggle key is enabled, then the connector remains unassigned, in a queue, for one of those users to [self-assign from the Self Service page](/v1/docs/self-assign-tasks-from-a-queue). - **Previous Task Assignee:** Select this option to assign the connector to the assignee of the previous task. - **Request Starter:** Select this option to assign the connector to the Request starter. This is the default option. - **Process Variable:** Select this option to assign the connector determined by the value of a Request variable. The entered variable(s) may be one or both of the following: - **Variable Name (Users):** In this setting, enter the Request variable that contains the user ID(s) for one or more users. If more than one user ID is included the Request variable's value, then the connector is assigned randomly to one of those users. The exception is if the **Self Service** toggle key is enabled, then the connector remains unassigned, in a queue, for one of those users to [self-assign from the Self Service page](/v1/docs/self-assign-tasks-from-a-queue). - **Variable Name (Groups):** In this setting, enter the Request variable that contains a group ID(s). The connector is assigned randomly to one of the group members. The exception is if the **Self Service** toggle key is enabled, then the connector remains unassigned, in a queue, for one of those users to [self-assign from the Self Service page](/v1/docs/self-assign-tasks-from-a-queue). ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/HITL 2.png) - **Rule Expression:** Select this option to assign the connector's assignee using one or more rules. The rule expressions follow the Friendly Enough Expression Language (FEEL) syntax described in [Expression Syntax Components](/v1/docs/feel-expression-syntax#expression-syntax-components). ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/HITL 3.png) Each rule can only have one expression, but by using logical operators multiple conditions can be specified in that expression. You may use multiple rules to better confine the condition(s), and you may use [Magic Variables](/v1/docs/magic-variables) in your expression. To add an expression, click the add ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/0a84f89f-9a9f-4007-91c9-6fb9ac19f6f6.png) button. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/1cac35ec-1486-4c91-8442-ffd042e8ed71.png) Follow these steps to define an expression: 1. In the **FEEL** **Expression** setting, enter or edit the expression using the syntax components described in [Expression Syntax Components](/v1/docs/feel-expression-syntax#expression-syntax-components), and then press **Enter**. 2. From the **Assign to User/Group** drop-down menu, select the user or group to assign the connector to when the **FEEL Expression** evaluates to True. 3. From the **Default Assignment** drop-down menu, select a user or group to assign that connector to if none of the expressions evaluate as True. - **Process Manager:** Select **Process Manager** to assign the connector to the Process Manager. [Ensure to configure the Process Manager for this Process](/v1/docs/configure-general-process-settings). 3. In the **Assignment Options**, do the following: ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/Assignment Options HITL.png) 1. Enable the **Self Service** toggle to allow group members to [self-assign the connector from a queue](/v1/docs/self-assign-tasks-from-a-queue). This option is only available if the **Assignment Type** is set to Users / Groups, Process Variable, or Rule Expression. 2. Enable the **Lock User Assignment** toggle to ensure the connector is reassigned to the same user if the workflow returns to it. This is useful when the original assignee may need to clarify or update information they previously submitted. 3. Enable the **Allow Reassignment** toggle key to allow the connector assignee to reassign the connector if necessary. If the **Allow Reassignment** option is enabled, the **Reassign** button displays in the connector summary to allow for connector reassignment. 4. In the **Assignee Permissions**, do the following: 1. Enable the **Escalate to Manager** toggle key to assign that connector to the manager of the connector assignee. An Administrator can configure the manager for each user in their [user account](/v1/docs/edit-a-user-account#edit-user-settings). 2. Enable the **Allow Manager Escalation** toggle key to automatically reassign this connector to the connector assignee's manager. An Administrator can configure the manager for each user in their [user account](/v1/docs/edit-a-user-account#edit-user-settings). > [!NOTE] > If you enable the **Allow Reassignment** option, make sure the connector is assigned to multiple users or to a group. Otherwise, even though the **Reassign** button will appear in the connector summary, the assignee will have no available users to reassign the connector to. --- ### Advanced Panel Settings #### Edit the Node's Identifier Value A Process node represents a component of a Process model, whether that is a BPMN element or a [connector](/v1/docs/connectors#overview). Process Modeler automatically assigns a unique value to each Process node added to a Process model. A Process node's identifier value can be changed if it is unique to all other nodes in the Process model, including the Process model's identifier value. > [!WARNING] > All identifier values for all nodes in the Process model must be unique. Follow these steps to edit the identifier value for an Smart Extract connector: 1. Select the Smart Extract connector from the Process model in which to edit its identifier value. 2. Ensure that the **Configuration** panel displays. If not, [show it](/v1/docs/show-configuration-settings-for-a-process-model-object). Panels to configure this element display. 3. Expand the **Advanced** panel if it is not presently expanded. The **Node Identifier** setting displays. This is a required setting. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/04017483-a2f5-40b6-b7a7-522585c61021.png) 4. In the **Node Identifier** setting, edit the Smart Extract connector's identifier to a unique value from all nodes in the Process model and then press **Enter**.