version

File Manager

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 support Windows style paths (for local paths such as 'c:/foo', but usually not for mapped network paths since they are user specific) 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:

'.' is not allowed. '..' is allowed as long as it does not escape the root.
Wildcard characters '?' and '*' are not allowed. Depending on the endpoint other characters might be forbidden as well.
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'.

Recommendations

The recommended priority when choosing endpoint is:

Protocol:

SFTP
FTPS
FTP

Authentication:

Password protected keyfile (SFTP)
Username/Password

Password storage

Using the Credentials concept. Or have the user enter the password every time.
Do not use passwords stored in clear text, neither in code nor in system settings.

FTP server support

Unlike SFTP the FTP/FTPS protocols are designed for humans and the communication is therefore not standardized. This leads to the support being dependent on the server implementation.

Servers known to work:

IIS FTP 10.0
Filezilla 0.9.60

Servers with known issues:

IBM z/OS Communications Server Version 2 Release 4
- List file has known issues. Read file works. The remaining commands are untested.
vsFTPd 3.0.3
- Known to not work at all with the setting "strict_ssl_read_eof=YES". Will give the error "FTP server returned status code 426. 426 Failure reading network stream.".
- Unknown compatibility with "strict_ssl_read_eof=NO".

SFTP Keyfiles

Generating a keyfile

It is recommended that before generating a keyfile reading up on what algorithms and key lengths are recommended online as this is continuously updated and support differs for different SFTP servers.

The key must be password-protected and you should use a strong password.

The following are examples of command prompt commands can be used to generate a key, depending on algorithm of choice:

ssh-keygen -t rsa -b 4096 -m PEM
ssh-keygen -t ed25519 -Z aes256-cbc

The private key is then stored on the web server, and referred to by the KeyFilePath column, and the public key is given to the host of the SFTP server.

Adding a password to a keyfile

If you have a keyfile for SFTP that is not protected by a password then you can convert it to a password-protected keyfile with the command

ssh-keygen -p -f mykeyfile

Using the keyfile

Create new Credentials of type Account. Put the SFTP username in the username field, and the password to decrypt the keyfile in the password field. Put the key file on the server.

Use the KeyFileCredentials and KeyFilePath columns. Read more.

SQL

SQL Call: Get initial actions (mandatory)

Retrieve the initial actions to perform.

May modify database: Yes

Parameters

@Action string

Possible value	Description
Init	The component requests initial actions to perform.

Resultset: EndPoints (optional)

Specifies the endpoint(s) on which actions are performed.

Table count: 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. The address should not include the protocol.
Only applicable for FTP, SFTP, 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.

Credentials optional string

Credentials to use.

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.
SFTP	SFTP (SSH File Transfer Protocol)

KeyFileCredentials optional string

This configuration is specific to SFTP and mandatory if KeyFilePath is used. Otherwise, this value is ignored. The username from the KeyFileCredentials must correspond the user on the SFTP server. The password in the KeyFileCredentials is used to unlock the key file in KeyFilePath`.

Refer to the "Keyfile" section above for guidance on generating these necessary files.

KeyFilePath optional string

This configuration is specific to SFTP. It specifies the path to the private keyfile located on the web server, which is used for authentication. It is imperative that this key is password-protected for security reasons.

When this column is used the password from KeyFileCredentials is used to decrypt the keyfile. The username from the KeyFileCredentials must correspond the user on the SFTP server.

Refer to the "Keyfile" section above for guidance on generating these necessary files.

Password optional string

This should only be used when the user enters the username and password as parameters for the menu item, otherwise use Credentials column if possible.

The password used for authentication. Only applicable for FTP and FTPS.

Port optional int

Network port to use. Only applicable for FTP, FTPS and SFTP. The default port is 21 for FTP and should explicitly be set to 21 for FTPS. The default port for SFTP is 22.

For legacy reasons the default port for FTPS is 990 which is used for implicit FTPS which is not supported by the component.

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 optional string

This should only be used when the user enters the username and password as parameters for the menu item, otherwise use Credentials column if possible.

The username used for authentication. Only applicable for FTP, FTPS and SFTP.

Resultset: Actions (optional)

Specifies the actions that should be performed. The actions are added to a queue and executed in the order that they are returned.

Table count: 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.
CreateDirectory	Creates a directory. The 'TargetPath' column specifies the directory that should be created.
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'.

May modify database: Yes

Parameters

@{Extra parameters} string

All extra parameters that were provided when specifying the action. The name of the parameter corresponds to the column name.

@Action string

The action that requires extra information.

@ExtraInformation 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.

Table count: 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.

May modify database: Yes

Parameters

@{Extra parameters} string

All extra parameters that were provided when specifying the action. The name of the parameter corresponds to the column name.

@Action string

The action that was performed.

@ErrorCode 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 string

Contains a human-readable message if an error has occurred. If the action was performed successfully then thie parameter is not set.

@Exists bit

Only set for the actions 'FileExists' and 'DirectoryExists'.

Possible value	Description
0	The object does not exist.
1	The object exists.

@FileImage binary

Content of the read file, only set for action 'ReadFile'.

@Hash binary

The hash value. Only set for action 'HashFile'.

@SourcePath 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 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).

Table count: 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 (optional)

Specifies the endpoint(s) on which actions are performed.

Table count: 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. The address should not include the protocol.
Only applicable for FTP, SFTP, and FTPS.

BasePath mandatory string

Credentials optional string

Credentials to use.

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.
SFTP	SFTP (SSH File Transfer Protocol)

KeyFileCredentials optional string

Refer to the "Keyfile" section above for guidance on generating these necessary files.

KeyFilePath optional string

When this column is used the password from KeyFileCredentials is used to decrypt the keyfile. The username from the KeyFileCredentials must correspond the user on the SFTP server.

Refer to the "Keyfile" section above for guidance on generating these necessary files.

Password optional string

Port optional int

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 optional string

Resultset: Actions (optional)

Specifies the actions that should be performed. The actions are added to a queue and executed in the order that they are returned.

Table count: 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.
CreateDirectory	Creates a directory. The 'TargetPath' column specifies the directory that should be created.
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

EndPointIdSource mandatory int

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

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

SourcePath mandatory string

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} 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 string

Possible value	Description
Finished	The component has finished performing actions.

Resultset: Forwarding definitions (optional)

Forwarding information.

Table count: repeated zero or one time

Row count: zero or more rows

Columns

ADMIN_ErrorMessage optional string

Displays a user friendly error message to the user. This blocks any forwarding for the user.

ADMIN_ConfirmDelete optional string

Displays a user friendly confirmation message to the user with a delete button as the confirm button. If the user chooses OK the SQL call will be rerun with the parameter @ButtonAction set to 'Delete'.

ADMIN_ConfirmQuestion optional string

Displays a user friendly confirmation message to the user with a question style. If the user chooses OK the SQL call will be rerun with the parameter @ButtonAction set to 'Confirm'.

ADMIN_ConfirmWarning optional string

Displays a user friendly confirmation message to the user with a warning style. If the user chooses OK the SQL call will be rerun with the parameter @ButtonAction set to 'Confirm'.

ADMIN_InfoMessage optional string

Displays a user friendly info message to the user. When the user clicks OK the user is forwarded.

ADMIN_SuccessMessage optional string

Displays a user friendly success message to the user. When the user clicks OK the user is forwarded.

ADMIN_Dialog optional string

The dialog alias of a predefined dialog to show the user. Must be the first column in the result set table. Use multiple result set tables to combine with other forwarding.

Use the menu item "Admin > Dialogs" to register new dialogs or find aliases for existing ones.

<xxx> (for ADMIN_Dialog) optional any

Any column without special meaning in the result set with the first column ADMIN_Dialog will be used to make replacements of placeholders in the message and title text.

ADMIN_DebugInfo optional string

Additional information to show the developer when using ADMIN_Dialog.

<passing_field> optional string

Any column with no other specific meaning will pe passed along to the menu item you are forwarding to.

ADMIN_CancelCidStepsBack optional int

Number of steps in the page history to jump back if the user clicks Cancel in an ADMIN_FORCE dialog (the default being none). This value overrides cancelcidstepsback specified in the query string.

ADMIN_CancelReturnToMenuItem optional string

Jumps back to the menu item with this alias if the user clicks Cancel in an ADMIN_FORCE dialog (the default being none). If no prior menu item is found with the given alias, then an error is thrown.

ADMIN_CancelMenuItem optional string

Alias of the menu item to execute if the user clicks Cancel in an ADMIN_FORCE dialog (the default being none). This value overrides cancelmenuitemid specified in the query string.

ADMIN_CancelMenuItemId optional int

Deprecated. Use ADMIN_CancelMenuItem instead.

Id of the menuitem to execute if the user clicks 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_ReturnToMenuItem optional string

Jumps back to the menu item with this alias after execution. This value overrides any destination specified by the query string. If no prior menu item is found with the given alias, then an error is thrown.

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_ForwardLink optional string

Alias of the link to forward to.

ADMIN_ForwardMenuGroup optional string

Alias of the menu group to show after execution (instead of former menu item). This value overrides any destination specified by the query string.

ADMIN_ForwardMenuGroupId optional int

Deprecated. Use ADMIN_ForwardMenuGroup instead.

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_ForwardMenuItem optional string

Alias of the menu item to execute after execution (instead of former menu item). This value overrides any destination specified by the query string.

ADMIN_ForwardMenuItemId optional int

Deprecated. Use ADMIN_ForwardMenuItem instead.

Id of the menu item 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 error message to the user.

ADMIN_PasteHtmlFromPopup optional string

Pastes HTML into an HTML editor. See ADMIN_SetFieldValueFromPopup.

ADMIN_SetFieldValueFromPopup optional string

Sets the value of the field specified in the menuitempopup call. Only select this column if menu item is opened in a popup.

ADMIN_ClosePopup optional bit

If this column is anything but NULL the popup will be closed. Only select this column if the menu item is opened in a popup.

Default: The default behavior is to step back inside the popup window and close it if there is nothing to step back to.

ADMIN_ClosePopupAndReloadOpener optional bit

If this column is anything but NULL the popup will be closed and the parent will be reloaded. Only select this column if the menu item is opened in a popup. Avoid using this feature if the opener is a newEdit as that may interrupt the user's ongoing input.

ADMIN_ClearHistory optional any

When the value is not NULL all navigation history is cleared and the user can't navigate back. This is only supported when forwarding to another menu item.

ADMIN_RefreshMenu optional bit

Will trigger a reload of the sidebar if the column is anything but NULL.

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, ADMIN_ConfirmWarning, ADMIN_ConfirmQuestion, ADMIN_ConfirmDelete.

OkButtonText optional string

Changes the text of the OK button when used with ADMIN_ErrorMessage, ADMIN_ConfirmWarning, ADMIN_ConfirmQuestion, ADMIN_ConfirmDelete, ADMIN_InfoMessage, ADMIN_SuccessMessage, ADMIN_Message, ADMIN_Force, or ADMIN_Forward. ADMIN_Force,

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.

May modify database: No

Parameters

@Force bit

Set to 1 if the last call to validate parameters used admin_force and the user clicked OK in the OK/Cancel dialog.

@ValidateParams bit

Set to 1 when this call is made.

Resultset: Messages (optional)

Table count: repeated zero or one time

Row count: zero or one row

Columns

ADMIN_Force optional string

Message asking the end user to confirm their parameters.

ADMIN_Message optional string

Message explaining why the parameters are rejected.

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'.

May modify database: Yes

Resultset: Access permissions

Return whether the user is allowed to visit the menu item with the current parameters.

Table count: 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.

Examples

Listing files on an SFTP server

CREATE TABLE Example.SftpFile
(
	SftpFileId int IDENTITY CONSTRAINT PK_SftpFile PRIMARY KEY,
	[ParentDirectory] nvarchar(max) NULL,
	[Name] nvarchar(max) NULL,
	[IsDirectory] bit NULL,
	[IsHidden] bit NULL,
	[IsReadOnly] bit NULL,
	[DatetimeCreated] datetime NULL,
	[DatetimeModified] datetime NULL,
	[SizeInBytes] bigint NULL
);

GO

CREATE OR ALTER PROCEDURE Example.Sftp_ListFiles
	@Action varchar(30) = NULL,
	@SourcePath varchar(MAX) = NULL,
	@ErrorCode int = NULL,
	@ErrorMessage varchar(max) = NULL
AS
BEGIN
	SET NOCOUNT, XACT_ABORT ON;

	IF @Action = 'Init'
	BEGIN
		/* IMPORTANT: Never store passwords directly in your code
		 * or system settings for a production system!
		 * Instead, make use of Credentials to securely store passwords. */
		DECLARE
			@Server varchar(300) = '127.0.0.1',
			@Username varchar(300) = 'bob',
			@Password varchar(300) = 'secret';

		SELECT
			1 AS EndPointId,
			'SFTP' AS EndPointType,
			@Server AS [Address],
			@Username AS [Username],
			@Password  AS [Password];

		SELECT
			1 AS EndPointIdSource,
			'List' AS Action,
			'/' AS SourcePath;

		RETURN;
	END;

	IF @Action = 'List'
	BEGIN
		INSERT Example.SftpFile
		(
			ParentDirectory,
			Name,
			IsDirectory,
			IsHidden,
			IsReadOnly,
			DatetimeCreated,
			DatetimeModified,
			SizeInBytes
		)
		SELECT
			[ParentDirectory],
			[Name],
			[IsDirectory],
			[IsHidden],
			[IsReadOnly],
			[DatetimeCreated],
			[DatetimeModified],
			[SizeInBytes]
		FROM
			#List;

		RETURN;
	END;
	
	IF @ErrorCode <> 0
	BEGIN
		RAISERROR('%s', 16, 1, @ErrorMessage);
		RETURN;
	END;
	
	IF @Action = 'Finished'
	BEGIN
		RETURN;
	END;
END;