Add chat context to chatops

[blag]

This is part of the work to add a Microsoft Teams (via BotFramework) adapter.

Microsoft Teams needs a bit more context other than the requesting user and the channel name.

Instead of adding the minimum amount of context, this PR adds a context parameter to the post_ actions in the chatops pack and adds it to the notify on_complete dictionary. The context parameter maximizes the amount of information available to the notification mechanism, in the hopes that it can be reused by other adapters.

• st2chatops in Cleanup a bit and use hubot-botframework for MS Teams support st2chatops#121
• hubot-stackstorm changes in Cleanup a bit and use hubot-botframework for MS Teams support hubot-stackstorm#164
• Documentation for configuring Microsoft Teams with BotFramework in Add configuration steps for Microsoft Teams to ChatOps st2docs#872

[Kami]

I like the idea of more generic context parameter.

Only thing I don't like about such "generic" dictionary parameters is usually lack of schema / structure. We had a "problem" with that in Mistral workflows where it wasn't always clear which attributes are available to the user in that context dictionary.

So at the very least we should document possible attributes in this dictionary where it's applicable.

[blag]

@Kami

Only thing I don't like about such "generic" dictionary parameters is usually lack of schema / structure. We had a "problem" with that in Mistral workflows where it wasn't always clear which attributes are available to the user in that context dictionary.

It's not really possible to define much of a schema - the actual dictionary schema will be specific to each hubot adapter. But it should only be passed back to the chatops.post_message action and forwarded back to hubot. The hubot adapter, also being specific to each chat service, will know what to do with it.

[nzlosh]

I just saw this pull request. Will these contexts specific to hubot adapters be documented or would other project maintainers using the chatops pack need to reverse engineer hubot to maintain compatibility?

[blag]

@nzlosh Right now, the only provider that uses the source_context is Microsoft Teams, and the context is simply sent right back to the hubot-botframework adapter - it isn't actually used by anything else (yet).

ChatOps is one place where we can use better documentation, including developer documentation. While we can document the entire context received from each supported chat provider, some providers may change their sent context over time. Slack, especially, changes their API a lot. So while we will try to document the context sent by each supported provider, it will be a "best effort" approach, and certainly may be out of date as time goes on/across version changes. This is, of course, an area where we would appreciate pull requests from the community.

[nzlosh]

Thanks @blag, I appreciate the explanation and understand external API stability guarantees are not easy to handle. My concern with the addition of the free form source_context field is StackStorm's API is no longer guaranteed from an external project maintainer point of view.

The match_and_execute API is very explicit with expected data structures and their intended use.

object
command string Command string to parse (eg: message from chat) required
user string User that requested the execution (or messaged in chat) required
source_channel string Channel the message is from (different than the notification channel) required
notification_channel string StackStorm notification channel to use to respond
notification_route string StackStorm notification route to use to respond

The new field source_context can only really be documented as an object without any additional structured information because that depends on hubot adapters and can change independently of the official st2 API.

I raise this point with maintaining coherency and compatibility in mind for projects that use the action-alias API and chatops pack. I know there aren't many projects impacted by this concern and I understand that there is no requirement for StackStorm to provide such a contract.

[blag]

The problem with source_channel is that it doesn't apply to all chat providers. The MS Teams provider, for instance, sends a giant object with all sorts of redundant data, and expects to receive that same giant object when posting back to the provider. The concept of a "source channel" simply does not apply to users using MS Teams - it needs the whole object, and the object cannot be constructed because MS Teams is not built around a Slack-like (or really IRC-like) concept of channels.

The end result is that there are now two paths for providers to provide data - the user and source_channel strings, or one giant source_context blob. The giant object blob can encapsulate user and source_channel strings, so I think that is a better paradigm to use. Of course I do recognize that current users expect the current user and source_channel strings, so at some point in the future, if I have my way there will be a deprecation period where we transition to using a source_context object. But this is in no way set in stone.

At this point it is premature to bikeshed about what this will look like, as I have a lot more work to do before approaching this change again.