OpenWhisk Events
Docs Version: 1.16.0
Edit on github

#Message Hub

This event allows you to connect functions to IBM Message Hub, a scalable message bus in the cloud, based upon Apache Kafka. Functions are invoked with messages that are added to a Kafka topic.

This event utilise the trigger feed provided by the Message Hub package.

#Setup

IBM Message Hub instances can be provisioned through the IBM Bluemix platform. OpenWhisk on Bluemix will export Message Hub service credentials bound to a package with the following name:

/${BLUEMIX_ORG}_${BLUEMIX_SPACE}/Bluemix_${SERVICE_NAME}_Credentials-1

#Configuration

Users need to pass the message hub credentials and the kafka topic to listen for messages on when defining the event.

#Using Package Credentials

Rather than having to manually define all authentication properties needed by the Message Hub trigger feed, you can reference a package which provides these properties as default parameters.

Developers only need to add the kafka topic to listen for messages on with each event.

# serverless.yaml
functions:
    index:
        handler: users.main
        events:
            - messagehub: 
                package: /${BLUEMIX_ORG}_${BLUEMIX_SPACE}/Bluemix_${SERVICE_NAME}_Credentials-1
                topic: my_kafka_topic

Optional parameters json, binary_key, binary_value are also supported.

The configuration will create a trigger called ${serviceName}_${fnName}_messagehub_${db} and a rule called ${serviceName}_${fnName}_messagehub_${db}_rule to bind the function to the database update events.

The trigger and rule names created can be set explicitly using the trigger and rule parameters.

#Using Manual Parameters

Authentication credentials for the Message Hub event source can be defined explicitly, rather than using pulling credentials from a package.

# serverless.yaml
functions:
    index:
        handler: users.main
        events:
            - message_hub: 
                topic: my_kafka_topic
                brokers: afkaprod01.messagehub.services.us-south.bluemix.net:9093
                user: USERNAME
                password: PASSWORD
                admin_url:  https://kafka-admin-prod01.messagehub.services.us-south.bluemix.net:443
                json: true
                binary_key: true
                binary_value: true         

topic, brokers, user, password and admin_url are mandatory parameters.

#Binding Multiple Functions

Other functions can bind to the same database event being fired using the inline trigger event and referencing this trigger name.

# serverless.yaml
functions:
    index:
        handler: users.main
        events:
            - message_hub: 
                package: /${BLUEMIX_ORG}_${BLUEMIX_SPACE}/Bluemix_${SERVICE_NAME}_Credentials-1
                topic: my_kafka_topic
                trigger: log_events
                rule: connect_index_to_kafka 
     another:
        handler: users.another
        events:
            - trigger: log_events 

#Event Details

The payload of that trigger event will contain a messages field which is an array of messages that have been posted since the last time your trigger fired.

The JSON representation of a sample event is as follows:

{
    "messages": [
        {
            "partition": 0,
            "key": "U29tZSBrZXk=",
            "offset": 421760,
            "topic": "mytopic",
            "value": "Some value"
        }
    ]
}

For more details on the exact semantics of the message properties, please see the trigger feed documentation.