hubot-symphony

Hubot adapter for Symphony hosted by the Symphony Program part of FINOS

Hubot is a chatops tool developed by GitHub, with this adapter 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 adapter is in use both by Symphony clients and by Symphony themselves.

In mid-2018 Symphony released their own JavaScript API together with a Yeoman generator which facilitates creating simple bots, unless you wish to make use of existing Hubot scripts it's recommended to use this instead. See the developer site here and symphony-api-client-node.

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 just pass messageML directly to the send method instead of plaintext. The various supported tags are documented here. If you want to send Structured Objects you can call send with an Object instead of a String (note the text must be valid messageML).

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
        // send url as text
        msg.send pug
        // send url as link
        msg.send "<messageML><a href=\"#{pug}\"/></messageML>"
        // send url as a card
        msg.send "<messageML><card iconSrc=\"#{iconSrc}\" accent=\"tempo-bg-color--blue\"><header>PUG!</header><body><img src=\"#{pug}\"/><br/><a href=\"#{pug}\"/></body></card></messageML>"
        // send message with a structured object
        msg.send {
          text: myMessageML,
          data: myStructuredObjectJson
        }

If you want to send a direct message to a user in response to a webhook you can interact with the adapter 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.

Whitesource reports

To check security and legal compliance, the build integrates with Whitesource to submit and validate the list of third-party packages used by the build.

Simply run the following commands from the root project folder.

export WHITESOURCE_API_KEY=<WhiteSource API Key>
npm install ; npm run whitesource

The <WhiteSource API Key> can be retrieved from the WhiteSource project dashboard.

If any issue is found, a file called ws-log-policy-violations.json will be generated in root project folder; if no issue is found, metrics will be sent to the WhiteSource project dashboard (available to project committers).

Contribute

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

Fork it (https://github.com/symphonyoss/hubot-symphony/fork)
Create your feature branch (git checkout -b feature/fooBar)
Read our contribution guidelines and Community Code of Conduct
Commit your changes (git commit -am 'Add some fooBar')
Push to the branch (git push origin feature/fooBar)
Create a new Pull Request

License

The code in this repository is distributed under the Apache License, Version 2.0.

Note

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