How to execute a Windows batch (.bat) file from LotusScript, either on a users local machine or on a Domino server

Blogs
, , , ,
1

Description :
This Blog explains how to execute a Windows batch (.bat) file from LotusScript, either on a users local machine or on a Domino server. It also outlines the advantages of using LotusScript over running batch files directly from the Command Prompt.

This will help to automate or integrate external system tasks (file processing, backups, or report generation) with HCL Domino Designer applications by triggering Windows batch files from within a LotusScript routine.

You can Integrate Notes workflows with legacy Windows systems.

Running batch files from LotusScript is not just a technical trick it is a bridge between Notes/Domino and the Windows environment. Whether you are automating backups, data exports, or third-party integrations, this method gives you power and flexibility, right where your users already work. This is one of the cleanest ways to extend its capabilities without external schedulers or manual steps.

Procedure :
1. Determine the Execution Context

The location where the batch file runs depends on where the LotusScript executes:

Notes Client (Button, Action, or Agent):
This execution type runs on the user’s local PC. It executes directly on the user’s workstation.

Domino Server (Scheduled or Web Agent):
This execution type runs on the Domino server. It executes on the server machine.

Example 1 – Run Batch File on Local Machine (Shell Command)

Sub Initialize

Dim result As Long

Dim batchFile As String

batchFile = “C:\Files\Test.bat”

’ Run the batch file. The second parameter = 1 means show the window.
result = Shell(batchFile, 1)

If result = 0 Then
MsgBox “Failed to run the batch file.”
Else
MsgBox “Batch file launched successfully.”
End If
End Sub

Example 2 – Run Batch File Using WScript.Shell (More Control)
Sub Initialize
Dim ws As Variant
Dim comm As String
Dim returnCode As Long

Set ws = CreateObject(“WScript.Shell”)
comm = “C:\Files\script.bat”

’ Run and wait for completion (2nd param = 0 hides window, 3rd param = True waits)
returnCode = ws.Run(Chr(34) & Command & Chr(34), 0, True)

MsgBox "Batch file finished with code: " & returnCode
End Sub

Use when:
–You need to control visibility or wait for the batch process to complete before continuing.
–Tasks that require completion tracking or integration with Notes workflows.

Runs on: Either client or server depending on where the script executes.
If you need to hide the window, wait for completion, or capture return codes, prefer the WScript.Shell COM object is your friend.

LotusScript provides several benefits compared to executing tasks through the Command Prompt:

  • Automation:
    LotusScript can be embedded directly inside Notes forms, agents, or buttons, making it easy to automate tasks within Notes workflows. In contrast, Command Prompt actions require manual execution or external scheduling.
  • Integration:
    LotusScript can easily read and pass Notes data—such as document fields—directly to scripts or processes. The Command Prompt requires manual entry of parameters or additional scripting to achieve the same.
  • Security:
    LotusScript runs under Notes/Domino security controls such as ECL, ACL, and signed code, offering a secure execution environment. A Command Prompt window may expose sensitive commands or credentials to the user.
  • User Experience:
    LotusScript can show dialogs, progress indicators, or logs inside the Notes interface. Command Prompt output is limited to plain text and less user friendly.
  • Error Handling:
    LotusScript allows structured error handling and can process return codes or exceptions. Batch files require manual logic and error checks.
  • Centralized Management:
    LotusScript deployed through a Notes database or template updates all users automatically. Command Prompt scripts (.bat files) must be manually distributed, maintained, and executed by each user.

Security Considerations:

The Domino server must be configured to allow the use of Shell commands and COM objects. For agents running on the server, ensure that the agent signer has the appropriate permissions by adding their ID or group to the “Run unrestricted methods and operations” located under:**
Server → Current Server Document → Security → Programmability Restrictions.**

Note: Please note that shell commands in LotusScript do not wait for the called program to finish executing. The shell function returns immediately with a value of 1 as soon as the external program starts.

If your code requires the external program to complete before LotusScript continues—for example, when copying a file to a specific location that LotusScript must read from—then you will need to include a delay (Sleep) to allow enough time for the file operation to finish before LotusScript proceeds.

Sleep Statement syntax:

Advantages of Using LotusScript Over Command Prompt:

Best Practices:

  1. Always use full paths for scripts and files.

  2. Avoid hard-coding credentials or sensitive data.

  3. Log batch execution results back to a Notes document if needed.

  4. Use WScript.Shell for more stable and controlled execution.

  5. Test locally before deploying to a Domino server environment.

Troubleshooting

  • Nothing happens: Check file paths and verify the Notes client/server can access the file.

  • Permission denied: Confirm the script signer has “Run unrestricted methods” privilege.

  • Batch file hangs: Try using WScript.Shell with the third parameter set to True to wait for completion and capture the exit code.

References

Disclaimer: Please note that the testing conducted is intended as an example to guide your implementation. We recommend working closely with your development team to adapt and integrate the solution into your specific production environment. Product Support is not available for customizing solutions to fit individual customer setups.

1 Like