#Cloudant

This event allows you to connect functions to IBM Cloudant, a NoSQL database-as-a-service based upon Apache CouchDB. Functions are invoked for each database modification that occurs.

This event utilise the trigger feed provided by the Cloudant package.

#Setup

IBM Cloudant instances can be provisioned through the IBM Bluemix platform. OpenWhisk on Bluemix will export Cloudant 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 database credentials and the database name to listen to changes on when defining the event.

#Using Package Credentials

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

Developers only need to add the database to listen to for each event.

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

The configuration will create a trigger called ${serviceName}_${fnName}_cloudant_${db} and a rule called ${serviceName}_${fnName}_cloudant_${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 Cloudant event source can be defined explicitly, rather than using pulling credentials from a package.

# serverless.yaml
functions:
  index:
    handler: users.main
    events:
      - cloudant:
          host: xxx-yyy-zzz-bluemix.cloudant.com
          username: USERNAME
          password: PASSWORD
          db: db_name

#Adding Optional Parameters

The following optional feed parameters are also supported:

• max - Maximum number of triggers to fire. Defaults to infinite.
• filter - Filter function defined on a design document.
• query - Optional query parameters for the filter function.

# serverless.yaml
functions:
    index:
        handler: users.main
        events:
            - cloudant:
                ...
                max: 10000
                query:
                   status: new
                filter: mailbox/by_status

#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:
            - cloudant:
                package: /${BLUEMIX_ORG}_${BLUEMIX_SPACE}/Bluemix_${SERVICE_NAME}_Credentials-1
                db: my_db
                trigger: db_events
                rule: connect_index_to_db
     another:
        handler: users.another
        events:
            - trigger: db_events

#Event Details

Functions are invoked with the JSON object returned by the CouchDB changes feed for each database modification. The contents of the generated events have the following parameters:

• id: The document ID.
• seq: The sequence identifier that is generated by Cloudant.
• changes: An array of objects, each of which has a rev field that contains the revision ID of the document.

The JSON representation of the trigger event is as follows:

{
  "id": "6ca436c44074c4c2aa6a40c9a188b348",
  "seq": "2-g1AAAAL9aJyV-GJCaEuqx4-BktQkYp_dmIfC",
  "changes": [
    {
      "rev": "2-da3f80848a480379486fb4a2ad98fa16"
    }
  ]
}