PX event handler for document management integration fails when attempting to attach files from network share. The script successfully creates document objects but file attachment operations throw FileNotFoundException, even though files exist and are accessible from the application server.
PX file attachment code:
IFile fileObj = (IFile) session.createObject(FileConstants.CLASS_FILE);
fileObj.setFile(new File(networkPath));
fileObj.save();
Exception occurs at setFile() call. We’ve verified file paths are correct and the Agile service account has read permissions on the network share. Files are accessible via manual attachment through Java Client. Is there a specific PX file path handling requirement or server permission configuration we’re missing?
Network paths in PX need to use UNC format on Windows (\\server\share\file.pdf) or absolute paths on Unix. Mapped drives don’t work because the service account session doesn’t have drive mappings. Also, verify the file vault configuration in Agile Admin - the PX might be trying to copy files to a vault location that the service account can’t write to.
We’re using UNC paths already. Checked the service account permissions and it has read/write on the network share. Could this be related to exception handling in the PX script? Should we be catching specific file access exceptions and handling them differently?
I’ll address all three focus areas comprehensively: PX file path handling, server permissions, and exception management for document management integration.
PX File Path Handling:
PX scripts require specific path handling for network file access. The key issues:
-
Path Format Requirements:
- Windows: Use UNC paths `\\server\share\folder\file.pdf
- Unix/Linux: Use absolute paths `/mnt/share/folder/file.pdf
- Avoid mapped drives (Z:, M:, etc.) - service context doesn’t have mappings
- Escape backslashes in Java strings properly
-
Corrected File Attachment Code:
String filePath = "\\\\fileserver\\docs\\document.pdf";
File sourceFile = new File(filePath);
if (sourceFile.exists() && sourceFile.canRead()) {
fileObj.checkInFile(sourceFile);
}
- File Vault Configuration:
Enable external file access in agile.properties:
px.allowExternalFileAccess=true
file.vault.allowNetworkPaths=true
Server Permissions:
Comprehensive permission requirements:
-
Application Server Service Account:
- Windows: Service account needs “Read” and “Read & Execute” on network share
- Verify using:
runas /user:DOMAIN\agile_service "cmd.exe" then test file access
- Grant permissions at share level AND NTFS level
- Unix: User running Agile must be in group with read access to mount point
-
File Vault Permissions:
- Service account needs write access to file vault root directory
- Default location: `AGILE_HOME/vault/default
- Verify with: Check agile.properties for
file.vault.location parameter
- Test vault write: Create test file manually as service account
-
Network Share Configuration:
- Disable SMB signing if causing authentication issues
- Ensure share is accessible from application server (test with
net use on Windows)
- Check firewall rules between app server and file server
- Verify DNS resolution of file server hostname
Exception Management:
Implement robust error handling in PX:
try {
IFile fileObj = (IFile) session.createObject(FileConstants.CLASS_FILE);
File sourceFile = new File(networkPath);
if (!sourceFile.exists()) {
throw new FileNotFoundException("Source file not found: " + networkPath);
}
fileObj.checkInFile(sourceFile);
fileObj.setValue(FileConstants.ATT_TITLE_BLOCK.NAME, sourceFile.getName());
fileObj.save();
} catch (FileNotFoundException e) {
session.getLogger().error("File access failed: " + e.getMessage());
throw new APIException("Unable to access file: " + networkPath);
} catch (IOException e) {
session.getLogger().error("IO error during file attachment", e);
throw new APIException("File transfer failed: " + e.getMessage());
} catch (APIException e) {
session.getLogger().error("Agile API error", e);
throw e;
}
Exception Handling Best Practices:
- Catch specific exceptions (FileNotFoundException, IOException) before generic Exception
- Log full stack traces for debugging: `session.getLogger().error(“message”, exception)
- Provide meaningful error messages that include file paths
- Don’t silently catch exceptions - either handle or rethrow
- Use session.getLogger() instead of System.out in PX
Troubleshooting Steps:
-
Enable PX debug logging in log4j.properties:
log4j.logger.com.agile.px=DEBUG
-
Test file access from server command line as service account:
# Windows
runas /user:DOMAIN\agile_service "type \\\\server\\share\\file.pdf"
# Unix
su - agile_user -c "cat /mnt/share/file.pdf"
-
Verify file vault write access:
File vaultTest = new File(vaultLocation, "test.txt");
vaultTest.createNewFile(); // Should succeed
4. Check PX execution context:
```java
session.getLogger().info("User: " + System.getProperty("user.name"));
session.getLogger().info("Working dir: " + System.getProperty("user.dir"));
Additional Recommendations:
- Copy files to vault location first, then attach from vault (more reliable)
- Implement retry logic for transient network failures
- Use FileInputStream for large files to avoid memory issues
- Consider async file processing for large documents
- Set appropriate file size limits in Agile configuration
The combination of correct path handling, proper server permissions, and robust exception management will resolve your PX file attachment issues. Focus first on verifying service account permissions using command-line testing before debugging the PX code itself.
Check your file vault security settings too. In 9.3.4, there’s a configuration parameter for allowing external file references in PX scripts. If this is disabled (default for security), PX can’t attach files from outside the configured vault locations. Look for ‘px.allowExternalFileAccess’ in agile.properties and set it to true if your security policy permits.