M.App Enterprise Tutorials

[#1]

This is the first part of Workflow Tutorials which will guide you through the initial steps when building a Workflow(s) for the Desktop Applications.

Introduction

Workflow enables you to configure processes and forms based on XML files. You can work with both flat and geospatially referenced data, control the Desktop App by functions such as manipulating scale level, working with legend items, capturing or editing vector data, etc.

A Workflow basically consists of two XML files - forms definition and workflow definition. In addition, custom JavaScript, CSS files and other resources might be required during the run time. Each tenant instance has its own unique Workflows stored at <Warehouse_Location>\<TENANT_NAME>\Workflows.

Best way to start the Workflow development is to use delivered Workflow Editor that can be launched from the M.App Enterprise Studio. However, for some complex workflow definitions it might be handy to check and work directly with the XML files using your favorite XML editor. It is also suggested to review the generated XML files in order to better understand the whole concept.

Prepare Database

Start by importing attached SQL dataset into your database. Microsoft SQL Server spatial data was used during the tutorial preparation. The coordinate system used is EPSG:3857.

Creating your first Workflow

1. Create new Workflow by CONTENT > WORKFLOW > NEW...
2. Give it a simple name such as "CrimesWF" and save it.
3. Worfklow Editor can be now launched from the list of Workflows:
   

Building the Workflow

List Form

1. Change the label of the first Workflow node to e.g. Crime Entries
2. Using mouse, pull the List from the TOOLBOX and drop it directly on the Crime Entries node:
   
3. Set the following list properties:

• Node ID = "CrimeList"
• Label = "Recent Crimes"

4. After the new workflow node is defined, we need to create a visual interpretation (form) of the list. Click on on the edit button to start editing the form properties:
   
   Form editor opens
5. Change the basic properties of the form:
   • Name = "RecentCrimes" (unique Form id)
   • Table = "Crime"
   • ID Field = "ID1"
   • Order by = "EVT_DATE DESC"

6. Drop a Column to the Listconfiguration
   
7. Set the new field name to ID1 (reflects a database PK field)
8. Repeat the steps 6.-7. with these fields:

• Name = "RUCR_EXT_D"; Label = "Event Type"
• Name = "LOCATION"; Label = "Location"

9. You can save the workflow now.
10. Further steps are required in order to test it. You must:
    • Define CONTENT > VECTOR DATA
      • At a minimum, define layer CrimeWF using the Crime database table.
    • Define DESKTOP > LEGENDS
    • Define DESKTOP > ACTION SET
      
      • You can position the new action to Top toolbar
      • Create an action group (e.g. ActionGroup1)
    • Assign the HalifaxWF Workflow
    • Assign a workflow to the Action set
      
    • Define SECURITY > ROLES
    • Create a Desktop App with components mentioned above

11. TIP: You can also create a lightweight Standalone Workflow Web App by following this article:
    https://community.hexagongeospatial.com/t5/M-App-Enterprise-Tutorials/Standalone-Workflow-in-custom-...
12. After you have everything set up, simply run our first Workflow by clicking on </> icon from a Desktop App and make sure that our first Workflow is running:

You will notice that if you click on some of the rows, you’ll receive information message that the Workflow has ended. That is a result of not having follow-node defined. Let’s add an editing form which will follow clicking on a list element.

Should you encounter an error instead of seeing the expected list, please review the log by checking SECURITY > LOGS in the M.App Enterprise Studio.

Edit Form

1. Drag’n’drop Form from the the TOOLBOX list on the Recent Crimes list.
   
2. Set:
   • Node ID = "crimeEdit"
   • Label = "Crime Record"
3. Click on the edit button on the newly placed form which will open a form editor.
   Set the basic form properties:
   • Name = "crimeEditForm"
   • Label = "Crime Record"
   • Table = "Crime"
   • ID Field = "ID1"
4. Drag’n’drop 6 fields total with following properties:

   Widget Type	Attribute	Value
   TextField	Name	ID1
   	Datatype	number
   	Visible	hidden (click on edit button to type this value)
   ComboBox	Name	RUCR_EXT_D
   	Label	Type
   	Datatype	string
   	List of values	SELECT DISTINCT RUCR_EXT_D FROM Crime
   TextField	Name	LOCATION
   	Label	Location
   	Datatype	string
   DateTimePicker	Name	EVT_DATE
   	Label	Event Date
   	Datatype	datetime
   DateTimePicker	Name	RevisionDate
   	Label	Date Last Revised
   	Datatype	datetime
   	Editable	unchecked

You should end up with a form like this:

5. Now, when you save the Form and open the Workflow from within your Desktop App, you should be able to click on the list items and see the detailed information:

Adding logic to the form

1. Let's add two Actions (form buttons) - Save and Cancel.
   
2. Set Action attributes:
   • Cancel button - SCRIPT[IG.navigate('CrimeList')]
   • Save button – "save"
     
3. Go to the CrimesWF workflow definition and define a Follow Node for the Crime Record form.

Now the form will return to the list after either editing or reviewing is over.

Adding list actions

Sometimes it is necessary to have actions available directly for the list views. Let’s add a button that will fit a selected list record. This action button will expect that a defined layer exists in the rich client’s legend.

1. Edit Recent Crimes (list) form and add a RowAction to the Listconfiguration.
   
2. Set action attributes:
   

   Attribute	Value
   Name	FitCrime
   Label	Fit
   Action	SCRIPT[fitCrime({ROW.ID1})]

As you can see this action requires some custom script function called fitCrime(). Let’s define the custom script file.

3. Save the RecentCrimes form and go to RESOURCES
   
4. Define NEW > SCRIPT
5. Name the script HalifaxScript.js
6. Insert following code snippet and save the script file.
   

   function fitCrime(rowId){
     SC.Map.setActiveLayer('CrimeWF').done(function(){
       SC.Map.setSelectedElements(rowId).done(function(){
         SC.Map.fitSelectedElements().done(function(){
           SC.Map.setMapScale(2000); 
         });
       });
     });
   }

   This script will work only within the Desktop App. It sets CrimeWF legend as an active layer, add the related row record to selected elements and lastly, it fits the map, centering the point feature.
7. Go to the RecentCrimes form definition, reference the new script from there and save the Workflow.
   
8. Run the rich client and check the functionality
   

Adding simple filters

1. Edit the RecentCrimes list form and define following two filters by clicking on “New Filter” button:
   

   Name	Label	Filter
   AssaultsFilter	Assaults Only	SQL[RURC_EXT_D = 'ASSAULT']
   VehicleRelatedFilter	Vehicle Related Only	SQL[RUCR_EXT_D LIKE '%VEHICLE']

2. Check Filterarea is expanded on the RecentCrimes form definition in order to have the filters visible during launch of the workflow.
   
3. Check the functionality in the running workflow.
   

Complete workflow files are attached to this article.

[#2]

Hi Jan,

I made the Crime Record form but it appears empty, could you kindly help?

Best Regards,

Khaled

[#3]

Hi Khaled,

I just see this comment now, but if this is still an issue you can check if 'Empty Form' is checked in the Form Properties. Having this checked will present an Empty Form

HTH

[#4]

Thanks sclow

[#5]

I want to delete a record from the list. I have a RowActions on the list (like your exanple 'Fit' button) . How can I delete a row from the list ? I'm a new here. Thanks ! 

--- I have fixed this one .

[#6]

Hi,

Perhaps the assumptions of this tutorial is not valid anymore, but I'm trying to create this basic workflow and i'm stucked on setp10. I am not being able to assined HalifaxWF Workflow. Where did I find it?

I got files attached and I past the javascript on ...\Hexagon\M.App Enterprise\<tenant>\Workflows\Custom\Scripts\CrimesWF

But I supose this is not the rigth way.

Is there any tutorial video about this routine?

Thks a lot.