Component: File manager

 Show all Hide all

Provides functionality to manipulate the contents of an endpoint by performing different actions. An action represents an operation such as copying a file or listing the contents of a directory. Supported endpoints are the local filesystem, network filesystems (using UNC) and FTP servers.

Details

Action queue

The component is based on a queue where actions are enqueued and then performed one at a time according to FIFO priority. The component starts by making a 'Get initial actions' call to retrieve the first set of actions to add to the queue. It then performs the first action in the queue after having made a 'Get extra information' call if the action requires extra information. After the action has been performed an 'Action performed' call is made to report whether the action was successful or not. The 'Action performed' call can optionally return new actions that are added to the queue. When the queue is empty the component makes a 'Finished' call and then terminates. To prevent the component from getting stuck in an infinite loop new actions can only be returned a finite number of times.

Paths

Most actions require a path to identify the entry on which to operate. The path is obtained by combining a base path specified on the endpoint with a path specified on the action. As an example, if the endpoint uses 'c:/foo' as base path and an action specifies '/bar' the combined path is 'c:/foo/bar'. It is not permitted to specify an action path that escapes the base path, i.e '/../bar' is not allowed.

The format for the base path depends on the type of endpoint. Filesystem endpoints supports Windows style path ('c:/foo') and UNC ('\server\resource'). Long UNC, also known as UNCW, is not supported. The FTP endpoint uses unix style paths, i.e '/foo/'. Filesystem endpoints must specify a base path whereas ftp endpoints use '/' by default.

The format for the action is unix-style and it must adhere to the following requirements:

  1. '.' is not allowed. '..' is allowed as long as it does not escape the root.
  2. Wildcard characters '?' and '*' are not allowed. Depending on the endpoint other characters might be forbidden as well.
  3. Unless otherwise stated the path must be absolute, i.e 'foo/bar.txt' is not valid but '/foo/bar.txt' is.

Extra parameters

When specifying an action it is allowed to include additional columns that are not used to control the action. These columns are transformed into parameters known as 'Extra parameters' where each column corresponds to an extra parameter. The name, datatype and value of the parameters equals the name, datatype and value of the column. All NULL values are ignored, i.e. they do not generate an extra parameter with NULL as its value. These extra parameters are set when making the 'Get extra information' and 'Action performed' call for the corresponding action.

It is recommended that the extra parameter's value are kept reasonably small, i.e. large BLOBs should not be passed as extra parameters. Some names are reserved and hence not allowed to be used as extra parameters. The restricted names are the names of all parameters used by the component and the following additional names: 'Md5hash', 'Sha1hash', 'Timeout', 'Content', 'Zip', 'Unzip', 'Compress' and 'Decompress'.

SQL

SQL Call: Get initial actions (mandatory)

Retrieve the initial actions to perform.
Supports custom errors: No
May modify database: Yes

Parameters:

@Action mandatory string
Possible value Description
Init The component requests initial actions to perform.

Resultset: EndPoints

Specifies the endpoint(s) on which actions are performed.
Repeat mode: repeated zero or one time
Row count: zero or more rows

Columns:

Address mandatory string
Network address to use, can either be a hostname or an IP-address. Only applicable for FTP and FTPS
BasePath mandatory string
The base path to use for the end point. This column is mandatory for filesystem endpoints and optional for FTP endpoints. For more information about base path and supported formats please see the component documentation.
EndPointId mandatory int
Id that is used to reference this endpoint in an action.
EndPointType mandatory string
The type of endpoint.
Possible value Description
Filesystem The local filesystem or a network filesystem (using UNC-paths i.e '\\server/path/to/object')
FTP FTP (File Transfer Protocol)
FTPS FTP using explicit SSL.
Password mandatory string
The password used for authentication. Only applicable for FTP and FTPS.
Port optional int
Network port to use. Only applicable for FTP and FTPS. The default port is 21 for FTP and 990 for FTPS.
UsePassiveMode optional bit
Specifies whether passive mode should be used when establishing a data connection with the server. The default is to use passive mode. Only applicable for FTP and FTPS.
Username mandatory string
The username used for authentication. Only applicable for FTP and FTPS.

Resultset: Actions

Specifies the actions that should be performed. The actions are added to a queue and executed in the order that they are returned.
Repeat mode: repeated zero or more times
Row count: zero or more rows

Columns:

<XXX> optional string
Values in columns to the right of the BeginExtraParams column are passed as parameters to the procedure after the action has been executed.
Action mandatory string
The type of action.
Possible value Description
CallProcedure Make a call to the procedure without performing an action.
ClearQueue A special action that removes all actions from the queue. The removal is performed directly and no 'Action performed' call is made. It is considered an error if this action is not the first in a resultset.
CopyDirectory Copies a directory. The 'SourcePath' column specifies the directory to copy. The 'TargetPath' column specifies the target directory for the directory. The copied directory will have the same name as the source directory. As an example, if SourcePath is '/bar/' and TargetPath is '/foo' then the copied directory will be '/foo/bar/'.
CopyFile Copies a file. The 'SourcePath' column specifies the source file and the 'TargetPath' column specifies the target directory. The copied file will have the same name as the source file.
DeleteDirectory Deletes a directory. The 'SourcePath' column specifies the directory that should be deleted. It is considered an error if the directory is not empty and the action is not performed recursively.
DeleteFile Deletes a file. The 'SourcePath' column specifies the file that should be deleted.
DirectoryExists Checks whether a directory exists or not. The 'SourcePath' column specifies the path to check. This action will return false if a file with the specified path exists.
FileExists Checks whether a file exists or not. The 'SourcePath' column specifies the path to check. This action will return false if a directory with the specified path exists.
Finish When executed the component performs a 'Finished' call and then terminates. It is considered an error if this action is not the last in a resultset.
HashFile Calculates the hash of a file's content. The 'SourcePath' column specifies the file.
List Lists all entries in a directory. The 'SourcePath'-column specifies the directory.

NOTE! On IIS FTP servers, SourcePath must be '/'. To get the contents of a specific directory, do a recursive listing and filter on the ParentDirectory column of the #List temp table.
MoveDirectory Moves a directory. The 'SourcePath' column specifies the directory to move. The 'TargetPath' column specifies the target directory for the moved directory. The moved directory will have the same name as the source directory. As an example, if SourcePath is '/bar/' and TargetPath is '/foo' then the moved directory will be '/foo/bar/'.
MoveFile Moves a file. The 'SourcePath' column specifies the source file and the 'TargetPath' column specifies the target directory. The moved file will keep its name.
ReadFile Reads the content of a file. The 'SourcePath' column specifies the file.
RenameDirectory Renames a directory. The 'SourcePath' column specifies the directory to rename and the 'TargetPath' column specifies the new name of the directory excluding path. The renamed directory will remain in its original directory.
RenameFile Renames a file. The 'SourcePath' column specifies the source file and the 'TargetPath' column specifies the new name of the file excluding path. The file will remain in its original directory.
WriteFile Writes data to a file. The 'TargetPath' column specifies the file that the data should be written to.
BeginExtraParams optional int
Marker that indicates that all columns with a higher ordinal than this column will be passed as parameters to the procedure after the action has been executed. This column must only contain NULL.
CreateDirectory optional bit
Specifies if any missing directories should be created. Default is to not create any missing directories. Applicable for actions CopyDirectory, CopyFile, CreateDirectory, MoveFile, MoveDirectory and WriteFile.
EndPointIdSource mandatory int
Id of the endpoint used as source. Applicable for actions CopyDirectory, CopyFile, DeleteDirectory, DeleteFile, DirectoryExists, FileExists, HashFile, List, MoveDirectory, MoveFile, ReadFile, RenameDirectory and RenameFile.
EndPointIdTarget mandatory int
Id of the endpoint used as target. Applicable for actions CreateDirectory, CopyDirectory, CopyFile, MoveDirectory, MoveFile and WriteFile.
HashAlgorithm mandatory string
Algorithm to use when calculating the hash value. Only applicable for action HashFile.
Possible value Description
Md5 The MD5 algorithm.
Sha1 The SHA1 algorithm.
NewName optional string
For CopyFile, MoveFile, CopyDirectory and MoveDirectory optionally renames the copied/moved object. Leave as null to retain original name.

For RenameFile and RenameDirectory either NewName or TargetPath must be specified and they are effectively aliases for each other.
Overwrite optional bit
Specifies if any existing items should be overwritten. Default is to not overwrite existing items. Applicable for actions CopyFile, MoveFile and WriteFile.
Recursive optional bit
Specifies whether the action should be performed recursively. Default is to not perform the action recursively. Applicable for actions List (list content of all subdirectories) and DeleteDirectory (remove non-empty directories).
SourcePath mandatory string
The path to the source entity. Applicable for actions CopyDirectory, CopyFile, DeleteDirectory, DeleteFile, DirectoryExists, FileExists, HashFile, List, MoveDirectory, MoveFile, ReadFile, RenameDirectory and RenameFile.
TargetPath mandatory string
The path to the target entity. Applicable for actions CreateDirectory, CopyDirectory, CopyFile, MoveDirectory, MoveFile, RenameDirectory, RenameFile and WriteFile.

SQL Call: Get extra information (mandatory)

Call made to retrieve additional information if it is required to perform the action. The only action that requires extra information is 'WriteFile'.
Supports custom errors: No
May modify database: Yes

Parameters:

@{Extra parameters} mandatory string
All extra parameters that were provided when specifying the action. The name of the parameter corresponds to the column name.
@Action mandatory string
The action that requires extra information.
@ExtraInformation mandatory bit
Possible value Description
1 The component requires extra information to perform the action.

Resultset: Retrieve file content

Contains the file content. Only applicable for action WriteFile.
Repeat mode: repeated exactly once
Row count: exactly one row

Columns:

<column with ordinal 1> mandatory binary
The file content.

SQL Call: Action performed (mandatory)

Call made after an action has been performed.
Supports custom errors: No
May modify database: Yes

Parameters:

@{Extra parameters} mandatory string
All extra parameters that were provided when specifying the action. The name of the parameter corresponds to the column name.
@Action mandatory string
The action that was performed.
@ErrorCode mandatory int
An error code that can be used to determine whether the action was performed successfully or not.
Possible value Description
0 The action was performed successfully.
-1 An unknown error occurred, see @ErrorMessage for details.
101 Failed to open a data connection.
11 The source directory could not be found or access is denied.
111 Invalid SSL certificate.
12 The target directory could not be found or access is denied.
13 The target directory already exists.
14 The source directory is not empty.
21 The source file could not be found or access is denied.
22 The target file already exists.
31 The specified hostname could not be resolved.
32 The endpoint is not responding.
41 Authentication with end point failed. Verify that the supplied username / password are correct.
5 The specified path is invalid.
6 The base path does not exist.
@ErrorMessage mandatory string
Contains a human-readable message if an error has occurred. If the action was performed successfully then thie parameter is not set.
@Exists mandatory bit
Only set for the actions 'FileExists' and 'DirectoryExists'.
Possible value Description
0 The object does not exist.
1 The object exists.
@FileImage mandatory binary
Content of the read file, only set for action 'ReadFile'.
@Hash mandatory binary
The hash value. Only set for action 'HashFile'.
@SourcePath mandatory string
The path used as source for the action. The value is only intended to be used for logging and hence the format is not guaranteed and it must not be used as a path for further actions. Parameter is NULL if the action does not use a source path.
@TargetPath mandatory string
The path used as target for the action. The value is only intended to be used for logging and hence the format is not guaranteed and it must not be used as a path for further actions. Parameter is NULL if the action does not use a target path.

Resultset: #List

Temporary table provided by the component if the action performed is 'List'. Contains metadata about the entries found in the directory (and subdirectories if the action was performed recursively).
Repeat mode: repeated exactly once
Row count: zero or one row

Columns:

DatetimeCreated mandatory datetime
The entry's creation date. Is NULL for FTP and FTPS.
DatetimeModified mandatory datetime
The entry's last modified date. Is NULL for FTP and FTPS.
IsDirectory mandatory bit
A value indicating whether the entry is a directory or not.
Possible value Description
0 The entry is a file.
1 The entry is a directory.
IsHidden mandatory bit
A value indicating whether the entry is hidden or not.
Possible value Description
0 The entry is not marked as hidden.
1 The entry is marked as hidden.
NULL Unknown, no information provided by the endpoint.
IsReadOnly mandatory bit
A value indicating whether the entry is readonly.
Possible value Description
0 The entry is not marked as readonly.
1 The entry is marked as readonly.
NULL Unknown, no information provided by the endpoint.
Name mandatory string
Name of the entry.
ParentDirectory mandatory string
Path to the directory containing the entry. The path is always absolute in relation to the specified end point. '/' is used as directory separator and it always ends with an '/'. An example of a reported path is '/foo/bar/'.
SizeInBytes mandatory bigint
The entry's size (in bytes) if the entry is a file, otherwise NULL.

Resultset: EndPoints

Specifies the endpoint(s) on which actions are performed.
Repeat mode: repeated zero or one time
Row count: zero or more rows

Columns:

Address mandatory string
Network address to use, can either be a hostname or an IP-address. Only applicable for FTP and FTPS
BasePath mandatory string
The base path to use for the end point. This column is mandatory for filesystem endpoints and optional for FTP endpoints. For more information about base path and supported formats please see the component documentation.
EndPointId mandatory int
Id that is used to reference this endpoint in an action.
EndPointType mandatory string
The type of endpoint.
Possible value Description
Filesystem The local filesystem or a network filesystem (using UNC-paths i.e '\\server/path/to/object')
FTP FTP (File Transfer Protocol)
FTPS FTP using explicit SSL.
Password mandatory string
The password used for authentication. Only applicable for FTP and FTPS.
Port optional int
Network port to use. Only applicable for FTP and FTPS. The default port is 21 for FTP and 990 for FTPS.
UsePassiveMode optional bit
Specifies whether passive mode should be used when establishing a data connection with the server. The default is to use passive mode. Only applicable for FTP and FTPS.
Username mandatory string
The username used for authentication. Only applicable for FTP and FTPS.

Resultset: Actions

Specifies the actions that should be performed. The actions are added to a queue and executed in the order that they are returned.
Repeat mode: repeated zero or more times
Row count: zero or more rows

Columns:

<XXX> optional string
Values in columns to the right of the BeginExtraParams column are passed as parameters to the procedure after the action has been executed.
Action mandatory string
The type of action.
Possible value Description
CallProcedure Make a call to the procedure without performing an action.
ClearQueue A special action that removes all actions from the queue. The removal is performed directly and no 'Action performed' call is made. It is considered an error if this action is not the first in a resultset.
CopyDirectory Copies a directory. The 'SourcePath' column specifies the directory to copy. The 'TargetPath' column specifies the target directory for the directory. The copied directory will have the same name as the source directory. As an example, if SourcePath is '/bar/' and TargetPath is '/foo' then the copied directory will be '/foo/bar/'.
CopyFile Copies a file. The 'SourcePath' column specifies the source file and the 'TargetPath' column specifies the target directory. The copied file will have the same name as the source file.
DeleteDirectory Deletes a directory. The 'SourcePath' column specifies the directory that should be deleted. It is considered an error if the directory is not empty and the action is not performed recursively.
DeleteFile Deletes a file. The 'SourcePath' column specifies the file that should be deleted.
DirectoryExists Checks whether a directory exists or not. The 'SourcePath' column specifies the path to check. This action will return false if a file with the specified path exists.
FileExists Checks whether a file exists or not. The 'SourcePath' column specifies the path to check. This action will return false if a directory with the specified path exists.
Finish When executed the component performs a 'Finished' call and then terminates. It is considered an error if this action is not the last in a resultset.
HashFile Calculates the hash of a file's content. The 'SourcePath' column specifies the file.
List Lists all entries in a directory. The 'SourcePath'-column specifies the directory.

NOTE! On IIS FTP servers, SourcePath must be '/'. To get the contents of a specific directory, do a recursive listing and filter on the ParentDirectory column of the #List temp table.
MoveDirectory Moves a directory. The 'SourcePath' column specifies the directory to move. The 'TargetPath' column specifies the target directory for the moved directory. The moved directory will have the same name as the source directory. As an example, if SourcePath is '/bar/' and TargetPath is '/foo' then the moved directory will be '/foo/bar/'.
MoveFile Moves a file. The 'SourcePath' column specifies the source file and the 'TargetPath' column specifies the target directory. The moved file will keep its name.
ReadFile Reads the content of a file. The 'SourcePath' column specifies the file.
RenameDirectory Renames a directory. The 'SourcePath' column specifies the directory to rename and the 'TargetPath' column specifies the new name of the directory excluding path. The renamed directory will remain in its original directory.
RenameFile Renames a file. The 'SourcePath' column specifies the source file and the 'TargetPath' column specifies the new name of the file excluding path. The file will remain in its original directory.
WriteFile Writes data to a file. The 'TargetPath' column specifies the file that the data should be written to.
BeginExtraParams optional int
Marker that indicates that all columns with a higher ordinal than this column will be passed as parameters to the procedure after the action has been executed. This column must only contain NULL.
CreateDirectory optional bit
Specifies if any missing directories should be created. Default is to not create any missing directories. Applicable for actions CopyDirectory, CopyFile, CreateDirectory, MoveFile, MoveDirectory and WriteFile.
EndPointIdSource mandatory int
Id of the endpoint used as source. Applicable for actions CopyDirectory, CopyFile, DeleteDirectory, DeleteFile, DirectoryExists, FileExists, HashFile, List, MoveDirectory, MoveFile, ReadFile, RenameDirectory and RenameFile.
EndPointIdTarget mandatory int
Id of the endpoint used as target. Applicable for actions CreateDirectory, CopyDirectory, CopyFile, MoveDirectory, MoveFile and WriteFile.
HashAlgorithm mandatory string
Algorithm to use when calculating the hash value. Only applicable for action HashFile.
Possible value Description
Md5 The MD5 algorithm.
Sha1 The SHA1 algorithm.
NewName optional string
For CopyFile, MoveFile, CopyDirectory and MoveDirectory optionally renames the copied/moved object. Leave as null to retain original name.

For RenameFile and RenameDirectory either NewName or TargetPath must be specified and they are effectively aliases for each other.
Overwrite optional bit
Specifies if any existing items should be overwritten. Default is to not overwrite existing items. Applicable for actions CopyFile, MoveFile and WriteFile.
Recursive optional bit
Specifies whether the action should be performed recursively. Default is to not perform the action recursively. Applicable for actions List (list content of all subdirectories) and DeleteDirectory (remove non-empty directories).
SourcePath mandatory string
The path to the source entity. Applicable for actions CopyDirectory, CopyFile, DeleteDirectory, DeleteFile, DirectoryExists, FileExists, HashFile, List, MoveDirectory, MoveFile, ReadFile, RenameDirectory and RenameFile.
TargetPath mandatory string
The path to the target entity. Applicable for actions CreateDirectory, CopyDirectory, CopyFile, MoveDirectory, MoveFile, RenameDirectory, RenameFile and WriteFile.

SQL Call: Finished (mandatory)

Call made when there are no more actions to perform or when performing the 'Finish' action.
Supports custom errors: Yes
May modify database: Yes

Parameters:

@{Extra parameters} mandatory string
Extra parameters that were provided as extra columns when specifying the 'Finish'-action. If the call is made due to the queue being empty then no extra parameters are set.
@Action mandatory string
Possible value Description
Finished The component has finished performing actions.

Resultset: Forwarding definitions

Forwarding information.
Repeat mode: repeated zero or one time
Row count: zero or more rows

Columns:

<querystring_variable> optional string
Any column with no other specific meaning will pe passed along on the querystring to the menuitem you are forwarding to.
admin_cancelcidstepsback optional int
Number of steps in the page history to jump back if the user clicks OK in an ADMIN_MESSAGE dialog or Cancel in an ADMIN_FORCE dialog (the default being none). This value overrides cancelcidstepsback specified in the query string.
admin_cancelmenuitemid optional int
Id of the menuitem to execute if the user clicks OK in an ADMIN_MESSAGE dialog or Cancel in an ADMIN_FORCE dialog (the default being none). This value overrides cancelmenuitemid specified in the query string.
admin_cidstepsback optional int
Number of steps in the page history to jump back after execution (the default being one step back). This value overrides any destination specified by the query string.
admin_force optional string
Prompts the user with the specified text and the user may answer OK or cancel. If the user chooses OK the sql call will be rerun with the parameter @force set to 1.
admin_forward optional string
Displays a user friendly message and then forwards to the next menu item.
admin_forwardmenugroupid optional int
Id of the menu group to show after execution (instead of former menu item). This value overrides any destination specified by the query string.
admin_forwardmenuitemid optional int
Id of the menuitem to execute after execution (instead of former menu item). This value overrides any destination specified by the query string.
admin_message optional string
Displays a user friendly message to the user.
admin_pastehtmlfrompopup optional string
Pastes HTML. See admin_setfieldvaluefrompopup
admin_setfieldvaluefrompopup optional string
Sets the value of field specified in the menuitempopup call. Only select this column if menuitem is opened in popup.
admin_closepopup optional bit
If this column is anything but NULL the popup will be closed. Only select this column if the menuitem is opened in popup.
The default behavior is to step back inside the popup window and close it if there is nothing to step back to.
Cache optional string
Cache key to be cleared. Supports wildcards.
CacheUserId optional string
Either a user id or '%'.

Clears all caches (e.g. access permissions) related to the specified user id.

Use '%' to clear caches for all users.
cancelbuttontext optional string
Changes the text of the Cancel button when used with ADMIN_Force.
okbuttontext optional string
Changes the text of the OK button when used with ADMIN_Message, ADMIN_Force, or ADMIN_Forward.

SQL Call: Validate parameters

Allows you to validate the parameters supplied by the user before any other SQL is run in the component. This call is only made if the component has visible parameters, the SQL is a stored procedure, and 'Validate parameters' is checked.
Supports custom errors: No
May modify database: No

Parameters:

@force optional bit
@validateparams mandatory bit
This parameter is set to 1 by Softadmin® when this call is made.

Custom access control and logging

SQL Call: Custom access control and logging

Use this call to restrict which entries a user is allowed to view and edit, and to log which entries a user views.

Access to a menu item is normally controlled through functions and roles alone but some entities need more fine grained control. For example, a user may have access to the View Member menu item for normal members but not for members with a protected identity.

The menu items a user visits are always logged (in ADMINLogMenuItem) but for sensitive data you may need to log exactly what entries are viewed. Do the logging in this call as the common ways of viewing data (grid and InfoSQL) are not allowed to modify the database.

If you bind a scalar function instead of a stored procedure to this call then its name must end with '_GrantAccess'.
Supports custom errors: No
May modify database: Yes

Resultset: Access permissions

Return whether the user is allowed to visit the menu item with the current parameters.
Repeat mode: repeated exactly once
Row count: exactly one row

Columns:

GrantAccess mandatory bit
1 if the user is allowed to view the menu item, 0 if the user should not be allowed to view the menu item.

If 0 then an error will be logged as the user should not have been able to reach the menu item with the given parameters in the first place.