M3 Bookmark URI syntax in MForms

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);
      }
   }
}

10 thoughts on “M3 Bookmark URI syntax in MForms

  1. Heiko

    Hi,

    about “stateless” : The blog states that a result is returned – what is the result, and how can the result data be accessed? Can you please provide an example ?

    Thanks in advance!
    Heiko

    Reply
    1. norpe Post author

      The stateless parameter is used in Mashups for the DetailPanels. When the parameter is used the program is closed directly after the request has been processed on the MUA server. The result is one or more detail panels in the standard MUA response XML format. Since the BE program is no longer running the data is kind of read-only.

      This parameter is only intended to be used by the Mashup framework but you could perhaps use it in other scenarios as well. This is not something that is officially supported however so I don’t have any example of how to use it.

      If you have a specific scenario where (and why) you would like to use it I could (maybe) add some more information.

      Reply
  2. xivicus

    In a link, I want to open a program: PMS070..
    In that program I want to add information from the program the link is in..
    Fieldname=WOMFNO
    And add the value= (the value of the field that i made into a link)..
    Can’t get it to work.. help?..

    Reply
    1. karinpb

      Hi,
      Just to clarify the question. He wants to link a column in MMS080 with the order number to PMS070 and pass in the order number.
      First check if PMS070 supports bookmarks since that is the only way to link into a program. That also means that you can’t create a bookmark to a A-panel so you need to select another panel, go to the program and select Tools -> Bookmarks ->. If the Bookmarks menu item is disabled Bookmarks is not avaialble and there is no way to link to that program.
      Bookmarks can be tested in MTS043.

      You can create your own links under Link Manager. If you create the target web you can still use bookmarks and use the replacement variables . A bookmark link to a specific WHLO and ITNO looks like this for example: mforms://bookmark?program=MMS002&tablename=MITBAL&keys=MBCONO%2c330%2cMBWHLO%2c110%2cMBITNO%2c%2b%2b%2b185%2b%2b%2b%2b%2b%2b%2b%2b%2b&option=2&panel=E&name=MMS002%2fE+Bookmark&source=MForms

      As long as WHLO and ITNO does not contain any charcters that will make this an invalid URL then you can replace the 110 with and %2b%2b%2b185%2b%2b%2b%2b%2b%2b%2b%2b%2b with . %2b is the encoded value for space. Characters like , ? & and space in some cases are invalid and will brake the URL. All keys needs to be interpreted as the value for the keys parameter for the bookmark to work.

      Online encode decoder:
      http://meyerweb.com/eric/tools/dencoder/

      The links in the Link Manager can be used in the Toolbox area to the right or you can open the link directly in the context menu, but mapping one of these links directly to a column in the list is not supported.

      Reply
  3. Nexhib

    Hi
    The situation in my Mashup:
    ‘Label1’ and ‘Textbox1’ Value in Textbox1 = 001
    ‘Label2’ and ‘Textbox2’ Value in Textbox2 = 04

    With a Button I would like to take my values (depending on my input in Textbox1 and Textbox2) in ECS420 to Field EHECON and EHECAC. The link should executed external.

    Is there a possibilty to do something like that?

    Reply
  4. karinpb

    You can use conditions in the button event to get value from Textbox1 or Textbox2, but to launch ECS420 and set two fields you need to check if this program supports bookmarks and that you can pass those two valued. So the first test would be MTS034 and test the bookmark. If you can’t get the scenario to work for you there then there is no need to start looking at what the condition on the button would looke like.

    Reply
  5. Martin

    Hi,
    Is it possible to run a JScript when the below bookmark is executed?

    26.03.2015 17:14:55 DEBUG Mango.UI.Services.DashboardTaskServiceImpl.Execute Executing task uri: mforms://bookmark/?program=OIS100&tablename=OOHEAD&option=1&panelsequence=Z&includestartpanel=False&requirepanel=False&suppressconfirm=False&keys=OACONO%2c201%2cOAORNO%2c0010000322&fields=OACUNO%2cEXTERP_MTO%2cOAORTP%2cB01&parameters=presetSMCD%2cEXTERP_MTO%2cpresetMODL%2c006%2cpresetTEPY%2cN30&lso-modal

    Reply
  6. Pingback: Rich HTML output from MEC | M3 ideas

  7. Pingback: Mashup quality control #5 – M3 ideas

  8. Pingback: Mashup quality control #6 – M3 ideas

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s