@symphonyoss/hubot-symphony

hubot-symphony

Hubot adapter for Symphony developed by the Symphony Foundation

Hubot is a chatops tool developed by GitHub, with this adapator you can get up and running with a programmable bot written in JavaScript/Coffescript in a few minutes. This project wraps a small number of the Symphony REST APIs required for two-way bot communication and user lookup together with offline test cases, the adaptor is in use both by Symphony clients and by Symphony themselves.

Usage

You must pass the following environment variables to hubot

• HUBOT_SYMPHONY_HOST set to the url of your pod without the https:// prefix
• HUBOT_SYMPHONY_PUBLIC_KEY set to the location of your bot account .pem public key file
• HUBOT_SYMPHONY_PRIVATE_KEY set to the location of your bot account .pem private key file
• HUBOT_SYMPHONY_PASSPHRASE set to the passphrase associated with your bot account private key

There are also optional arguments which should be used if you are running on-premise

• HUBOT_SYMPHONY_KM_HOST set to the url of your key manager without the https:// prefix
• HUBOT_SYMPHONY_AGENT_HOST set to the url of your agent without the https:// prefix
• HUBOT_SYMPHONY_SESSIONAUTH_HOST set to the url of your session auth without the https:// prefix

These arguments are passed through to the NodeJs request module as described here.

Non-standard messaging

If you want to send a rich message you can call send with an Object instead of a String:

module.exports = (robot) ->
  robot.respond /pug me/i, (msg) ->
    msg.http("http://pugme.herokuapp.com/random")
      .get() (err, res, body) ->
        pug = JSON.parse(body).pug
        msg.send pug
        msg.send {
          format: 'MESSAGEML'
          text: "<messageML><a href=\"#{pug}\"/></messageML>"
        }

The various supported tags are documented here.

If you want to send a direct message to a user in response to a webhook you can interact with the adaptor via the robot variable:

module.exports = (robot) ->
  robot.router.post '/hubot/webhook', (req, res) ->
    email = req.params.email
    message = req.params.message
    robot.adapter.sendDirectMessageToEmail(email, message)
    res.send 'OK'

Diagnostics

A simple diagnostic script is included to help confirm that you have all the necessary pieces to get started. You can run this as follows:

git clone https://github.com/symphonyoss/hubot-symphony.git
cd hubot-symphony
npm install
npm run diagnostic -- --publicKey [key1.pem] --privateKey [key2.pem] --passphrase [changeit] --host [host.symphony.com]

If you are running on-premise you can add optional fifth / sixth / seventh arguments

git clone https://github.com/symphonyoss/hubot-symphony.git
cd hubot-symphony
npm install
npm run diagnostic -- --publicKey [key1.pem] --privateKey [key2.pem] --passphrase [changeit] --host [host.symphony.com] --kmhost [keymanager.host.com] --agenthost [agent.host.com] --sessionhost [session.host.com]

If the script runs as expected it will obtain and log both session and key manager tokens, look up and log some details of the bot account and then create a datafeed and poll. If you send a message using the Symphony client to the bot account you should see the details logged.

Contribute

Contributions are accepted via GitHub pull requests. All contributors must be covered by contributor license agreements to comply with the Code Contribution Process.

Note

The privateKey.pem and publicKey.pem files under test/resources have been generated at random and are not real keys.