@amag-ch/sap_cap_common_messaging NPM

sap_cap_common_messaging

Wrapper for communication with cap messaging service

Features
Installing
Configuration
Implementation
License

Features

Simple configuration
Using placeholders in topics
Optional logging of whole event message (DEBUG=messaging)
Set 'x-correlation-id' in event header to follow events over applications

Deprecated

Using 'self:' as namespace placeholder to register to own events (deprecated: replaced with config option subscribePrefix)
Set 'topic' in event header (deprecated: use type and/or source instead)

Installing

Using npm:

$ npm install @amag-ch/sap_cap_common_messaging

Using yarn:

$ yarn add @amag-ch/sap_cap_common_messaging

Configuration

Set or overwrite defaults

Simple default configuration over standard messaging object in package.json

At least only the namespace is needed

{
    "cds": {
        "requires": {
            "messaging": {
                "kind": "local-messaging",
                "credentials": {
                    "namespace": "cap/<space>/<application>"
                }
            }
        }
    }
}

This results in following standard configuration

{
    "cds": {
        "requires": {
            "messaging": {
                "kind": "local-messaging",
                "subscribePrefix": "$namespace/",
                "publishPrefix": "$namespace/",
                "format": "cloudevents",
                "credentials": {
                    "namespace": "cap/<space>/<application>"
                },
                "queue": {
                    "maxDeliveredUnackedMsgsPerFlow": "10"
                }
            }
        }
    }
}

Configure sepcial queues for own application

Simpliest configuration

{
    "cds": {
        "requires": {
            "messaging-self-publishes": {
                "kind": "default-messaging"
            }
        }
    }
}

This results in following standard configuration

{
    "cds": {
        "requires": {
            "messaging-self-publishes": {
                "kind": "default-messaging",
                "subscribePrefix": "$namespace/",
                "publishPrefix": "$namespace/",
                "format": "cloudevents",
                "credentials": {
                    "namespace": "cap/<space>/<application>"
                },
                "queue": {
                    "name": "$namespace/self-publishes",
                    "maxDeliveredUnackedMsgsPerFlow": "10"
                }
            }
        }
    }
}

Of course, the defaults could be overwritten

{
    "cds": {
        "requires": {
            "messaging-self-publishes": {
                "kind": "default-messaging",
                "queue": {
                    "maxDeliveredUnackedMsgsPerFlow": "1"
                }
            }
        }
    }
}

Configure special queues for foreign application events

Simpliest configuration

{
    "cds": {
        "requires": {
            "messaging-foreign-system": {
                "kind": "default-messaging",
                "subscribePrefix": "foreign/system/namespace/"
            }
        }
    }
}

This results in following standard configuration

{
    "cds": {
        "requires": {
            "messaging-foreign-system": {
                "kind": "default-messaging",
                "subscribePrefix": "foreign/system/namespace/",
                "publishPrefix": "$namespace/",
                "format": "cloudevents",
                "credentials": {
                    "namespace": "cap/<space>/<application>"
                },
                "queue": {
                    "name": "$namespace/foreign-system",
                    "maxDeliveredUnackedMsgsPerFlow": "10"
                }
            }
        }
    }
}

Implementation

Own application events

const em = require('@amag-ch/sap_cap_common_messaging')
const messaging = await em.connect.to('messaging-self-publishes')

cds.once('listening', () => {

    /*
    * Standard emitting
    * Signature is same as for standard cap messaging service
    * 
    * Full topic based on configuration is: $namespace/object/changed => cap/<space>/<application>/object/changed
    */
    messaging.emit('object/changed', { ID })  
    
    /*
    * Emitting with replacements
    * Usefull, if cannot fully control the input value  
    * 
    * Following call results in event: objectwithillegalcharacters/changed
    */    
    messaging.emit({ template: ':1/changed', replacements: ['object-with-illegal_characters']}, { ID })
})

/**
 * Topics, we are listening here are (based on subscribePrefix):
 * - $namespace/object/changed => cap/<space>/<application>/object/changed
 * - $namespace/objectwithillegalcharacters/changed => cap/<space>/<application>/objectwithillegalcharacters/changed
 */
messaging.on([
    'object/changed',
    'objectwithillegalcharacters/changed'
], async (msg) => {

    console.log(msg)
    ...
})

Foreign application events

const em = require('@amag-ch/sap_cap_common_messaging')
const messaging = await em.connect.to('messaging-foreign-system')


/**
 * Topic, we are listening here is (based on subscribePrefix): foreign/system/namespace/object/changed
 */
messaging.on('object/changed', async (msg) => {

    console.log(msg)
    ...

    /**
     * This results in topic (based on publishPrefix): $namespace/object/changed => cap/<space>/<application>/object/changed
     */
    messaging.emit('object/changed', { ID })  
})