Skip to content
main
Switch branches/tags
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
bin
 
 
lib
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Teams Connector

Gem Version RSpec

Welcome to Teams Connector. This gem allows you to easily send messages from your ruby project to Microsoft Teams channels. It integrates in your rails project, when you are using bundler or even in plain ruby projects.

The messages can be send synchronous or asynchronous with Sidekiq.

Installation

Add this line to your application's Gemfile:

gem 'teams_connector'

And then execute:

$ bundle

Or install it yourself as:

$ gem install teams_connector

Usage

After setting up the Incoming Webhook Connector for your Microsoft Teams channel, it is as simple as configuring the channel and creating a new TeamsConnector::Notification.

The channels parameter can either be a single channel identifier or an array of multiple channel identifiers, that each will receive the notification.

# TeamsConnector initializer
TeamsConnector.configure do |config|
  config.channel :channel_id, "https://<YOUR COMPLETE WEBHOOK URL GOES HERE>"
end

# Send a test card to your channel
TeamsConnector::Notification.new(template: :test_card, channels: :channel_id).deliver_later

# Send a card with a list of facts
content = {
  title: "Teams Connector Readme",
  subtitle: "A list of facts",
  facts: {
    "Usage": "Testing the facts Card"
  }
}
TeamsConnector::Notification::Message.new(:facts_card, "This is a summary", content).deliver_later

Secure Channel Configuration

Since the Incoming Webhook Connector does not allow any authentication at the endpoint it is crucial that you keep your channel urls secret. At best nobody finds the url but it can also lead to spam or even faking of critical messages.

In Rails provides the credentials functionality for environmental security. This mechanism can be used by TeamsConnector to load channels from an encrypted file. This also allows easy separation of production and development channel URLs. All channels are defined under the top-level entry teams_connector and will be identified by their key.

# $ bin/rails credentials:edit
teams_connector:
  default: "<INSERT DEFAULT URL HERE>"
  sales: "<INSERT URL FOR THE :sales CHANNEL HERE>"

After configuration of the credentials you can load the channels in your initializer. Since #load_from_rails_configuration is a wrapper around #channel both methods can be used together.

# TeamsConnector initializer
TeamsConnector.configure do |config|
  config.load_from_rails_credentials
  # After loading the :default channel is available and can be set as the default 
  config.default = :default
  config.channel :another_channel, "<URL>"
end

Templates

This gem provides some basic templates in its default template path. You can also define your own templates in your own path. The default templates will be still available so you can mix and match.

Default templates

Template name Description
:adaptive_card A card with the body of an adaptive card for more complex scenarios
:facts_card A card with title, subtitle and a list of facts
:test_card A simple text message without any configurable content for testing

Custom Templates

Custom templates are stored in the directory specified by the configuration option template_dir. As an array of strings, describing the path relative to the project root. When using Rails or Bundler their root is used, otherwise it is the current working directory.

Templates are json files with the extension .json.erb. The file is parsed and populated by the ruby ERB module.

Builder

You can use TeamsConnector::Builder to create Adaptive Cards directly in ruby. YOu can output the result of the builder as JSON for future use with TeamsController::Notification::AdaptiveCard#pretty_print.

builder = TeamsConnector::Builder.container do |content|
  content << TeamsConnector::Builder.text("This is an introductory text for the following facts")
  content << TeamsConnector::Builder.facts { |facts|
    facts["Usage"] = "Testing the adaptive card builder"
    facts["Quokka fact"] = "They are funny little creatures"
  }
end

TeamsConnector::Notification::AdaptiveCard.new(content: builder).deliver_later

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

You can define the channels you use for testing in the file bin/channels.yml or directly in the bin/console script.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/qurasoft/teams_connector. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.