Notify - Symphony

Symphony is a secure instant messaging service focused on financial companies.

To make Symphony services available to Genesis, you need to provision symphony service and configure a symphony bot.

Importing Symphony

Symphony is a separate module of the Genesis platform. This gives you a better way to manage third-party dependencies, as the Symphony BDK has a number of transitive dependencies.

Adding the Symphony module data schema

In order to add the Symphony route tables to your application, add symphonyVersion to the gradle.properties file in your application's server folder:

symphonyVersion=x.y.z

Then add the following line to the settings.gradle.kts file in your application's server folder:

genesis {
    projectType = ProjectType.APPLICATION
    dependencies {
    ...
        dependency("global.genesis:genesis-symphony:${extra.properties["symphonyVersion"]}")
    ...
    }
}

Configuring the Notify Processes

To add the Symphony functionality, you need to override the genesis-notify-processes.xml file. If you are using the IntelliJ plugin, you can find this in the folder .genesis-home/genesis-notify/cfg/.

Paste this file into the cfg folder at server/appname-app/src/genesis/resources/cfg/.

Then you need to make the following changes to the processes file:

1. Add or edit the <script> tag of the NOTIFY_MANAGER process:

<script>genesis-symphony-dataserver.kts, genesis-symphony-eventhandler.kts, genesis-symphony-reqrep.kts</script>

2. Add or edit the the <classpath> tag of the NOTIFY_DISPATCHER and NOTIFY_MANAGER processes as follows :

<classpath>genesis-symphony-manager*</classpath>

3. Import the extensions for the Notify GPAL configuration. This enables intellisense to work for your Notify scripts.

To do this, add the following dependency to the build.gradle.kts file in your application's server/appname-app/ folder:

...
dependencies {
    ...
    compileOnly("global.genesis:genesis-symphony-manager:${properties["symphonyVersion"]}")
    ...
}

4. Deploy and install.

After you have made these changes, perform a deploy. If you are using the Intellij plugin, this also performs a genesisInstall automatically. If you are working manually, then you need to run genesisInstall separately.

Symphony configuration

Genesis requires the use of Symphony POD, Symphony Bot and the generation of private/public key pairs. This is covered extensively in the Symphony documentation.

You configure Symphony in your notify.kts file. Here is an example configuration with connection details.

notify {
    gateways {
        symphony(id = "symphony1") {
            sessionAuthHost = "76680.p.symphony.com"
            botUsername = "botusergenesis@genesis.global"
            botPrivateKeyPath = "/home/priss/run/site-specific/cfg/symphony/rsa/"
            botPrivateKeyName = "bot1.test.pem"
            appId = "GENESIS_EXTENSION_APP"  // optional, required for Symphony OBO feature
        }
	}
    
    // optionally include additional connections, including additional Symphony, Email or Microsoft Teams connections 
}

Now consider another example. For this, the private key is sourced from the DB.

To store the private key in a DB, you need to use the SYSTEM table with the following settings:

• SYSTEM_VALUE set to the contents of the private key, and
• the associated SYSTEM_KEY set to SymphonyRsaKey

notify {
    gateways {
        symphony(id = "symphony1") {

            sessionAuthHost = "76680.p.symphony.com"
            botUsername = "botusergenesis@genesis.global"
            botPrivateKeyFromDb = true
		}
    }
    
}

Using system definition in the notify.kts script

You must configure Notify in your application's genesis-system-definition.kts file.

systemDefinition {
    global {
        
            item(name = "SESSION_AUTH_HOST", value = "76680.p.symphony.com" )
            item(name = "BOT_USER_NAME", value = "botusergenesis@genesis.global" )         
        }
}

Once that is configured, you can refer to the item name directly in your notify.kts script, without import or qualifier.

notify {
    gateways {
        symphony(id = "symphony1") {
            sessionAuthHost = SESSION_AUTH_HOST
            botUsername = BOT_USER_NAME
            botPrivateKeyFromDb = true
		}
    }
}

Database configuration

NOTIFY

Field Name	Usage
SENDER	Genesis User sending message, if Symphony OBO is activated, then this message will be sent 'On Behalf Of' of this user
TOPIC	The Topic to broadcast this message
HEADER	Header that placed at the beginning of every message
NOTIFY_SEVERITY	An ENUM of either, "Information", "Warning", "Serious", or "Critical", which defaults to "Information". This is simply appended to a Symphony Message Header
BODY	The message content in Symphony MessageML Format

SYMPHONY_ROOM_NOTIFY_ROUTE_EXT

Field Name	Usage
ROOM_ID	The unique identifier of the Symphony chat room to send the notification to.
NOTIFY_ROUTE_ID	Reference to a primary KEY in the NOTIFY_ROUTE table.

SYMPHONY_BY_USER_EMAIL_NOTIFY_ROUTE_EXT

Field Name	Usage
ENTITY_ID	String identifying the entity to send to.
ENTITY_ID_TYPE	One of USER_NAME, PROFILE_NAME, ALL, or SELF. An additional value will be available that matches the ENTITY_ADMIN_PERMISSION_FIELD, if it is defined in Sysdef.
NOTIFY_ROUTE_ID	Reference to a primary KEY in the NOTIFY_ROUTE table.

Genesis Notify operations for Symphony

The Notify service currently provides additional Symphony operations; these are exposed as Event Handlers.

• GATEWAY_CREATE_CHANNEL creates a channel (to allow external users to be added to a channel; a channel should be created with external set to true and public to false)
• GATEWAY_ADD_MEMBER_TO_CHANNEL adds a user to a channel (if the user is not a member of the host POD, then a connection request will be sent to that user)
• GATEWAY_REMOVE_MEMBER_FROM_CHANNEL removes a user from a channel
• GATEWAY_ACTION_ON_CHANNEL allows a channel to be either reactivated or deactivated

Where there is more than one Symphony gateway defined, these operations act upon the first listed.

package global.genesis.message.core.event.notify
data class CreateChannel(
    val topic: String,
    val channelName: String,
    val external: Boolean = false,
    val multilateral: Boolean = false,
    val discoverable: Boolean = true,
    val public: Boolean = true
)
data class AddUserToChannel(val channelName: String, val userId: String)
data class RemoveUserFromChannel(val channelName: String, val userId: String)
data class ActionOnChannel(val roomId: String, val activate: Boolean)

The Notify service also offers the Request Server resource LIST_MEMBERS_OF_CHANNEL, which, unsurprisingly, lists members of a channel.

• Inputs (Request)

  ChannelName - Symphony Stream Id

• Outputs (Response)

  USER_EMAIL

  USER_ID - Symphony User Id

Configuring OBO for outgoing messages

To use the Symphony On-behalf-of (OBO) feature, which enables messages to be sent through a configured Symphony robot as a particular user, you need to configure your application to point to the required Symphony extension app.

You can find out how to set this up in the Symphony Documentation

item(name = "SYMPHONY_APP_ID", value = "GENESIS_EXTENSION_APP")

Configuring more than one service

You can configure Notify to work with more than one service at a time. For example, if you wanted to set up both Symphony and Email to be integrated with your application, you could configure them like this in your notify.kts file:

notify {
    gateways {
        email(id = "email1") {
            smtpHost = "smtp.office365.com"
            smtpPort = 587
            smtpUser = "default@genesis.global"
            smtpPw = "xxxxxxxxxxx"
            smtpProtocol = TransportStrategy.SMTP_TLS
            systemDefaultUserName = "Genesis System"
            systemDefaultEmail = "genesis@global.com"
        }

        symphony(id = "symphony1") {
            sessionAuthHost = "apod.symphony.com"
            botUsername = "abotuser@genesis.global"
            botPrivateKeyPath = "~/symphony/rsa/"
            botPrivateKeyName = "privatekey.pem"
        }
    }
}