This post describes the M3 Bookmark URI syntax that is used in MForms. Knowing the bookmark URI syntax is important when generating URIs within Smart Office using scripts or in other scenarios such as external applications that links to Smart Office with task parameters that contains a bookmark URI.

Even if you are not interested in the details of the bookmark URI syntax this post describes all the available bookmark parameters. These parameters maps to fields used in the Mashup Designer and fields in the MTS043 test program.

When bookmark URIs are not working as expected you should test the bookmark in the MTS043 test program to make sure that the bookmark code in the program actually works. The bookmark functionality is implemented in each program so if something is not working you can check if there is newer version of the program is available or open a support case for the specific program.

Encoding

All parameters in a bookmark URI should be encoded. In .NET you can do this using the UrlEncode method in the System.Web.HttpUtility class. For some of the parameters parts of the value must also be URL encoded. The encoding can make a bookmark URI hard to read but is necessary to ensure a valid URI. You can read more about encoding in this post It’s all in the URL – Client Configuration

Getting bookmark data

When constructing a bookmark URI you need to know the table name and the names of the primary keys for a progam. There are a couple of different ways to find this.

• In newer verisons of MTS043 you can simply enter the program name, press enter and the table and key names will be displayed.
• You can use the Bookmark context menu on a detail panel and select Copy to Clipboard. The URI in the clipboard will contain the table name and key names.
• You can use the Settings dialog for the ListPanel/DetailPanel in the Mashup Designer to get the table name and key names using the Get button or the Capture mode.

Mandatory parameters

There are only three mandatory bookmark parameters called program, tablename and keys.

program

The name of the M3 program to start. The value should be an uppercase string with a max length of 10. This could be MMS001 for the Item master program.

Example: program=MMS001

tablename

The name of the M3 database table. The value should be an uppercase string with a max length of 10. This would be MITMAS for the MMS001 program.

Example: tablename=MITMAS

keys

The unique primary key names and values for the record. The keys and values should be formatted as a comma separated list of key names and values where the values are URL encoded using UTF-8. It is very important that the values are URL encoded as some values can make the bookmark URI invalid without the encoding. How to do URL encoding in JScript will be shown in an example below.

Note that you must always supply all keys in a bookmark but the values can be blank in many cases such as B-panel bookmarks. An empty string should work, but older versions required a space ” ” and this should always work. The Business Engine will consider a bookmark to be invalid if not all keys are supplied.

The format of the keys parameter is: “key-1,value-1,key-2,value-2,key-n,value-n”

Example: keys=MMCONO,330,MMITNO,MANGO

In M3 it is possible to use almost any character in key values so assume that the item number was “M&NG,O”. The keys would then look like this with the values URL encoded.

Example: keys=MMCONO,330,MMITNO,M%26NG%2CO

Minimal URI example

The absolute minimal bookmark URI can be used to start programs on the default panel, usually the B-panel. The following URI starts MMS001 on the B-panel using company 330 and a blank item number.

Note that when used in a URI the entire keys parameter is URL encoded so that you no longer can see the commas separating the keys and values. The comma has been replaced with “%2c”.

Example:
mforms://bookmark?program=MMS001&tablename=MITMAS&keys=MMCONO%2c330%2cMMITNO%2c%2b

Optional parameters

The optional bookmark parameters are panel, startpanel, includestartpanel, panelsequence, option, sortingorder, view, fields, focus, source and name.

panel

The panel to open. The value should be one uppercase character. Valid characters are E-O | Q-Z | 1-9. Note that the A, B, C, D, and P are not valid for bookmarks. The value could be E for the E-panel.

Example: panel=E

startpanel

The start panel for the panel sequence. The value should be A or B but a default value will be set by BE.

Example: startpanel=B

includestartpanel

Indicates if the start panel panel should be included in the panel sequence. The value should be true or false. The default value is true. When this parameter is set to false the program will close when the panel sequence is completed. When this parameter is set to true the program will return to the start panel when the panel sequence is completed. The same applies if you go back using F12 or the previous button. If the bookmark navigated to the E-panel with includestartpanel=false and you press F12 the program will close. If the parameter had been set to true (or left out) the program would have returned to the B-panel when F12 was pressed.

Example: includestartpanel=false

panelsequence

The panel sequence to use. The value should be an uppercase string with a max length of 10. The value can be up to 10 uppercase characters. A default value will be set by BE if missing.

Example: panelsequence=EFG

option

The option to use when opening the panel. The option should be a numeric value from 1-99. An example value would be 2 to open the panel in change mode. Note that options that are supported vary between programs. To start a program on the B-panel you just leave out the option and panel parameters.

Example: option=2

sortingorder

Sets the sorting order to use. Setting the sorting order or the view makes sense when navigating to the B-panel or when the start panel is included. When navigating to a detail panel without including the start panel the sortingorder and view parameters will not have any effect. A legacy alias name for this parameter is inquirytype.

Example: sortingorder=10

view

Sets the view to use. This parameter will only have an effect if the program supports views. Also see sortingorder above.

Example: view=STD01-01

fields

The fields parameter is used to set additional values on the start panel. It can be used to set values in header fields or position fields on B-panels. Some values on the B-panels might be filled automatically if they are of the primary key. The fields parameter must be used when setting fields that are not part of the primary key. The format of the fields parameter is exactly the same as the keys parameter, it’s a comma separated list of field names and values. See the keys parameter for more information.

Example: fields=W1OBKV,20

focus

The name of a field to set keyboard focus to. The name should be an uppercase string with a max length of 10. A default value will be set by BE if missing.

Example: focus=WWITNO

source

The source parameter can be used to indicate where the bookmark was created/generated. The value for the source parameter is logged in BE to make it possible to filter on different bookmark sources in the log output. Bookmarks created by users on MForms detail panels use the source “MForms”. Bookmarks used in Mashup panels use the source “MFormsMashup”.

Example: source=MForms

name

The name parameter is used when a bookmark is created by a user on a detail panel.

Example: name=Test

More URI examples

Below are some additional bookmark URI examples. A tip is to use the Bookmark context menu on a M3 detail and then Copy to Clipboard to get a base URI that you can tweak when testing.

This bookmark opens the E-panel in MMS001 for the item MANGO.

mforms://bookmark?program=MMS001&tablename=MITMAS&keys=MMCONO%2c330%2cMMITNO%2cMANGO%2b%2b%2b%2b%2b%2b%2b%2b%2b%2b&option=2&panel=E

This bookmark opens the E-panel in MMS001 for the item MANGO but the start panel is not part of the panel sequence.

mforms://bookmark?program=MMS001&tablename=MITMAS&keys=MMCONO%2c330%2cMMITNO%2cMANGO%2b%2b%2b%2b%2b%2b%2b%2b%2b%2b&option=2&panel=E&includestartpanel=false

This bookmark opens the B-panel in MMS001 positioned on the item MANGO.

mforms://bookmark?program=MMS001&tablename=MITMAS&keys=MMCONO%2c330%2cMMITNO%2cMANGO%2b%2b%2b%2b%2b%2b%2b%2b%2b%2b

This bookmarks opens the B-panel for CRS610 with sorting order 1 and sets the position fields on customers with type 1 and status 90.

mforms://bookmark?program=CRS610&tablename=OCUSMA&keys=OKCONO%2c330%2cOKCUNO%2c%2b&fields=W1CUTP%2C1%2CW1STAT%2c90&sortingorder=1

Special optional parameters

The following parameters are used internally or for other very specific purposes. They are documented here as a reference but you should only use them if you understand how they work and when it is appropriate to use them.

requirepanel

Bookmarks were originally designed to start a M3 panel in interactive mode. If starting a bookmark did not result in a panel this was considered an error. Since then bookmarks have been used in more creative ways to execute operations that do not result in a panel. When the value of the requirepanel is true this indicates that a bookmark is used in a way that will not return a panel and that that the lack of a panel is not an error.

Example: requirepanel=false

suppressconfirm

Some special bookmarks starts by displaying a BE confirm dialog. When this parameter is set to true the confirm dialog will be be automatically suppressed by pressing the Enter key if a confirm dialog is displayed when the program starts.

Example: suppressconfirm=true

stateless

The stateless parameter is used for the Mashup DetailPanel. When the stateless parameter is set to true the MNE/MUA server will execute the bookmark, close the program and then return the result. When the result has been returned there will not be a program instance running on the BE server. When a bookmark is executed in stateless mode it will also step through the panel sequence and can return a list of detail panels in one response.

Example: stateless=true

Creating a bookmark URI in JScript

The following JScript shows how a bookmark URI can be constructed in code. The script creates a bookmark URI that uses both the keys and the fields parameters with encoding of both the values and the parameters.

import System;
import System.Windows;
import System.Windows.Controls;
import MForms;
import System.Web;
import System.Text;

package MForms.JScript {
   class BookmarkEncodingExample {
      public function Init(element : Object, args : Object, controller : Object, debug : Object) {

         var uri = "mforms://bookmark?program=CRS610&tablename=OCUSMA&sortingorder=1";

         var keyNames = new Array("OKCONO", "OKCUNO");
         var keyValues = new Array("330", " ");
         var fieldNames = new Array("W1CUTP", "W1STAT");
         var fieldValues = new Array("0", "20");

         var keys = CreateKeys(keyNames, keyValues);
         var fields = CreateKeys(fieldNames, fieldValues);

         uri += "&keys=" + HttpUtility.UrlEncode(keys);
         uri += "&fields=" + HttpUtility.UrlEncode(fields);

         debug.WriteLine("Keys: " + Environment.NewLine + keys + Environment.NewLine);
         debug.WriteLine("Fields: " + Environment.NewLine + fields + Environment.NewLine);
         debug.WriteLine("Bookmark URI: " + Environment.NewLine + uri + Environment.NewLine);

      }

      private function CreateKeys(names, values) {
         var builder = new StringBuilder();
         for (var i = 0; i < names.length; i++) {
            AddValue(builder, names[i], values[i]);
         }
         return builder.ToString();
      }

      private function AddValue(builder, key, value) {
         if (builder.Length > 0) {
            builder.Append(',');
         }
         if (String.IsNullOrEmpty(value)) {
            value = " ";
         }

         value = HttpUtility.UrlEncode(value);
         builder.Append(key);
         builder.Append(',');
         builder.Append(value);
      }
   }
}