Script assemblies in MForms

The most common way to extend the functionality of M3 panels in MForms is to use JScript files but there are other options such as Script assemblies and MForms extensions. With Script assemblies you can write code in most languages supported by .NET such as C# and VB.Net and you can actually debug your code using Visual Studio. Instead of deploying the script as a JScript file you use a .NET assembly in the form of a DLL file.

Script assemblies do not add any additional functionality compared to JScript files but it gives you more language options and a richer development environment in Visual Studio. The entry point to a Script assembly is an Init method in a public class in the MForms.JScript namespace, exactly the same as for a JScript file. Although you can choose to implement your scripts in almost any .NET language I would recommend using C#.

This post will describe how to create, test and debug a basic HelloWorld Script assembly. I will assume that you are already somewhat familiar with JScript so I won’t repeat what you can do with JScript but rather how you can build script functionality in a different way.

When to use Script assemblies

There are no exact guidelines of when to use Script assemblies and when to use regular JScript files. You have to decide from case to case what is most appropriate. Sometimes you might start prototyping in JScript and then move to a Script assembly when the solution gets to complex. Other times you might test, debug and develop using Script assemblies but then port the code to JScript.

Using Visual Studio gives a lot of gained productivity when developing and debugging but is also adds some complexity. If you are used to Visual Studio the choice might be obvious, if you have never used Visual Studio or coded in C# the step might be too great. Even if you don’t want to try this right away you know that you have the option in the future.

Prerequisites

If you want to build a Script assembly you need some version of Visual Studio. There is a free version called Visual Studio Express 2012 for Windows Desktop that can be downloaded from http://www.microsoft.com/visualstudio/eng/products/visual-studio-express-for-windows-desktop

Smart Office 10.1.x requires Visual Studio 2012 but for Smart Office 10.0.5.x you can use both the 2010 and 2012 editions of Visual Studio.

You will also need some assemblies from Smart Office to reference in your projects such as Mango.UI.dll and MForms.dll. If you have access to the Infor Smart Office SDK you can get the assemblies from the Bin directory of the SDK. If you don’t have access to the SDK you can get the assemblies from the ClickOnce installation of Smart Office on your local machine by following these instructions:

  • Create a bin folder for the Smart Office binaries. Example: F:\Demo\Bin
  • Locate the ClickOnce application folder in Windows Explorer. It should be in a path similar to this one (just replace userid with your user): C:\Users\userid\AppData\Local\Apps\2.0
  • Use the search field in Windows to find the assemblies you need
  • Search for Mango.UI.dll. If you only have one installation of Smart Office there should just be single result in the search. If there are multiple results you need to check the Properties of the Mango.UI.dll (right-click Properties) and then select the Details tab to see which version the assembly has.
  • Right-click on the Mango.UI.dll file in the search result and select Open file location. You should now be in the binary directory for the Smart Office framework. Sort the files on Type, select all files with the *.dll file extension and copy the files to the bin folder you created earlier.
  • Search for MForms.dll. If there are more than one hit in the search result you need to find the one with the version you want to use. Copy the MForms.dll to the bin folder.

In the example in this post I will use Visual Studio 2012 and C# but you should be able to follow along if you are using a different version of Visual Studio or another language.

Creating the Visual Studio project

This section describes how to create a Visual Studio project for a script assembly.

  • Start Visual Studio and open the new project using the File > New > Project… menu.
  • Locate the project template you want to use. Different project types can be used but I will choose the WPF User Control Library project to get the WPF references setup in the project.
  • Select the framework version. Use 4.0 for Smart Office 10.0.5.x or 4.5 for Smart Office 10.1.x
  • Enter a name for the project. This name must be the same as the name of the script class you will create later. Example: HelloWorld.
  • Select a location for the project. Example: F:\Demo
  • Enter a name for the solution. This name can be different from the project name but you can also use the same name. Example: HelloWorld.
  • Click OK to create the project.

M3SA_NewProject

  • Select the UserControl1.xaml file in the Solution explorer and delete it since we won’t use it in the example.
  • Right click on the project in the Solution Explorer and select Add Reference…
  • In the Reference Manager click the Browse button
  • Browse to your bin folder. Example: F:\Demo\Bin
  • Select the assemblies you want to reference and click OK. Example: “MForms.dll” “Mango.UI.dll”

M3SA_ReferenceDialog

You should now have project configured for creating a Script assembly for MForms.

Creating the script class

This section describes how to create the script class and add some test code to it. The script class is very similar to a regular JScript file.

  • Right-clicking on the project in the Solution explorer and select Add > Class…
  • Enter the name of the class which must be the same as the name of the project. This is similar to how the class in JScript must be the same as the name of the JScript file. Example: HelloWorld.
  • Click OK to create the class.

You should now have a blank class and there are couple of changes we have to do to make the class into a script. If you have worked with JScript before these steps should be very familiar.

  • Change the namespace of the class to MForms.JScript. Regardless of what language you use the namespace must be MForms.JScript.
  • Make the class public by adding the public keyword before the class name.
  • Add a public Init method with the following signature: public void Init(object element, object args, object controller, object debug)
  • Add import statements for MForms and Mango.UI
  • Save the file and then build the project using the Build > Build solution menu.

The code in your script class should look similar to this.

using Mango.UI;
using MForms;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;

namespace MForms.JScript
{
    public class HelloWorld
    {
        public void Init(object element, object args, object controller, object debug) 
        {
        
        }
    }
}

Now you have a Script assembly that can be deployed but it doesn’t do anything so we need to add some code.

Adding code to the script class

To be able to test the script class we need to add some code to it. To keep this example simple I will just get some values from the parameters to the Init method and show a message box with that information.

First I will create a StringBuilder instance to use when creating the message. The first thing I want to add is the name of the element that the script is connected to. The script might not be connected to a specific element so that must be checked first. The next thing is to add the script arguments. The script might not have any arguments so we must check that as well.

After that I want to get some values from the PanelState. First I need to convert the controller parameter to a typed variable of type IInstanceHost. The “as” operator is used since the controller parameter can be null if the script is executed when not connected to a panel. The PanelState is used to get the program and panel names.

The debug parameter is cast to a ScriptDebugConsole variable. The cast operator is used since this parameter should always have a value. The ScriptDebugConsole has limited value in script assemblies as you can’t use the Script Tool. The ScriptDebugConsole can still be used for logging if you don’t want to use log4net for logging.

Finally the ConfirmDialog is used to show the message to the user. The complete script code looks like this.

using Mango.UI;
using MForms;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Windows;

namespace MForms.JScript
{
    public class HelloWorld
    {
        public void Init(object element, object args, object controller, object debug)
        {
            var builder = new StringBuilder();
            if (element is FrameworkElement)
            {
                builder.Append("Element name: " + (element as FrameworkElement).Name);
            }

            if (args is string)
            {
                builder.Append(Environment.NewLine);
                builder.Append("Args: " + args);
            }

            var instanceController = controller as IInstanceController;
            if (instanceController != null)
            {
                var panelState = instanceController.PanelState;
                builder.Append(Environment.NewLine);
                builder.Append("Program: " + panelState.ProgramName);
                builder.Append(Environment.NewLine);
                builder.Append("Panel: " + panelState.PanelName);
            }

            var debugConsole = (ScriptDebugConsole)debug;
            debugConsole.Info("HelloWorld script initialized");

            ConfirmDialog.ShowInformationDialog("Hello World from script assembly", builder.ToString());
        }
    }
}

Building and deploying a Script assembly

To build a script assembly you simply use the Build > Build Solution menu item in Visual Studio or use the keyboard shortcut (F6 with the C# settings). Unless there are any errors in your solution you should get a Build succeeded message in the Visual Studio status bar.

Open the project bin directory for you project and locate your Script assembly. In my example the path to the project bin directory is F:\Demo\HelloWorld\HelloWorld\bin\Debug and the Script assembly is HelloWorld.dll. Now that we have the assembly file we need to deploy it to a location that MForms can read. The deployment is exactly the same as for regular JScript files, you just copy the assembly file to the jscript directory on the MUA-server or to your local script directory. It is highly recommended to use a local script directory when developing Script assemblies.

You have a couple of options of how to do this during development.

  • You could manually copy the Script assembly to the local script directory each time.
  • You could add a post build step to your solution that automatically copies the Script assembly to the local script directory after each build.
  • You could change your local script directory to be the bin\Debug directory of your Script assembly project.

Any of these solutions will work and there are probably other options as well.

If you don’t have a local script directory configured follow these steps:

  • Create a new directory. Example: F:\Demo\LocalScripts
  • Open the Windows Registry Editor and expand the HKEY_CURRENT_USER node followed by the Software node.
  • For Smart Office 10.0.5.x create or locate the Lawson key.
  • For Smart Office 10.1.x create or locate the Infor key.
  • Create or locate a key called MangoDev.
  • Create a new string value in the MangoDev key with the name LocalScriptPath where the value is the path to your local script directory. Example: F:\Demo\LocalScripts

Configuring and testing in MForms

If everything has worked so far you should have a Script assembly in your local script path or deployed to the JScript directory on the MUA server. The next step is to configure and test the Script assembly in MForms.

  • Start Smart Office and launch a M3 program such as MMS001 and navigate to the E-panel.
  • Open the Scripts dialog from the Tools > Personalize menu.
  • Select a target field such as WEITNO.
  • Enter the name of the script. Example: HelloWorld.dll. The only difference when using a Script assembly is that the .dll file extension must be part of the script name. If the .dll file extension is missing MForms will try to load a JScript file instead.
  • Enter the script arguments. Example: Test args
  • Press the Add button and then press the Save button.

M3SA_ScriptDialog

Refresh the panel. A dialog similar to the screenshot below should be displayed.

M3SA_ScriptResult

Note that you can still clear the script cache if necessary using the command mforms://jscript/clear

Debugging script assemblies

One of the great benefits of using Script assemblies is that it is possible to debug them using Visual Studio. Since you are not starting Smart Office from Visual Studio like you do when using the SDK you must attach the debugger to the Smart Office as described below.

The instructions assumes that Smart Office is started from the installation point, that Visual Studio is open with the project, that the Script assembly has been deployed and that the script is configured for the panel in MForms .

  • In Visual Studio open the Debug menu and select the Attach to Process item.
  • In the Attach to process dialog find the process for Smart Office. The process is called LawsonClient.exe in 10.0.5.x and MangoClient.exe in 10.1.x. You can also find it using the title column (Lawson/Infor Smart Office).
  • With the correct process selected click the Attach button.

M3SA_AttachDialog

  • Open the script class file and set a breakpoint in the beginning of Init method by clicking in the left document border or by pressing F9 (Toggle breakpoint).
  • Start the program and navigate to the panel where the script is configured.
  • If everything is working as expected you should hit the breakpoint like in the screenshot below.

M3SA_Debugging

The functionality that is available when debugging in Visual Studio depends on what version you are using but even with the free edition you can do a lot. When debugging Script assemblies for Smart Office 10.1.x you can actually use the Edit and continue functionality in Visual Studio to make code changes without restarting the client.
Debugging in Visual Studio might be a topic for a future blog post but there are lots of information about this on the web.

The last thing I will mention has to do with name changes. If you change the name of the script class or change the name of the assembly you must also remember to change the other. The name of the script class and the name of the assembly (set in the project properties) must always be the same.

Update on deployment

Update done by Karin. This post was written three years ago. In most cases we never update old posts and details to change over time. It is important to know that in M3 13.3 and possibly before that the script files has been moved to the database. If you as a H5 administrator has a Admin tools link in your menu with a tab that says Data Files then you must always manage deployed scripts via the tool – or they will be lost as you apply a patch or upgrade the solution. For dlls there is also an important note to consider.

For dlls you must use the import zip button in the data files tool.

Take your dll and add it to a zip. Import the zip by clicking “Import zip” in the Data Files tab in the administration tool. To export the dll successfully make sure to select more than one file in the tool so that a zip is exported instead of a single file.

19 thoughts on “Script assemblies in MForms

  1. Suraj

    Hi Norpe,
    This is just amazing as a c# developer looking to help out a customer … its a no brainer for me considering I struggle with script util in Smart office.
    Just c couple of questions on how far can we take this ?. Can I write my own custom helper classes in the same project and instatiate and then use them in the script class ? How do I add configurability? can I use some sort of global parameters in the script that can be modified without having to rebuild and redeploy?
    thanks,
    Suraj

    Reply
    1. norpe Post author

      You can create classes in a feature project that can be used in scripts. You just have to be clear and state that a script requires a specific feature to be installed when handing off the script to someone else.

      There are two standard ways for configuration in Smart Office, profile and settings. Both these topics are described in the Smart Office Developers guide in the SDK. In this case I would recommend placing your parameters in the profile. You can define a profile template in your feature manifest so that the profile is updated when the feature is installed and that the values can be edited in the Profile editor. In newer versions of Smart Office it is also possible to add new profile groups, applications and settings directly in the Profile editor.

      Both profile and settings values can be accessed from either feature code or script code.

      Reply
      1. Suraj

        Norpe thank you so much for your response. I did ask for smart office SDK (earlier) but I guess the cost is a bit restrictive so I am trying to work around it using the script assembles (as its right up my street). Although I don’t have the SDK documentation yet I can see all the objects and functions using the object browser and although I don’t have the complete documentation they are quite well named for me to understand what they do.
        To test out my idea I wrote a small WPF user control complete with event handling and called it on the initialization of the script class in a Modal Window. It all seems to work fine and I am able to handle events … next on my agenta is to use it to talk to a database and present some data in a grid …. not sure what the smart office sdk adds in terms of functionality but what you have shown here is a “poor man’s” SDK. Thanks again !!

  2. Sam N

    That worked for me and I am beginning to see the potential…. I wonder , why M3 bothers with JScript when they could use a standard .net platform like C#?

    Reply
    1. karinpb

      Hi,
      We use .Net c# and WPF for all Smart Office client development. It is just that with JScript .Net you can compile it and run it without having to create a dll. Please note that you can write a dll and run that as a script as well as this blog described. So if you would like to use C# you can do that. If you have a Smart Office SDK (requires and extra license) you can even set up your project in Visual Studio and debug into your code.

      Reply
  3. Pingback: Integrating Zeacom call center with Infor Smart Office | M3 ideas

  4. Kurt Jensen

    Hi.
    First of all, I am an absolute beginner in scripting in SmartOffice.
    I have tried your example (in vb.net though) but when I come to the lines similar to this:
    var debugConsole = (ScriptDebugConsole)debug;
    debugConsole.Info(“HelloWorld script initialized”);
    Visual Studio writes an error message that indicates that I have more than one version of mango.ui.
    The message goes like this: “The project currently contains references to more than one version of Mango.UI, a direct reference to version 10.0.50003.8 and an indirect reference (through ‘MForms.ScriptDebugConsole’) to version 10.0.50003.11. Change the direct reference to use version 10.0.50003.11 (or higher) of Mango.UI.”

    I have searched for the dll’s as you have shown, but I can not find any other versions. Why is there diferent versions?
    Our SmartOffice version is 10.0.5.3.8

    Reply
    1. karinpb

      Hi,
      If this is just a warning it can be ignored. Check references on your two projects (by expanding the References node in the Solution Explorer) and make sure they point to the same location/dlls. Also check the properties window in Visual Studio for the reference and make sure the Specific Version property is set to False. Start by checking the MForms.dll which is the only references that you have added manually if using the project template.

      Reply
  5. Antonio Caria

    on last version of SMO MUA web.xml should be changed otherwise You aren’t authorized to use dll’s.

    Exclude from Security Constraint

    Exclude from Security Constraint
    *.js
    *.dll

    Reply
  6. Pingback: Smart Office V.S. Script Template | Cheggen

  7. Farhat

    Hi,
    i am beginner in scripting of SmartOffice.
    I require to call a .Net c# and WPF for Smart Office from javascript on click button.
    can any one please help me to achieve this.
    I have below requirement..

    call a WPF on the click of a Button from panel which pass some parameter and get value from database.

    Thanks
    Farhat

    Reply
    1. karinpb

      Hi Farhat,
      I’m afraid we don’t have the possibility to help with generic requests. There should be enough examples on the blog to get you started but you do need general WPF and C# experience to be able to write JScript code. As for accessing the database we strongly advise you not to access the M3 database directly. You can access a replica – but even then you should probably use a service layer like Infor Web Services and not connect the client to the database. The recommendation to get data is to use M3 APIs.

      Reply
  8. bm

    Hello,
    Is it possible to call a webservice in jscript?
    I’m asking for that because there is no API to perform update of one field in M3.
    So well create a webservice which will perform the update.

    Thanks,

    Reply

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