Overview about available events

The following list is just a rough and short recap of available events. Please check the sections below for additional information:

• <functionNameWhichWasCalled> (cf. general description and addGraphics example description)
• integrationApiReady (cf. description)
• map-extent-changed (cf. description)
• setSketchUpdate (cf. description)
• smekul-feature-event (cf. description)
• getFeatureAttribute (cf. description)
• searchUpdate (cf. description)

List of available Events

The IntegrationAPI fires various events for specific purposes. In general, every function which is posted via the overall postMessage approach, will return a so-called "response event". This event includes additional information about the actual function call, details, error and whether the function call was successful and lead into an error.
In addition to the "response event", some events are "pushed" based which means that those are triggered without the actual function-call was posted.
All things have in common that they are built as follows: An event is posted with the structure like below:

{
   "functionName":"<functionNameWhichWasCalled>",
   "reason":"<normally the <functionNameWhichWasCalled> but could also contains additional information",
   "detail":{
      //additional information from the function call if success=true
   },
   "error":{
      //additional information from the function call if success=false
   },
   "success":true|false, //indicates that the function call was successfully
   "target":"<mapIntegrationElement>"  //indicates the DOM element where the map is placed
}

Function-Based "response-events"

To give you an example for the "response-events", which are triggered by their corresponding function calls, the following events might be returned if the addGraphics was called:

Success case:

{
    detail: {data: Array(1)}
    functionName: "addGraphics"
    reason: "addGraphics"
    success: true
    target: "mapIntegrationElement"
}

The detail object contains information about the data which were added by the function.

Error case:

{
    detail: {}
    error: TypeError: Cannot read properties of null (reading 'x')
    functionName: "addGraphics"
    reason: "addGraphics"
    success: false
    target: "mapIntegrationElement"
}

The error object contains information about the actual error which leads to the error.

Push-Based events

Some events are triggered without that the actual function was called.

integrationApiReady Event

The event will be triggered if the mapviewer and the IntegrationAPI is loaded completely. After this event was fired, the IntegrationAPI can be used.

{
    functionName:"integrationApiReady"
    reason:"integrationApiReady"
    success:true
    target: "mapIntegrationElement"
}

map-extent-changed Event

The event will be triggered if the mapviewer's spatial extent is changed. The detail-object contains information can include three different extent details:

• clusterExtent: If a cluster-layer is available, the extent of all cluster features is returned
• mapExtent: The current mapviewer's extent visible in the map.
• mapExtent: If a feature-layer is available, the extent of all visible service features is returned.

{
   "functionName":"map-extent-changed",
   "reason":"map-extent-changed",
   "detail":{
      "clusterExtent":{
         "spatialReference":{
            "wkid":25833
         },
         "xmin":296910.9670000002,
         "ymin":5597853.198999999,
         "xmax":478095.74399999995,
         "ymax":5703109.517000001
      },
      "mapExtent":{
         "spatialReference":{
            "wkid":25833
         },
         "xmin":273157.7435651523,
         "ymin":5573411.052260829,
         "xmax":539464.882724719,
         "ymax":5731483.142898597
      },
      "featureExtent":[
         {
            "layerId":"standorte_uVb/0",
            "extent":{
               "extent":{
                  "spatialReference":{
                     "wkid":25833
                  },
                  "xmax":478095.74399999995,
                  "xmin":296910.9670000002,
                  "ymax":5703109.517000001,
                  "ymin":5597853.198999999
               }
            }
         }
      ]
   },
   "success":true,
   "target":""
}

setSketchUpdate Event

The event will be triggered after the setSketchUpdate function was called. Calling the function will add and active EventListener for Graphic-Manipulation which will be fired everytime when graphics are created, edited or removed.

{
   "functionName":"setSketchUpdate",
   "reason":"setSketchUpdate",
   detail: {data: Array(1)}
   "success":true,
   "target":"mapIntegrationElement"
}

searchUpdate Event

The event will be triggered after the searchUpdate function was called. Calling the function will add and active EventListener for search-result-manipulation which will be fired everytime when a search is triggered or cleared.

{
   "functionName":"searchUpdate",
   "reason":"searchUpdate",
   detail: {}
   "success":true,
   "target":"mapIntegrationElement"
}

smekul-feature-event Event

This special event will be triggered if the geobak-4x-smekul-action Bundle ist loaded. If the user clicks the corresponding popup action, the smekul-feature-event will be fired containing details about the identified feature. Additionally, the "application administrator" can define which attributes should be passed to the application using the following configuration:

"geobak-4x-integrationapi": {
    "IntegrationApiExternService": {
        "externServices": {
            "smekul-feature-event": {
                "attributes": [
                    "AUM_INFO",
                    "BNR",
                    "FB_BEZEICH",
                    "FELDSTCKNR",
                    "JAHR",
                    "OBJECTID",
                    "SCHLAGNR"
                ]
            }
        }
    }
}

Please note that this event has a very limited use case and is not available per default.

{
    "functionName":"smekul-feature-event",
    "reason":"smekul-feature-event",
    "detail: {
         "data": {
            "layerID": "schlaege_sachsen/0",
            "attributes": {
                "AUM_INFO": "OEBL (bis 2022)",
                "BNR": "0113200000",
                "FB_BEZEICH": "AL-183-292952",
                "FELDSTCKNR": "FSWi009",
                "JAHR": 2022,
                "OBJECTID": 104403900,
                "SCHLAGNR": "Schl1"
            }
         }
     }
    "success":true,
    "target":"mapIntegrationElement"
}

getFeatureAttribute Event

This special event will be triggered if the "application administrator" configures a special event mapping using the following definition within the app.json file.

"geobak-4x-integrationapi": {
  "IntegrationApi": {
    "featureAttributes": {
      "setPostMessage": true,
      "showPopup": false,
      "layerId": "schlaege_sachsen/0",
      "highlightOne": true,
      "attributes": ["*"],
  }
}

Using this definition, data from the configured layerId are automatically pushed to your application without the need of calling a function explicitly. Additional with the use of graphicMapLayers notification are also possible. Have a look at the Tutorial - Service-Layer API

geo_impossible Event (iframe only)

This event will be triggered if the mapviewer application fails during initialization. A failed startup will result in an unusable mapviewer application.

{
    detail: {}
    error: TypeError: Cannot read properties of null (reading 'x')
    functionName: "geo_impossible"
    reason: "geo_impossible"
    success: false
}

Please note:

• Using an iframe integration approach will require that the "application administrator" ensures that the geo_impossible event handling is added
• Using a div approach, you need to implement your own "error" handler via the apprt.startApp error callback (cf. div integration example).

geo_failed_analysis Event

This event will be triggered if the analysis (cf. analysis resources) causes one of the following errors:

• Timeout after x seconds. If timeout is not passed as param (cf. documentation]), 30 seconds are used as a timeout.
• Functional error, produced by the Analysis-Backend-Service is returned.
• HTTP-StausCode is != 200. Any backend specific error is returned.
• HTTP-Status Code = 404. Wrong url was used or resource is not available. The four above-mentioned information are stored in the error object within the event.

{
    detail: {}
    error: <anyOfTheAboveMentionedErrors>
    functionName: "geo_failed_analysis"
    reason: "geo_failed_analysis"
    success: false
}