Bookmarks

Bookmarks provide a mechanism for storing and re-using the request parameters, user input data, and configuration choices made by users at runtime.

About Bookmarks

Depending on how they're developed, Logi reports can offer users many opportunities to customize their reports at runtime. Developers can include user input controls and "super-elements", such as the Analysis Grid, in the reports. Super-elements have their own user interface and give users a lot of freedom to work with data, arrange table columns and rows, and add charts to their reports.

However, the time users invest in configuring their reports may be lost when their session ends. Logi "bookmarks" allow these settings to be saved, on an individual user basis, so users don't have to re-configure their reports each time they view them. Bookmarks can save the following:

  • Values selected in user input controls
  • Session variables and link parameters
  • Super-element UI configurations

When a bookmark is created, it essentially "vacuums up" all the values that will become Request parameters, all super-element UI configuration settings, and all session variables and saves them in an XML data file. The contents of the file can be "replayed" at runtime to recreate the report, with all of its selections and settings intact.

 Bookmarks will not work with values passed using a Target-type element's Request Forwarding attribute. When this attribute is used, request variable values are not passed in a query string so they will not subsequently be available to be saved in a bookmark. To achieve the desired results, instead of using Request Forwarding, use a Link Parameters element to send request variable values to the target report.
 

Bookmark Types and Scope

Manual bookmark functionality, which uses special Action.Bookmark elements, is report-wide in scope. All of the values listed above will be saved. If a report definition includes two super-elements, the UI configuration values for both of them will be saved.

The special bookmark Action elements are available as children of Label, Button, Image, and other elements that can be used to initiate actions. These special elements are discussed in more detail in a later section.

Automatic bookmarks provide similar functionality but their scope is limited to recording the configuration details and parameters of their parent super-elements. These details are saved automatically every time a user makes a change in the super-element user controls. This makes working with bookmarks extremely easy. The Auto Bookmark element is available as a child of several super-elements and its use is discussed in a later section.

You can use either manual or automatic bookmarks in a report, but not both.
 

Bookmark Data

Regardless of type, bookmark data is stored in one or more XML data files, called a "Bookmark Collection" and, typically, there's one collection per user. The developer specifies the storage location and ID of the collection. If Logi Security is being used, these files can be named using the @Function.UserName~ token, thus tying the bookmark collection files to an individual user.

Bookmarks can be saved in a SQL database instead of in the file system; see the section Storing Bookmarks in a Database.

Bookmarks are identified by report name and a description. Special elements, discussed later, are available so developers can create their own Logi applications to manage bookmarks.

The Bookmark Organizer element allows users organize bookmarks into folders and sub-folders, which can be shared with other users.

Working examples of the Bookmark elements can be seen in our sample application.

Adding Manual Bookmarks to a Report

Adding manual bookmarks to your report is easy and the following examples provide step-by-step guidance. First, ensure that your report is a good candidate for bookmarks: it needs to include a super-element and/or some kind of user input selection that affects the displayed data. A simple report that just executes a SQL query and displays the entire results in a data table is not a good candidate, for example.
 

     

  1. In Studio, open your application's _Settings definition and select the General element.
     
  2. Set the Bookmark Collection Default attribute to the name for the bookmark data file. Do not include a path or .xml file extension. If you're using Logi Security, you can use the @Function.UserName~ token to individualize the collection; if not, enter some other value of your choice.

     In general, specifying this value here and leaving the corresponding attributes blank in individual bookmark-related elements is good practice. If necessary, you can override this value by providing one in those other elements.
     
  3. Set the Bookmark Location attribute value to the name of a folder, underneath the Logi application root folder where you want the bookmark files to be stored. You can use a token for the root folder here, as shown above. Don't use the system rdDataCache or rdDownload folders as these are periodically "cleaned up" automatically.
     
  4. If it doesn't already exist in the file system, create the bookmark location folder and be sure it inherits all the file access permissions of the application root folder.

     
  5.  

  1. In the report definition you want to add bookmark features to, make a note of the element ID of any user input elements whose values you want to save. In the example shown above, there's an Input Select List element with an ID of "inpCustID" that we want to save.

     

  1. In an appropriate place in the definition, add a Label, Button, Image or similar element, which will become the "Save Bookmark" link, as shown above.
     
  2. Beneath it, add an Action.Add Bookmark element. Unlike most Action elements, it needs no Target element.
     
  3. You can leave the Bookmark Collection attribute blank, unless you want to override the default value set in the _Settings definition.
     
  4. Set its ID attribute to a unique ID. This is very important, especially if you have multiple reports with "Save Bookmark" links in the same application.
     
  5. Set its Bookmark Name attribute to a meaningful name, usually the name of the report. This value can be used later, along with the Description, to identify individual bookmarks.
     
  6. Set its Bookmark Request Parameter IDs attribute to a comma-separated list of one or more element IDs for user input control elements or link parameter IDs. In the example above, the element ID from Step 4 is entered. These identify the values to be stored in the bookmark; any value from this report that would be referenced in a subsequent report using an @Request token can be identified here.

That's all it takes to save bookmarks. Run the report, click the Save Bookmark link, and inspect the files created in the specified bookmark file location. Assuming a bookmark collection name of "MyBookmarks", you should see:
 

The first file is the main bookmark file and will always be present. The other files, with a GUID as part of their names, are referenced in the main file and contain information about any super-elements in the report. These may nor may not exist, depending on your report definitions.

Here are the other Action.Add Bookmark element attributes you might want to use:
 

Attribute Description

Bookmark Custom Column 1
Bookmark Custom Column 2

Specifies a custom value to saved in the bookmark, which will be returned by DataLayer.Bookmarks. This could be use to provide additional information or datalayer filtering.

Bookmark Description

Normally, when saving a bookmark, the user enters a description of their own. This attribute value specifies custom default description text.

Bookmark Description Message

Specifies the prompt text for the description in the bookmark "save" dialog box. When this attribute has a value and the bookmark link is clicked at runtime, a dialog box will open prompting the user to enter a description, which is saved in the bookmark. If this attribute has no value, no dialog box will be displayed when the link is clicked.

Bookmark Save Caption

Specifies a custom caption for the Save button that appears in the bookmark dialog box. The default caption is "Save".

Bookmark Session Parameter IDs

Specifies one or more Session variables names, in a comma-separated list, to be saved in the bookmark. For example, to save the value of the token @Session.UserID~, you would enter UserID here.

If you create Metadata with Custom Tables and include Session tokens in its SQL queries, you should enter the session variables here. For example, if the query uses tokens like @Session.CustomerID~ and @Session.OrderID~ then enter CustomerID,OrderID here.


Adding Automatic Bookmarks

Adding automatic bookmarks to your report is easy and the following examples provide step-by-step guidance.
 

Auto Bookmark Attributes

Here are the attributes for the Auto Bookmark element:
 

Attribute Description

Bookmark Collection

(Required*) Specifies the name of a bookmark collection. Typically, there is one collection for each user. In this case, specify @Function.Username~ here..

For consistency, set the _Settings definitions General element's BookmarkCollectionDefault attribute with a global value, rather than setting BookmarkCollection in individual elements.

* This attribute is not required when a global value has been specified in _Settings.

Bookmark ID

(Required) Specifies a unique ID for the bookmark. The ID is returned by DataLayer.Bookmarks.

Bookmark Custom Column 1
Bookmark Custom Column 2

Specifies a custom value to saved in the bookmark, which will be returned by DataLayer.Bookmarks. This could be use to provide additional information or datalayer filtering.

Bookmark Description

Specifies default bookmark description text.

Bookmark Name

Specifies a text string saved in the bookmark and returned by DataLayer.Bookmarks. It is typically used to store the report name.

Bookmark Request
Parameter IDs

Specifies one or more Request variables names, in a comma-separated list, to be saved in the bookmark. For example, to save the value of the token @Request.State~, you would enter State here.

Values for Request variables specified here will be automatically saved when the report is submitted or refreshed.

Bookmark Session
Parameter IDs

Specifies one or more Session variables names, in a comma-separated list, to be saved in the bookmark. For example, to save the value of the token @Session.UserID~, you would enter UserID here.

Values for Session variables specified here will be automatically saved when the report is submitted or refreshed.

If you create Metadata with Custom Tables and include Session tokens in its SQL queries, you should enter the session variables here. For example, if the query uses tokens like @Session.CustomerID~ and @Session.OrderID~ then enter CustomerID,OrderID here.

Ensure that your report is a good candidate for automatic bookmarks: it needs to include one of the super-elements listed in the earlier About Bookmarks section. Remember that automatic bookmarks do not record values for user input controls outside of super-elements.

     

  1. In Studio, open your application's _Settings definition and select the General element.
     
  2. Set the Bookmark Collection Default attribute to the name for the bookmark data file. Do not include a path or .xml file extension. If you're using Logi Security, you can use the @Function.UserName~ token to individualize the collection; if not, enter some other value of your choice.

     In general, specifying this value here and leaving the corresponding attributes blank in individual bookmark-related elements is good practice. If necessary, you can override this value by providing one in those other elements.
     
  3. Set the Bookmark Location attribute value to the name of a folder, underneath the Logi application root folder where you want the bookmark files to be stored. You can use a token for the root folder here, as shown above. Don't use the system rdDataCache or rdDownload folders as these are periodically "cleaned up" automatically.
     
  4. If it doesn't already exist in the file system, create the bookmark location folder and be sure it inherits all the file access permissions of the application root folder.
     
  1. Add an Auto Bookmark element as a child of the target super-element, as shown above.
     
  2. You can leave the Bookmark Collection attribute blank, unless you want to override the default value set in the _Settings definition.
     
  3. Specify a unique Bookmark ID to differentiate this bookmark in the collection. This value will be incorporated into the bookmark file names, so don't use any exotic characters here that the web server file system considers invalid in file names.
     
  4. With the exception of Allow Shared Bookmark Updates (discussed later), the rest of the element's attributes are identical to those for Action.Add Bookmark but, of course, without those for the Save Bookmark dialog box user interface. Refer to the table in the previous section for information about these attributes.
     
  5. The last thing you need to do to is initiate automatic bookmarks. This is done by calling the report with rdLoadBookmark=True in the query string. One way to do this is by using Link Parameters with the link that calls the report.

Now you can run the report and manipulate the super-element interface. After that you can inspect the files created in the specified bookmark file location. Assuming a bookmark collection name of "MyAutoBookmarks", you should see:

The first file is the main bookmark file and will always be present. The other file, with Bookmark ID you specified as part of its name, is referenced in the main file and contains information about the super-element in the report. It will appear once the super-element UI is manipulated.

Here are some additional important usage tips:

To automatically generate the Bookmark ID: If you want the application to generate the Bookmark ID automatically, using a GUID, as shown above, leave the element's Bookmark ID attribute blank and call the report with rdNewBookmark=True in the query string.

With Report Center Menu: If the report includes a ReportCenter Item element, the automatically-created bookmark will be listed with the ReportCenter Menu element.

With Dashboards: If using Auto Bookmark with a Dashboard, do not set the Dashboard element's Save File attribute. The bookmark will in effect become the dashboard's Save File.

Organizing Bookmarks

Users may want to group and organize the bookmarks they create. The Bookmark Organizer element allows users to place their bookmarks into "bookmark folders" at runtime.

A bookmark folder is not an actual folder in the web server file system; instead, the bookmark data is referenced in the master bookmark data file in a hierarchy that creates "logical folders". The Bookmark Organizer lets users manage bookmarks and folders. Multiple bookmarks can be collected into a folder and folders can have sub-folders.
 

Runtime Display and Manipulation

The Bookmark Organizer displays the bookmark folders and works with a Data Table element, in the same definition, that lists the bookmarks. Clicking an entry in the data table runs the "bookmarked" report. When a folder is clicked, the data table is refreshed to show the contents of that folder. Folders can be created, renamed, and deleted, and bookmarks are organized by dragging them into folders. Here's an example:

The example above shows a Bookmark Organizer and its companion data table. They can be physically arranged on the page however you desire, and theme selection and/or styling can vary their appearance.

The example shows the default "My Items" bookmark folder and several sub-folders created by the user. When bookmarks are first created, they're placed in the My Items folder by default. The "gear" icon appears when the mouse hovers over a folder and allows you to add new sub-folders, and rename or delete sub-folders. The data table displays the bookmarks in each folder (the selected folder name is shown in bold text).

To move a bookmark from one folder to another, the user just drags the data table row's drag icon to the desired folder, as shown above.
 

Sub-folders can also be rearranged into other folders by clicking their folder icon and dragging, as shown above.
 

Implementation

As mentioned above, to implement this you'll need to add a Bookmark Organizer element and a companion Data Table element. Here's how:

  1. Implement manual or automatic bookmarks, as discussed in earlier sections.

     

  1. Include a Bookmark Organizer element in your report definition (one possible arrangement is shown above). Set its Data Table ID attribute to the element ID you'll give its companion data table.



  2. Add the companion Data Table, as shown above, and ensure its ID matches the one entered in the previous step.




  3. Add a DataLayer.Bookmarks element beneath the data table, as shown above. Unless you want to override the Bookmark Collection Default value set in _Settings.lgx, you can leave the collection name blank here.




  4. Add a Compare Filter beneath the datalayer and set its attributes as shown above. The Bookmark Organizer element automatically creates and updates the session variable rdSelectedFolderID each time the user selects a folder, so this filter causes the data table to only show the bookmarks in the selected folder.




  5. Add Data Table Column, Image, and Action.Drag Bookmark elements, as shown above. If you prefer, you can use a Label or Button element instead of the image. Set the action element's attributes as shown.

     If you want to use the standard "drag icon" image - - provided with Logi Info, enter the following for the Image element's Caption attribute value: ../rdTemplate/rdBookmarkOrganizer/rdDragHandle.png




  6. Enter one or more Data Table Column and Label elements, as shown above, to display information identifying the bookmarks.




  7. Finally, in order to actually run the bookmarks, add an Action.Run Bookmark element beneath the Label element and set its attribute, as shown above.

     

When run, with the Clarity theme applied, this simple example looks like the image shown above. The bookmark can be dragged into any of the folders and clicking its bookmark description will run the report and apply the bookmark.

Sharing Bookmarks

Up to this point, we've seen how bookmarks can be used to preserve an individual user's configurations. It might also be useful to be able to share configurations with other users of the same application. Once the Bookmark Organizer has been implemented, adding sharing takes very little development time. This section describes sharing in general and a later section describes sharing with groups of users.

Bookmark sharing is enabled by setting the Bookmark Organizer element's Allow Sharing attribute. Some variety of Logi Security must also be enabled so that the application knows who the users are.

Users who create bookmarks can share them by giving other users permission to access them. Here's our earlier organization example:

 

We've added a few icons in the bookmark row for sharing and deleting the bookmark, and you'll notice the new Shared with Me folder has appeared. This folder will contain links to bookmarks that have been shared with you by other users.

When the Share icon is clicked, a modal pop-up panel, shown above, is displayed. In it, users can select the other users who can share the bookmark. Developers can control the styling and content of the pop-up panel.

As users are selected and included in the "Shared With" list, their entries will be removed from the list of available users.

 

Implementation

Assuming you've already implemented the Bookmark Organizer, here's how to add bookmark sharing:

 

  1. Ensure that some variety of Logi Security is being used.





  1. Building on our earlier example definition, set your Bookmark Organizer element's Allow Sharing attribute to True (tokens may be used here), as shown above.







     
  2. Add a new data table column, with Division, Image, and Action.Show Bookmark Sharing elements, as shown above. Set the Action element's Bookmark ID attribute value to the Bookmark ID column returned in the datalayer.







     
  1. Next, decide if you want to the pop-up Share panel to include a pick-list of other users with whom a user can share bookmarks. This is determined by the addition of the Sharing List element beneath the Action element. Referring to the images shown above:



    With the Sharing List element, user names are displayed in an embedded table, as shown above right, and the names come from a datalayer. If a user in the table doesn't have a personal bookmark collection yet, one will be created for her automatically if a folder is shared with her. The Sharing List element also allows you to specify user groups for sharing.



    Without
    the Sharing List element, user names can be typed-in and will be compared to the names associated with all of the existing personal bookmark collections. A type-ahead feature will help filter the available names.









    The example above shows the Sharing List element in use. You must specify the name of the datalayer column containing the user names in its Sharing Collection Column attribute.



    As a special type of data table, Sharing List gives developers some control over the contents and formatting of the list. Any type of datalayer can be used and users are selected by clicking table rows. You can add whatever descriptive data you want and the pop-up panel will automatically expand to include the width of the table.







    The Sharing List element's datalayer result set only needs columns for the username and some descriptive value, like a department name.







  1. Find the Action.Drag Bookmark element you're using in the bookmarks data table and set its Bookmark User Name attribute as shown above. The BookmarkUserName column is returned by DataLayer.Bookmarks. As with all tokens, this is case-sensitive so mind your spelling.







     
  1. Find any Action.Run Bookmark elements you're using in the bookmarks data table and set their Shared Bookmark ID attributes as shown above. The SharedBookmarkID column is returned by DataLayer.Bookmarks. As with all tokens, this is case-sensitive so mind your spelling.

     

And now you have bookmark sharing ready to go.

 

 Tip: In your _Settings definition, use the Security element's Development Username attribute to run the application as different users in order to see that bookmarks are shared correctly.

A nice refinement you may want to add is to have differently colored sharing icons to indicate whether a bookmark has already been shared with others or not. To do this you'll need the two icons (assumed to be in _SupportFiles) and these formulae for the Image element's attributes:

 

Attribute Formula

Caption

=IIF("@Data.IsShared~" == "True" && "@Data.BookmarkUserName~" == "@Function.UserName~", "_SupportFiles/BookmarkShared.png", "_SupportFiles/BookmarkNotShared.png") 

Tooltip

=IIF("@Data.IsShared~" == "True" && "@Data.BookmarkUserName~" == "@Function.UserName~", "Edit Sharing", "Share")



If you have Logi's SSRM Add-on Module installed, you may want to copy and use these icon images:

    C:\Program Files\Logi Analytics\InfoGo\_SupportFiles\rdBookmarkSharingOff.png and rdBoomarkSharingOn.png



Sharing Bookmark Folders

Entire bookmark folders can also be shared with other users:

When sharing is enabled and you hover your mouse over sub-folders in the Bookmark Organizer, you'll see the built-in sharing icon, as shown above. The icon color indicates whether the folder has been shared with anyone.

A special Shared with Me folder will appear containing the folders, if any, that others have shared with you. Click the shared folders to see their contents and run the bookmarks. You can hover your mouse over them to see who shared them with you.

Clicking a sub-folder's green or black sharing icon will display the same Share pop-up panel used when sharing bookmarks. In it, you can see who you've shared the folder with, share the folder with others, and revoke sharing. The My Items personal folder cannot be shared.

 

Shared Folder Shortcuts

Suppose a folder shared with you is many levels of sub-folders deep and it's a nuisance to have to drill-down to it every time you need to use its bookmarks. The shared folder shortcut can make life easier for you in this case. This is created by drilling-down to the shared folder you want and then dragging it onto one of your personal folders:

This action creates the folder shortcut, as shown above. Note that the shortcut has a special "shared folder" icon and that, by clicking its Gear icon, you can rename it or remove it.

 

Implementation

Assuming you've already implemented the Bookmark Organizer, here's how to implement bookmark sharing:

 

  1. Ensure that some variety of Logi Security is being used.





  1. Set your Bookmark Organizer element's Allow Sharing attribute to True (tokens may be used here), as shown above.

     





     
  1. Next, decide if you want to provide users with a pick-list of other users with whom they can share folders. This is determined by the addition of the Sharing List element beneath Bookmark Organizer. Referring to the images shown above:



    Without the Sharing List element, user names can be typed-in and will be compared to the names associated with all of the existing personal bookmark collections. A type-ahead feature helps filter the available names.



    With the Sharing List element, user names are displayed in an embedded table, as shown above right, and the names come from a datalayer. If a user in the table doesn't have a personal bookmark collection yet, one will be created for her automatically if a folder is shared with her.











    The example above shows the Sharing List element in use. As a special type of data table, it gives developers some control over the contents and formatting of the list. Any type of datalayer can be used and users are selected by clicking table rows. The Share pop-up panel will automatically expand to fit the width of the table. Specify the name of the datalayer column containing the user names in the Sharing List element's Sharing Collection Column attribute.

     

Your bookmark folder sharing functionality is now ready for use. Here's a testing tip:

 In your _Settings definition, use the Security element's Development Username attribute to run the application as different users in order to see that individual bookmark folders are created and shared correctly.

Sharing with Groups of Users

Sharing bookmarks with groups of users works in a manner similar to the sharing mechanism we've already seen, with two important implementation differences. First, the security configuration must, of course, identify groups and the users that belong to them.

 



The example above shows a simple arrangement of security elements that uses a static datalayer to illustrate the assignment of roles, or "group membership", to users. It's through these elements, whether static or from other sources such as Active Directory, that a user is understood to "belong" to a group. We can see above that user "Roger" belongs to the group "Operations".

The second difference is that a Sharing List must be used and its configuration needs to include entries for groups, as shown above. Note that these group names should match those in the security elements in the _Settings definition.

Your should include a column as a "this user name is really a group name" flag. When this column value is blank, the username column will be understood to be the name of an individual user; when the column has any other value, such as "yes", the username column will be understood to be a group name. The name of the group name flag column is entered into the Sharing List element's Group Identifier Column attribute. In the example above, that would be "isGroup".



With groups included in the Sharing List configuration, the sharing pop-up will look like the example shown above, with special icons for groups.

As you might expect, when you share a bookmark with a group, it will be available to all of the users in that group.

Creating a Bookmark Manager

If you don't want to use the Bookmark Organizer and you're not sharing bookmarks, you can easily create your own bookmark manager application with Logi Info. This section describes how to create the data table shown below (from the Bookmarks sample app on DevNet) which can be used to manage bookmarks.

 

The table shown above contains these columns:

  • Report - The name of the report.
  • Description - Text entered when the bookmark is created to help identify it.
  • Saved - The bookmark creation time stamp.
  • Run As - Links that re-create the report, either by running it in a new window or by exporting it to PDF.
  • Actions - Links that allow the description to be edited and the entire bookmark to be deleted.

The following examples present the bookmark-related elements used to create the table. They assume that you've set the General element's Bookmark Collection Default attribute in the _Settings definition. If you're using an earlier version, you'll need to provide a value for the Bookmark Collection attribute in each element.

 

Re-run Reports with Bookmarked Values

Here's how to build your report definition to include links to re-run bookmarked reports:

  1. Add a DataLayer.Bookmarks element, as shown above, to retrieve the saved bookmark data. You may want to add a Sort Filter element to sort the data on the creation timestamp (the SaveTime column).









  2. Add Data Table Columns, as shown above, and in order to re-run a report with bookmarked values, add an Action.Run Bookmark element as a link. You do not need to provide a Bookmark Collection attribute value for it if you've already configured it in _Settings. If you want to run the report in a different window, add a Target.Run Bookmark element as shown. If you want to pass parameters to the report, use a Link Parameters element as usual.

     

Edit the Bookmark Description

Here's how to include elements that allow bookmark descriptions to be edited:

  1. Beneath the element to be used as a link, add an Action.Edit Bookmark element, as shown above.
  2. If you set a Bookmark Collection Default in _Settings, leave this blank. If not, or if using earlier versions, provide the name of the bookmark collection to be edited.









     
  3. Set its Bookmark Description Message attribute to the text for the prompt in the edit box, as shown above. When the link is clicked at runtime (and this attribute has a value), a modal dialog box will open and prompt the user to enter a description, which is saved in the bookmark.
  4. Set its Bookmark ID attribute value to the ID of the bookmark to be used. In this example, that information comes from the datalayer and is specified using an @Data token.
  5. Set its ID attribute to a unique identifier.
  6. Set its Bookmark Description attribute value to the current description of the bookmark to be used. In this example, that information comes from the datalayer and is specified using an @Data token.

  1. Finally, to fresh the table immediately, add an Action.Refresh Element element beneath the Action.Edit Bookmark element, as shown above.
  2. Set its Element ID attribute value to the ID of the data table.

Delete Bookmarks

Here's how to include elements that allow bookmarks to be deleted:

  1. Beneath the element to be used as a link, add an Action.Remove Bookmark element, as shown above.
  2. If you set a Bookmark Collection Default in _Settings, leave this blank. If not, or if using earlier versions, provide the name of the bookmark collection to be edited.
  3. Set its Bookmark ID attribute value to the ID of the bookmark to be used. In this example, that information comes from the datalayer and is specified using an @Data token.
  4. Set its ID attribute to a unique identifier.
  5. Set its Confirmation Message attribute value to the text to be displayed when the user is prompted to confirm the deletion. If this is left blank, no confirmationrequest will appear.
  6. As before, an optional Action.Refresh element can be added to refresh the table after the bookmark is deleted (see Steps 7 and 8 above).

Running the Most-Recent Bookmark on Page Load

Some developers may want their users to run a report and have their most-recently saved bookmark applied by default.

There are two steps required to make this happen: 1) run the report to get the ID for the most-recently saved bookmark, and 2) run that bookmark. Here's how to do this:

 

The elements shown above will let you reduce the data in the datalayer to the single row for the most-recently saved bookmark.

  1. Local Data - This is used to get the bookmark. We'll control when it runs by setting its Condition attribute to the special token "@Request.rdBookmarkID~" = "".
  2. DataLayer.Bookmarks - Configure with the name of your bookmark collection or leave blank if a default collection has been specified in _Settings. A token can also be used here.
  3. Sort Filter - Sort the bookmarks on the SaveTime column (Date type data), into Descending order.
  4. Sequence Column - This adds a "row number" column to each row of sorted data and the most recent bookmark will wind up as Row #1.
  5. Condition Filter - Configure its Condition attribute to @Data.mySequenceColumn~ = 1 which will remove all rows except Row #1, the most recent bookmark.



Now that you've retrieved and isolated the most-recently saved bookmark data, you need to run the bookmark:

 

The elements shown above will reload the report with the appropriate request variables.

  1. Division - This container is used to prevent endless recursive reloading of the report; set its Condition attribute to "@Request.rdBookmarkID~" = "".
  2. Image - Create and use a 1-pixel x 1-pixel transparent image (which will not be visible in the report).
  3. Event Handler - Set this to handle the DHTML onLoad event.
  4. Action.Run Bookmark attributes:

    - Bookmark Collection = leave this blank if you configured it in _Settings > General.

    - Bookmark ID = @Local.BookmarkID~.

    - Report Definition File = the name of this report definition (do not select Current Report).
  5. Target.Run Bookmark - No attribute settings.



When run, your report will load, then immediately reload itself with the most-recently saved bookmark applied to it.

Storing Bookmark, Gallery, and Save Files in a Database

Bookmark, Gallery, and Save files are usually stored as XML files in the web server file system. However, this may not be useful or practical in some Logi application deployments, so it's now possible to store them instead in a SQL database.

Some of the benefits of this approach include making backups easier and eliminating the need for network shares and "sticky" sessions. Logi Studio includes a migration tool that makes it easy to transfer existing bookmark files into a database, and then use them from there.

You can store the following (which we'll collectively call "bookmark files" in this section)...

  • Bookmark Collection files
  • Bookmark files
  • Gallery files
  • Gallery thumbnail files
  • Files uploaded with Report Author

...in these databases:

  • Microsoft SQL Server 2005+
  • MySQL
  • Oracle
  • PostgreSQL



Requirements

These are the requirements for migrating and using database bookmark storage. In your _Settings definition:

  1. If one doesn't already exist, add a Connection element for the database where your bookmarks will be stored. Ensure that the account used in the Connection element has sufficient rights to read from, and write to, the database.
  2. If not already in use, add and enable the Security element and enter a user name in its Development Username attribute. For the duration of the bookmark migration operation, grant the rdBookmarksAdmin right or role to that user.
  3. If you're using Logi SecureKey security, set your Security element's SecureKey Database Connection attribute to the connection for your bookmark database.
  4. Add a File To Database Mapping element under the root of your _Settings definition. When your application needs to read or save a bookmark, this element will "redirect" the command to a database table created for this purpose.

The migration takes place entirely within the context of the application currently open in Logi Studio, you can't use it to migrate files in other Logi applications.

 

As shown above, the Mapping element is added in the _Settings definition.

Its Folder attribute is set to a file folder that has been previously configured to store bookmark files. For example, to store bookmarks in the database, this attribute and the General element's Bookmark Folder Location attribute would be the same, as long as you do not have any dynamic subfolders in the BookMark Folder location.. The @Function.AppPhysicalPath~ token can be used in this attribute but other tokens are not allowed.

If you DO have dynamic subfolders(such as in SSRM), then you need to specify it in this way (for example) if:

BookmarkLocation="@Function.AppPhysicalPath~\goBookmarks\UserName@Function.UserName~"

Then your mapping would look like this:

<FileToDatabaseMapping Folder="@Function.AppPhysicalPath~\goBookmarks"

The Table Name attribute specifies the database table to be used; if it doesn't exist, it will be created by the migration tool using this value. At a minimum, we recommend that you use a different table for each Logi application. Tokens cannot be used here.

The Connection ID specifies the database connection to be used. If left blank, the first Connection element found will be used.

The Mapping element's attributes now support tokens.

If you have multiple folders where bookmark files are stored, then add multiple File to Database Mapping elements to include them, and migrate them all to the same database table.

 

Migrating Existing Files into the Database

Once the requirements listed above have been met, you need to run Logi Studio's migration tool to create the database table and insert existing bookmark files into it. The migration of existing bookmark files into the database is something you'll do once, to create the table(s) and migrate any existing bookmark files, and won't need to do again.

Important: Before you begin this operation, you will have to disable your Security element in the _Settings.lgx file. Find where security enabled = True, and reset it to False, and then save the settings file. Once you have completed the migration, set security enabled back to True.

 The migration is a one-way operation: once bookmarks have been stored in the database and used, it's very difficult to accurately revert them back to being stored in files.

 

The migration tool is launched from Logi Studio's Tools menu, as shown above, by clicking the Bookmark Storage menu item. Click Next to start the migration.

 

A gauge and bookmark item counter will display progress as the migration proceeds. Click Next, then Finish when the migration is complete.

 

If you examine your database table, as shown above, you'll see that the files have been copied into it.

If it's not otherwise useful, delete the user name you set in the Security element's Development Username attribute and remove the rdBookmarksAdmin right/role assignment.

Subsequent new bookmarks and changes to existing bookmarks will now be automatically applied to the table. Requests for the bookmark data will result in a query of the table. Bookmark files are not automatically deleted by the migration process, but you may delete them manually if you'd like, as they'll no longer be read or updated.

 It's not recommended but if you do re-run the migration tool later, it will update all of the existing table rows with whatever is in the (possibly "stale") bookmark files and then add any new files. This could result in overwriting newer bookmark table data with the old bookmark file data.