Showing results for 
Search instead for 
Do you mean 

Javascript API

by sturcato ‎07-17-2018 01:11 PM - edited ‎09-11-2019 04:51 AM (993 Views)


This tutorial describes you how to use the Javascript API in order to make Workflows communicate with the map and manage medias in your workflows.

To get a comprehensive description of the whole Javascript API available in Workflows visit this page. The library described is still relevant to Workflows in GMSC. The main functions that have changed are the subject of this tutorial.


Typical workflow configuration

Using workflows you often need to fit selected objects on the map. Here is a typical configuration in a list controller, where you would like to add a button to zoom to the geometry of the corresponding row (the action will be visible only if the current row has a geometry, this is specified in the visibility property).

In this example we use a custom function called zoomTo that will be defined in a custom script (the script will be bound to the list configuration using the "script" property).


Workflow editor:



Corresponding XML definition:


<FormAction name="ZoomTo" editable="true"
visible="list[SQL[select count(geometry_spa) from buildingextension where gid={ROW.gid}]]"
action="SCRIPT[zoomTo('Building Extension',{ROW.gid})]" type="row" /> 


We call the function passing the name ('Building Extension') we configured in GMSC Administrator as name in the legend configuration (project settings) and the primary key of the selected objects (placeholder {ROW.gid} will be replaced at runtime with primary key value of the current row).


Custom script:


function zoomTo(layername,featureids){
      return SC.Map.clearSelectedElements().then(function(){
          return SC.Map.setSelectedElements(featureids).then(function(){
              return SC.Map.fitSelectedElements().then(function(){
                  return SC.Map.closeWebBrowser();
  }).fail(function (error) {



In the custom script we use several methods of the JS API to

  1. set the layer active in the legend (in case it was not active already)
  2. clear any already selected object 
  3. set the passed object selected
  4. fit the object
  5. close the web browser (this is optional)

All of these methods are asynchronous, so we have to wait for the execution before issuing the following one.


Methods provided by JS API 


The Javascript API offers methods to communicate with GMSC application in both directions.


Communication with the map

The first set of methods allows communication with the map. Functions can be called as SC.Map.functionName.
Here is the list of available functions:


  • setActiveFeature(feature)
    • set the feature feature active in legend
    • feature, type string/number: must match Simple Id or name of the feaure in legend (project configuration)
    • throws exception if feature cannot be found or is null
  • getActiveFeature()
    • returns the active feature or NULL if no layer is active
  • clearActiveFeature()
    • clears current active feature in the legend
  • getVisibleFeatures()
    • returns an array of all visible features
  • reloadFeatures(features)
    • reloads sets of features
    • features, type string/number/array of strings/array of numbers: single feature or Javascript array of features to reload
  • setFeaturesVisible(features)
    • sets features visible
    • features, string/number/array of strings/array of numbers: single feature or Javascript array of features to be shown
  • setFeaturesInvisible(layers)
    • sets features invisible
    • features, string/number/array of strings/array of numbers: single feature or Javascript array of features to be hidden
  • setFeatureTranslucency(features, translucency)
    • sets translucency of the given features
    • features, string/number/array of strings/array of numbers: single feature or Javascript array of features
    • translucency, type number: translucency level between 0 and 1 to be set
  • setSelectedElements(selection)
    • sets the selection on the map
    • selection, type number/array of numbers: single element id or Javascript array of element id's to select
  • getSelectedElements()
    • returns Javascript array of element id's
  • fitSelectedElements()
    • fits the view on the selected elements on the map
  • clearSelectedElements()
    • clears the current map selection
  • setMapScale(mapScale)
    • sets the new map scale
    • mapScale, type number
  • getMapScale()
    • returns the current map scale
  • setMapCenter(centerX,centerY)
    • sets map center to centerX, centerY 
    • centerX, type number: horizontal value of the map center
    • centerY, type number: vertical value of the map center
  • getMapCenter()
    • returns current centerXcenterY values
  • setMapCenterAndScale(centerX,centerY,mapScale)
    • sets map center to centerXcenterY and scale to mapScale
    • centerX, type number: horizontal value of the map center
    • centerY, type number: vertical value of the map center
    • mapScale, type number: scale to use
  • setMapBounds(left,top,right,bottom)
    • sets the bounds on the map
    • left, type number: left (X max) coordinate
    • top, type number: top (Y max) coordinate
    • right, type number: right (X max) coordinate
    • bottom, type number: bottom (Y min) coordinate
  • getMapBounds()
    • returns the bounds of the map
  • bringToFront()
    • brings Desktop App to front
  • bringToBack()
    • brings Desktop App to back
  • convertGPSCoordinate(latitude, longitude)
    • converts a GPS coordinate to the used coordinate system in the map
    • latitude, type number: latitude of the GPS point
    • longitude, type number: longitude of the GPS point
  • executeSelectionSetQuery(queryName)
    • executes the query (associated to the current active feature) defined by name
    • queryName, type string: name of the query to execute
  •  closeWebBrowser()
    • closes the associated web browser instance
  • closeSmartClient()
    • closes SmartClient application

Geometry capturing

The API offers a dedicated method to digitize the geometry of an object. The function can be called as IG.captureGeometry().

In order to specify the actions we would like to make available to the user for capturing the geometry we have to specify them in the FormGeometry element of the form. On the top right corner of the form itself we can click on the Geometry property and drag&drop actions from the left panel and give them the name, that must match the list of available capturing actions provided by the API:


GE_ADDPOINTTOCOLLECTION Add point to collection 
GE_ADOPT Copy existing geometry
GE_DELETECOLLECTIONPART Delete collection part
GE_MERGE Merge polygons
GE_MODIFY Modify geometry
GE_MOVE Move geometry
GE_NEWARCBYCENTER New arc by center
GE_NEWARCBYTHREEPOINTS New arc by three points


Here is a configuration sample, with different actions specified if it is for a new geometry or for editing an existing one ("New" actions will be available in the edit panel if there is no geometry for the current element, "Edit" actions will be available in the edit panel if a geometry is already present):







Management of medias

This set of methods offers handling of different kind of medias. A media can be an URL to open, file to edit or document to download. Functions can be called as SC.Media.functionName.

Here is the list of available functions:


  • browse(urltargetwidthheight)
    • opens the url in the internal browser
    • url, type string: url to open
    • target, type string: name of the window to open the url; null will always open a new window
    • width, type number: width of the browser window
    • height, type number:height of the browser window
  • browseInNativeBrowser(url)
    • opens the url in the default browser registered on the client
    • url, type string: url to open
  • showFile(fileName)
    • launches the associated application to open the file; if the specified file is a directory, the file manager of the current platform will be launched to open it
    • fileName, type string: file/directory to open
  • openFileInEditor(fileName)
    • launches the associated editor application and opens a file for editing
    • fileName, type string: file to edit
  • downloadAndSave(url)
    • downloads the content of the given url and prompts the user for a directory where to place the file on the local system
    • url, type string: url to download
  • downloadAndOpen(url)
    • downloads the content of the given url and opens the file in the assigned editor
    • url, type string: url to download
  • downloadFile(urlConnectionlocalFile)
    • opens an URLConnection  and stores the inputStream to the defined path
    • urlConnection, type URLConnection: urlConnection to connect to
    • localFile, type path: path where to store the local copy
    • throws IOException if the connection fails or the local file path is not accessible
  • getFileName(urlConnection)
    • returns the filename attribute of the provided URLConnection; the method tries to read the "Content-Disposition" header from the stream; if the flag is not available the fileName given by the URL is returned
    • urlConnection, type URLConnection: urlConnection to read the header information