Official Content

Event Dispatcher is a GeneXus Server extension. When a user makes a commit to a Knowledge Base (KB) published in GeneXus Server, it allows communicating with third-party services (e.g.: tools that enable continuous integration such as ticketing tools, or automation of assembly and testing, communication between developers, etc.). Some examples of tools to integrate with are Jenkins, Jira, Slack.

For example, when integrating with Jenkins, when a commit is executed, a job can be fired in Jenkins that executes an automatic build of the Knowledge Base with the recent changes.

This document explains how to implement the integration to any of those tools, supported by Event Dispatcher extension.

Summary

How does the solution work?

An event-driven architecture is used.

The Event Dispatcher is subscribed to events of GeneXus Server (AfterPublishKB and AfterCommit). Those events are initiated in each KB under the GeneXus Server installation. The events are consumed only for those KBs that have a configuration file - DevOpsExtensionConfig.txt - (for details about the configuration, see below in this document).

When the Event Dispatcher receives an incoming event, it calls by reflection an assembly that listens to the request and passes the commit information to that assembly.
The assembly (intermediate software that must be installed on GeneXus Server at VDir\BinGenexus) should be implemented for each third-party tool you want to integrate to and should be specified at the configuration file also. 

In the end, this assembly will call the services of the third-party tool, using the API that the tool may provide and take any required action.

These intermediate software .dlls must implement a pre-established interface that is explained below in this document.

Components of the solution

The solution consists of the following components:

Distributed by GeneXus Server

  • GeneXus.Packages.Server.EventsDispatcher.dll (under <GXServer installation>\VDir\BinGenexus\Packages)
  • GeneXus.Server.ExternalTool.dll (under <GXServer installation>\VDir\BinGenexus)

Components you must set up

  • Configuration file: DevOpsExtensionConfig.txt
    Create it first under <GXServer installation>\VDir\BinGenexus\Packages.
    When the KB is published, this file is automatically copied to the KB Catalog (KB folder under Catalog directory). Therefore, at the KB level it is possible to manage which tools to enable and the settings of those tools. For more information, see the annex below.
  • The assemblies that implement the integration with the third-party tools should be installed under <GXServer installation>\VDir\BinGenexus.

Implementing the third-party tool integration

In order to develop the integration with a tool (e.g: Slack, Jenkins), first, you should investigate which is the API offered by the tool in order to execute the actions you want (for example, sending a message to a channel in Slack, using the information of the commit given by the Event Dispatcher).

Each intermediate software (dll that implements the integration) is called by reflection. The constructor of the class has to receive a string which is the configuration information in Json format (the part of the configuration of  the DevOpsExtensionConfig.txt file that corresponds to the tool, i.e: Slack, Jenkins, etc).

Besides, it must implement the following method:

List<Result> CommitEvent(CommitData commitData)

Define a reference in your Visual Studio project to the GeneXus.Server.ExternalTool.dll (which is distributed by the GeneXus Platform SDK, under the BinServer directory), where the interface IExternalTool is defined.

Example:

namespace GeneXus.Server.ExternalTool.Jenkins
{
    public class JenkinsImplementation : IExternalTool
    {
        private Configuration configuration;

        public JenkinsImplementation(string jsonDataConfig)
        {
            configuration = JsonConvert.DeserializeObject<Configuration>(jsonDataConfig);
        }

        public List<Result> CommitEvent(CommitData data)
        {
        }
    }
}

The CommitData class represents the commit structure. It is defined in the GeneXus.Server.ExternalTool.dll.
This class can be used to be able to process the comment and parse the content looking for a certain pattern that allows establishing what action to take.
In the Result list, the message that will be shown in the GeneXus output must be returned (as shown in the figure below).

image_20207292097_1_png

Requirements

Availability

Since GeneXus 17

Examples

Download the following examples:

Annex

About the configuration file

A configuration file called DevOpsExtensionConfig.txt is required. It must be created in the GXserver installation, under <GXServer installation>\VDir \BinGenexus\Packages.

It is an initialization file in JSON format. Its purpose is to enable/disable the third-party tools with which you want to interact and establish the settings to access these tools' services.

When the KB is published, this file is automatically copied to the KB Catalog (KB folder under Catalog directory). Therefore, at the KB level, it is possible to manage which tools to enable and the settings of those tools.

File format:
{
    'Tools':{
            "Assembly Name Tool 1": {
             'enable':Y/N,
            "key1":"value1",
            "key2":"value2",          
            "keyN":"valueN"
        },
          "Assembly Name Tool 2": {  
            'enable':Y/N,
            "key1":"value1",
            "key2":"value2",         
            "keyN":"valueN"
        },
    }
}

 

  • Within the "Tools" item, all assembly third-party tools must be listed. The name of the .dll file that implements the communication with that tool must be specified, e.g.: "GeneXus.Server.ExternalTool.Jenkins".
  • The "enable" item is mandatory, with the values ​​"Y" or "N" (if the tool is enabled - "Y", Event Dispatcher calls that .dll using reflection).
  • The rest of the JSON elements are free and will be read by the assembly implementation of the tool for communication with the third-party tool.

Note: The configuration file is read only once, when GeneXus Server is initialized. So, if you make any changes, GeneXus Server has to be restarted.

Example
{
    'Tools':{
            'GeneXus.Server.ExternalTool.Slack': {
    'enable':'N',
            'url':'https://hooks.slack.com/services/XXXXXX',
            'username':'genexus',
            'channel': ['#integración-gx','#general'],
            'gxServer':'localhost'
        },
        'GeneXus.Server.ExternalTool.Jenkins': {   
            'enable':'Y',
            'instance': [
                {
                    'host':'http://localhost:88',
                    'projectName':['In'],
                    'userName':'admin',
                    'userToken':'11111111111111111'
                }
            ]
        },
    }
}

See also

Changelog Event Dispatcher


Last update: February 2024 | © GeneXus. All rights reserved. GeneXus Powered by Globant