New command: Create Microsoft Teams Bot

stephanbisser commented 3 years ago

Usage

bots bot add [options]

Description

As a user I want to use one single command to create/provision all necessary resources needed to add a bot to Microsoft Teams (and in the future to other M365 services like SharePoint Online etc.). Therefore the following resources/services are required:

Azure AD App Registration
Azure Bot Channel Registration

In addition the Microsoft Teams channel should be enabled on the Bot Channel Registration service to be able to use the bot in Teams. If possible, verify upfront if the specified handle is available as handles must be unique globally.

Options

Option	Description
`--handle <handle>`	The bot's handle to be used for the Bot Channel Registration
`-s, --subscriptionId <subscriptionId>`	The Azure Subscription ID to be used for provisioning the resources in
`-r, --resourceGroupName <resourceGroupName>`	The name of the Resource Group to be used for provisioning the resources in
`-p, --pricingTier [pricingTier]`	The pricing tier for the Bot Channel Registration Services: `F0, S1`. Default `F0`
`-m, --messagingEndpoint <messagingEndpoint>`	The messaging endpoint of the bot (e.g.: https://yourbotapp.com/api/messages)

waldekmastykarz commented 3 years ago

Looks awesome!

A few question comments, before we continue:

let's drop -h as the short for --handle, because -h is already used by --help
subscriptionId: does it happen often that you work with an account that has access to multiple subscriptions? I wonder if this is something that we should set CLI-wide or if it should stay limited to just this one command

@wictorwilen is there anything else you think we should consider for the first implementation of this command?

stephanbisser commented 3 years ago

@waldekmastykarz my take on that: regarding -h makes sense, should we just use --handle or shall we add another shortcode here? regarding subscriptionId as a dev you most of the time have a personal Azure subscription as well as a test/dev susbcription shared across a team and maybe also a prod subscription so we should definitely think about that but it would make sense to set it "globally" meaning CLI-wide

waldekmastykarz commented 3 years ago

regarding -h makes sense, should we just use --handle or shall we add another shortcode here?

Let's use --handle for now. We can always introduce a short in the future if there's a good candidate that's intuitive

regarding subscriptionId as a dev you most of the time have a personal Azure subscription as well as a test/dev susbcription shared across a team and maybe also a prod subscription so we should definitely think about that but it would make sense to set it "globally" meaning CLI-wide

I've just checked and I don't think that we have any other command that requires a subscription ID. With that, we could make it easy for now by following your spec. Later, should we get more commands that need the subscription ID, we could change the subscriptionId here to be optional and we could allow for configuring the subID centrally. Would that work?

stephanbisser commented 3 years ago

sounds good to me!

garrytrinder commented 3 years ago

Let's use --handle for now. We can always introduce a short in the future if there's a good candidate that's intuitive

We can't use -h as that is the global short code for --help ✋

wictorwilen commented 3 years ago

Since handle is globally unique I think it would be great to 1) have a dedicated error message for that, or 2) have an option to create a random handle or 3) a separate command that can be used to verify if handle is available

garrytrinder commented 3 years ago

Since handle is globally unique I think it would be great to 1) have a dedicated error message for that, or 2) have an option to create a random handle or 3) a separate command that can be used to verify if handle is available

1) Makes sense to have a dedicated error 2) We could introduce a --withHandle similar to how we use --withSecret in aad app add command to state that you want a randomly assigned value 3) something like bot handle verify?

waldekmastykarz commented 3 years ago

Is there a case where you'd want to use a random handle? Wouldn't that cause issues invoking the bot?

As for checking if the specified handle exists, I think that's a great idea. Is there an API that we could use for this or do we need to look out for an error that we might get if it exists?

wictorwilen commented 3 years ago

@waldekmastykarz not really a reason for using a random one tbh, except when you want to make one-off demos. Perhaps that would be better to be implemented as a script combining the command with a verify command...

stephanbisser commented 3 years ago

Is there a case where you'd want to use a random handle? Wouldn't that cause issues invoking the bot?

As @wictorwilen mentioned only for demo purposes I guess, but even there I would not want to create a random handle

As for checking if the specified handle exists, I think that's a great idea. Is there an API that we could use for this or do we need to look out for an error that we might get if it exists?

I'm not aware of an API so we would need to check what the Azure Portal does and if we discover something here

waldekmastykarz commented 3 years ago

I've updated the spec removing -h and adding a remark about checking the handle upfront if possible.

One more thing: for the messagingEndpoint does it feel more intuitive to use -m or -e as the short?

wictorwilen commented 3 years ago

How about update a bot? To me, being able to update the messaging endpoint is the most crucial part.

stephanbisser commented 3 years ago

@wictorwilen that would definitely be a good command as well, but I guess we should have that separated right?

One more thing: for the messagingEndpoint does it feel more intuitive to use -m or -e as the short?

@waldekmastykarz I'd say -m

waldekmastykarz commented 3 years ago

@wictorwilen that would definitely be a good command as well, but I guess we should have that separated right?

yes, that would be bots bot set. Shall we do a quick spec for it as well? We could start with supporting updating just the messaging endpoint and take it from there.

waldekmastykarz commented 3 years ago

@stephanbisser, @pnp/cli-for-microsoft-365-maintainers just to double check: are we spec-complete and ready to implement?

garrytrinder commented 3 years ago

I've just made some minor amends on the options and descriptions to make them more consistent with our docs, but all looks good to me 👍

pnp / cli-microsoft365