KVSKBASystem#
Procedures#
Notify(Text) :#
Summary: Sends a notification message to the user in local scope.
procedure Notify(message: Text):
Parameters:
message: The notification message text to display.
Remarks: This is a simplified overload of the Notify procedure that automatically uses LocalScope. The notification will only be visible on the current page and will not persist across pages.
Notification characteristics:
- Scope: LocalScope (notification disappears when navigating away)
- No actions attached
- Simple text-only notification
Use cases:
- Simple informational messages on the current page
- Quick feedback to user actions
- Non-critical status updates
- Temporary warnings or hints
For notifications that should persist across pages, use the overload with NotificationScope parameter
and specify GlobalScope. For notifications with navigation actions, use NotifyNavigate instead.
Example: Notify('The operation completed successfully.');
Notify(Text, NotificationScope) :#
Summary: Sends a notification message to the user with specified notification scope.
procedure Notify(messagetext: Text; notifscope: NotificationScope):
Parameters:
messagetext: The notification message text to display.notifscope: The notification scope (LocalScope or GlobalScope).
Remarks: This procedure provides full control over notification scope, allowing you to choose between local and global notification visibility.
Notification scopes:
- LocalScope: Notification is only visible on the current page and disappears when navigating away
- GlobalScope: Notification persists across page navigation until dismissed by user
Notification characteristics:
- No actions attached (text-only)
- User can dismiss manually
- Displayed in notification bar at top of page
Use cases:
- LocalScope: Temporary feedback, page-specific information, quick status updates
- GlobalScope: Important system-wide messages, warnings that need attention,
information relevant across multiple pages
For notifications with navigation actions to specific records, use NotifyNavigate instead.
Example: Notify('Settings have been updated.', NotificationScope::GlobalScope);
NotifyNavigate(Text, Variant, Integer) :#
Summary: Sends a notification with a navigation action to open a specific record on a page in local scope.
procedure NotifyNavigate(message: Text; rec: Variant; pageId: Integer):
Parameters:
message: The notification message text to display.rec: The record to navigate to (passed as Variant).pageId: The page ID to open when user clicks the navigation action.
Remarks: This is a simplified overload that automatically uses LocalScope for the notification. It creates a notification with a "Navigate" action button that opens the specified record on the specified page when clicked.
How it works:
- Extracts the SystemId from the provided record
- Stores SystemId and PageId in notification data
- Adds a "Navigate" action that calls NotifyNavigateHandler
- When clicked, opens the record on the specified page
Notification characteristics:
- Scope: LocalScope (disappears when navigating away)
- Includes "Navigate" action button
- Automatically retrieves record by SystemId
Use cases:
- Alerting user about issues with specific records on current page
- Providing quick access to related records
- Error notifications with navigation to problem source
- Validation warnings with direct navigation to affected record
The record parameter accepts any table type via Variant. The procedure extracts the SystemId
automatically and uses it to locate the record when the navigation action is triggered.
For notifications that should persist across pages, use the overload with NotificationScope.
Example: NotifyNavigate('Please review this customer.', Customer, Page::"Customer Card");
NotifyNavigate(Text, Variant, Integer, NotificationScope) :#
Summary: Sends a notification with a navigation action to open a specific record on a page with specified scope.
procedure NotifyNavigate(messagetext: Text; rec: Variant; pageId: Integer; NotifScope: NotificationScope):
Parameters:
messagetext: The notification message text to display.rec: The record to navigate to (passed as Variant).pageId: The page ID to open when user clicks the navigation action.NotifScope: The notification scope (LocalScope or GlobalScope).
Remarks: This procedure provides full control over a navigation notification, allowing you to specify both the target record/page and the notification scope.
How it works:
1. Validates the record variant can be converted to RecordRef
2. Extracts the SystemId from the record using SystemIdNo()
3. Stores SystemId and PageId as notification data
4. Creates notification with "Navigate" action
5. When action is clicked, NotifyNavigateHandler retrieves the record by SystemId
6. Opens the specified page with the retrieved record
Notification scopes:
- LocalScope: Notification visible only on current page, disappears on navigation
- GlobalScope: Notification persists across pages until dismissed or action is taken
Use cases:
- LocalScope: Page-specific issues with records, temporary validation errors
- GlobalScope: Important system-wide alerts about records, critical warnings that need attention,
cross-page references that should remain visible
The record parameter accepts any table type via Variant. The procedure uses Data Type Management
to convert it to RecordRef and extract the SystemId, making this a type-safe approach that works
with any record type.
Navigation mechanism:
- Action handler: NotifyNavigateHandler (hard-coded procedure name)
- Data keys: 'systemid' and 'pageid' (locked tokens)
- Record retrieval: Via RecordRef.GetBySystemId()
Important: If the record cannot be converted or doesn't have a valid SystemId, the procedure
exits silently without sending a notification.
Example: NotifyNavigate('Customer credit limit exceeded.', Customer, Page::"Customer Card", NotificationScope::GlobalScope);
NotifyNavigateHandler(Notification) :#
Summary: Handles the navigation action triggered from NotifyNavigate notifications.
procedure NotifyNavigateHandler(noti: Notification):
Parameters:
noti: The notification object containing SystemId and PageId data.
Remarks: This is the action handler for the "Navigate" button in notifications created by NotifyNavigate. It retrieves the target record using the stored SystemId and opens it on the specified page.
CRITICAL NAMING WARNING:
This procedure is linked via its hard-coded name string 'NotifyNavigateHandler' in the
NotifyNavigate procedures. If you rename this procedure, you MUST update all references
to the name string throughout this file, otherwise navigation actions will fail.
Process flow:
1. Retrieves 'pageid' from notification data and parses it to Integer
2. Retrieves 'systemid' from notification data and parses it to Guid
3. Uses RecordRef.GetBySystemId() to locate the record
4. Opens the specified page with the retrieved record using Page.Run()
Error handling:
- If PageId cannot be evaluated: exits silently
- If SystemId cannot be evaluated: exits silently
- If record cannot be found by SystemId: exits silently
Data format:
- PageId: Integer stored as Text, retrieved via 'pageid' key
- SystemId: Guid stored as Text, retrieved via 'systemid' key
The procedure uses RecordRef to work generically with any record type, then converts
to Variant for Page.Run() to open the appropriate page.
This handler is called automatically by the notification framework when the user
clicks the "Navigate" action. It should not be called directly from code.
Used by: NotifyNavigate procedures
WriteToFile(Text, Text) :#
Summary: Writes text data to a file and downloads it to the user's browser.
procedure WriteToFile(data: Text; filename: Text):
Parameters:
data: The text content to write to the file.filename: The filename for the downloaded file.
Remarks: This procedure creates a temporary blob on the server, writes the text data to it, and triggers a download to the user's browser's default download location.
Process flow:
1. Creates a Temp Blob (temporary binary large object)
2. Creates an OutStream to write data
3. Writes the text data to the OutStream
4. Creates an InStream from the blob
5. Copies data between streams (ensures proper buffering)
6. Triggers browser download using File.DownloadFromStream()
File handling:
- No file is permanently stored on the server
- Blob is temporary and disposed after download
- Download location: Browser's configured download folder
- User may be prompted based on browser settings
Use cases:
- Exporting data as text files (CSV, TXT, JSON, XML)
- Generating reports or logs for download
- Creating configuration files
- Exporting data for external processing
- Generating documentation or templates
The filename parameter should include the file extension (e.g., 'export.csv', 'report.txt').
The browser may append a number if a file with the same name already exists.
For binary data or when you already have an InStream, use the overload that accepts
an InStream parameter instead.
Example: WriteToFile('Name,Amount' + '\n' + 'Customer1,100', 'export.csv');
WriteToFile(InStream, Text) :#
Summary: Writes stream data to a file and downloads it to the user's browser.
procedure WriteToFile(var stream: InStream; filename: Text):
Parameters:
stream: The InStream containing the data to write to the file.filename: The filename for the downloaded file.
Remarks: This is a simplified overload that directly downloads stream data without creating an intermediate Temp Blob. Use this when you already have data in an InStream.
Process flow:
1. Takes the provided InStream directly
2. Triggers browser download using File.DownloadFromStream()
File handling:
- Downloads directly from the provided stream
- No intermediate blob or stream copying
- More efficient than Text overload for stream data
- Download location: Browser's configured download folder
Use cases:
- Downloading binary files (images, PDFs, Excel files)
- Exporting data already in stream format
- Forwarding data from external sources
- Downloading Report output as PDF
- Exporting blob fields from database
Stream source examples:
- Temp Blob InStream
- Media/MediaSet InStream
- Report output stream
- External API response stream
The filename parameter should include the appropriate file extension to help the browser
identify the file type (e.g., 'document.pdf', 'image.png', 'data.xlsx').
File.DownloadFromStream parameters explained:
- Parameter 1: InStream with the data
- Parameters 2-4: Empty strings (dialog title, to folder, from folder - not used)
- Parameter 5: Target filename
For simple text data, use the overload that accepts a Text parameter instead.
Example:
var tempBlob: Codeunit "Temp Blob"; inStr: InStream;
tempBlob.CreateInStream(inStr);
WriteToFile(inStr, 'export.pdf');