PowerShell Engine module in Bridge | Qntrl | Bridge | Online Help | Troubleshooting PowerShell tasks

PowerShell Engine

PowerShell Engine

In Bridge, the PowerShell Engine module is used to perform actions in any Windows machines in the client's network using PowerShell script.

Prerequisite
While creating Credentials, select the type Powershell and provide the User Name and Password of the machine where the Powershell script has to be executed. Click here to learn how to create a credential.

PowerShell Task Configuration  

Enabling PowerShell Remoting  

To run PowerShell tasks in the Windows environment using the Bridge agent, remoting must be enabled. There are two ways to enable this:

  • Remote Session (Default):

    • PowerShell remoting must be enabled by default for tasks to run successfully. The PowerShell engine task runs only on the local (Bridge-installed) machine, while other PowerShell task states work on both local and remote machines.

    • To enable remoting on the local host, use the command: Enable-PSRemoting. For more details, click here.

    • You can verify or manually enable remoting using the command: winrm quickconfig. For more information, click here.

  • Without Remote Session:

    • When executing PowerShell scripts directly without a remote session, this functionality is not available by default. You need to configure it manually.

    • Steps:

      1. Go to the Bridge installation folder: Bridge >> config >> powershell.properties.

      2. Add the following property: bridge.pwsh.script.execute.session=false.

      3. In Windows, open Services, locate Qntrl Bridge, and Restart.

    • After this configuration, PowerShell tasks will execute in a non-remote session.


The following section explains the tasks associated with the PowerShell Engine module and the request data for performing  tasks using Bridge.
To perform tasks using the PowerShell engine module requires stable network connectivity between the Windows machines.
Common keys in the Request data,
Keys
Description
  task_details
  A JSON object that contains the details of the task.
  activity_name
 Name of the activity performed in the PowerShell Engine module.
  execution_path
  (optional)
 Executable path of the installed PowerShell in the remote Windows machine.
  host
 Address of the Windows machine where the activity has to be performed.
  credential
 A JSON object that contains credentials of the machine in which the PowerShell script has to       be executed.
  name
 Name of the machine credential.
  task_name
 A system-defined name for the respective modules. 'pwsh_task' is the task name for         PowerShell Engine.


PowerShell Engine

This task is used to execute an attached PowerShell script file on the remote Windows machine.

Request data  

{ "task_details": { "activity_name": “file”, "execution_path": "<PATH OF EXECUTABLE FILE>", "host": "<HOST_NAME>", "script_name": "<name of the script file>" }, "credential": { "name": "<CREDENTIAL_NAME>" }, "task_name": "pwsh_task"
}
where,
script_name the name of the script file to be executed in a Windows machine.

Install WindowsApp

This task allows users to install apps on Windows machines using PowerShell.


Request data  

{
"task_details": {
"activity_name": "install_app",
"execution_path": "<PATH OF EXECUTABLE FILE>",
"host": "<HOST_NAME>",
"file_path": "<PATH FOR THE APP TO BE INSTALLED>",
"msi_file_name": "<NAME OF THE MSI FILE>"
},
"credential": {
"name": "<CREDENTIAL_NAME>"
},
"task_name": "pwsh_task"
}
where,
file_path - msi file path for the app to be installed on the Windows machine.
msi_file_name - msi file name of the app to be installed.

Uninstall WindowsApp

An existing app can be uninstalled from the Windows machine using this task.


Request data  

{
"task_details": {
"activity_name": "uninstall_app",
"execution_path": "<PATH OF EXECUTABLE FILE>",
"host": "<HOST_NAME>",
"app_name": "<APPLICATION_NAME>"
},
"credential": {
"name": "<CREDENTIAL_NAME>"
},
"task_name": "pwsh_task"
}
where,
app_name the name of the app to be uninstalled from the Windows machine.

Start Service

The task helps to start a service in the backend Windows server.

Request data  

{
"task_details": {
"activity_name": "start_service",
"execution_path": "<PATH OF EXECUTABLE FILE>",
"host": "<HOST_NAME>",
"service_name": "<NAME OF THE SERVICE>"
},
"credential": {
"name": "<CREDENTIAL_NAME>"
},
"task_name": "pwsh_task"
}
where,
service_name - the name of the service that has to be initiated in the Windows machine.

Stop Service

A service running in the backend Windows server can be stopped with this task.


Request data  

{
"task_details": {
"activity_name": "stop_service",
"execution_path": "<PATH OF EXECUTABLE FILE>",
"host": "<HOST_NAME>",
"service_name": "<NAME OF THE SERVICE>"
},
"credential": {
"name": "<CREDENTIAL_NAME>"
},
"task_name": "pwsh_task"
}
where,
service_name - the name of the service that has to be stopped in the Windows machine.

Restart WindowsServer

This task helps to restart a remote Windows machine using PowerShell.


Request data  

{
      "task_details": {
            "activity_name": "restart_server",
            "execution_path": "<PATH OF EXECUTABLE FILE>",
            "host": "<HOST_NAME>"
      },
      "credential": {
            "name": "<CREDENTIAL_NAME>"
      },
      "task_name": "pwsh_task"
}
Notes The restart task can be performed only when no users are logged in. If any users are logged in, the restart cannot be performed. 

Troubleshooting

1. PowerShell tasks are not executing on my Windows machine. What should I check? 

  • Ensure PowerShell Remoting is enabled on the target machine.
  • Run the given command in PowerShell: Enable-PSRemoting
  • Alternatively, verify remoting with winrm quickconfig

 

2. How to PowerShell scripts without using a remote session?

To execute scripts directly (non-remote mode):
  • Navigate to Bridge/config/powershell.properties

  • Add this line, bridge.pwsh.script.execute.session=false

  • Then restart the Qntrl Bridge service from Windows Services.

 

3. Why PowerShell task failsI even after providing the credentials?

There are a few common reasons this might happen. Check the following:

Is the credential name correct?  

Ensure the credential name matches the one provided in the request data.

Is the username formatted correctly?  

The format depends on whether the machine is part of a domain:

  • If not using a domain: <hostname>\<username>

  • If part of a domain: <domainname>\<username>

Is the password valid?  

  • Confirm that the password is correct.

  • Ensure the password is not expired or recently changed.

Test the Credentials in PowerShell  

Run the below command to manually verify if the username and password work:

Enter-PSSession -ComputerName localhost -Credential $cred

  • A login prompt will appear.

  • If the credentials are valid, you’ll enter the session.

  • If they’re invalid, PowerShell will show an error.


4. How to debug the PowerShell script execution failure? 

  • Verify the execution_path is correctly pointing to the installed PowerShell executable.

  • Ensure the script_name is correct and uploaded to the task.

  • Check if the host (target machine) is reachable from the Bridge-installed machine.

  • Review Bridge logs under <Bridge-Path>/logs/

 

5. PowerShell task returns an error when installing or uninstalling an app. What can I verify? 

  • Confirm the file_path and msi_file_name are correct and accessible from the target machine.

  • For uninstall, ensure app_name exactly matches the installed application’s name.

 

6. Restart server task doesn’t work. Why? 

  • Restart will fail if any user is currently logged in to the target machine.

  • Ensure the machine is idle before executing the restart_server activity.

 

7. Services are not starting or stopping as expected. What should I do? 

  • Make sure the service_name matches the actual service name (case-sensitive).

  • Check that the user in the credential has permission to manage Windows services.

 

8. How to resolve a host or credential error while running PowerShell Engine tasks.  

  • Confirm that the host IP/name is accessible from the Bridge server.

  • Verify network connectivity between Bridge and the target machine.

 

9. Bridge seems inactive or PowerShell task doesn’t trigger. What now? 

  • Restart the Qntrl Bridge service via Services (Windows) or command line.

  • Review logs under <Bridge-Path>/logs/ for any errors.

  • Check if PowerShell remoting or session settings are misconfigured.


    • Related Articles

    • PowerShell Task Engine

      These states are used to perform any actions in the Windows machines of a private network using PowerShell commands. There are six states available in the PowerShell Task Engine for performing different operations. PowerShell Engine Install ...
    • File Management

      Early Access File Management module is not enabled for all users. If you’d like to try it out, please email our support team for early access. The File Management module facilitates file transfer operations across various locations, providing ...
    • Credentials

      The Credential module provides a streamlined solution for storing and managing authentication credentials for databases, remote machines, and application servers. Organizations dealing with multiple databases or APIs often face repetitive credential ...
    • SSH Engine

      SSH Engine state is configured to connect to a client's machine or network and remotely execute commands or scripts on the client's Linux/UNIX operating system. Prerequisite Bridge must be installed and should be active. Learn how to install and ...
    • Install Bridge

      Follow the below step-by-step procedures to configure and use Bridge in Qntrl. Step 1: Download the Bridge agent Only one Bridge agent can be installed per machine. To download a bridge agent in Qntrl: Navigate to (settings), under Advanced click ...

    You are currently viewing the help articles of Qntrl 3.0. If you are still using our older version and require guidance with it, Click here.