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_HOSTset to the url of your pod without the https:// prefixHUBOT_SYMPHONY_PUBLIC_KEYset to the location of your bot account .pem public key fileHUBOT_SYMPHONY_PRIVATE_KEYset to the location of your bot account .pem private key fileHUBOT_SYMPHONY_PASSPHRASEset 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_HOSTset to the url of your key manager without the https:// prefixHUBOT_SYMPHONY_AGENT_HOSTset to the url of your agent without the https:// prefixHUBOT_SYMPHONY_SESSIONAUTH_HOSTset 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.
Copyright 2016-2019 Jon Freedman
Note
The privateKey.pem and publicKey.pem files under test/resources have been generated at random and are not real keys.