scenarios.md

Scenarios

This feature can help with attributes guessing for your custom event. Imagine user triggered your event, but unfortunately from the message bot cannot parse all the attributes. In this case, instead of throwing of error message, you can trigger the scenario for your event, which will ask a questions and set needed variables for your custom event.

Demo

With tagging of the bot-user

Without tagging of the bot-user

How to stop active scenario

To stop the scenario, please use the following phrases:

• stop!
• stop scenario!
• exit
• stop
• cancel Once bot receives some of these phrases, he will try to stop the active scenario in the current channel, where the message posted.

Database

Before describing of the code base, let's check the database schema and see how on the database level the scenario looks like. First, let's have a look on the database schema

As you can see we have the scenario_id in the questions table. This field will be used for grouping of the questions.

On the screenshot below you can see that not each question row has the filled question attribute. This is because initially question attribute of questions table is used as the question from the user and answer field is used as answer from the bot. And in case of the scenario, the bot asks user and we don't expect the question from the user.

Each scenario must have:

1. at least 1 question
2. a connected event with the alias defined(otherwise the custom event will not be triggered)
3. only first question of scenario should have the filled question attribute and all next questions should have that field as empty string

Conversations

Each trigger of scenario, opens a conversation for the channel from where the message was received. That means, once the bod started the scenario, you will not be able to ask him other questions, because he is expecting the answers for the open scenario conversation.

Below you can see how the example of how the scenario processing looks like

Installation of scenario

Each scenario with multiple questions and answers should have not less than 2 questions, otherwise it will not be handled as scenario, but as a simple question. So for installation you will need to create the initial question and answer first and then, based on created scenario ID, connect to it one or more questions.

Here you can see the example of Install method for your custom event, where we install the scenario

// Install method for installation of event
func (e EventStruct) Install() error {
    log.Logger().Debug().
        Str("event_name", EventName).
        Str("event_version", EventVersion).
        Msg("Triggered event installation")

	return container.C.Dictionary.InstallNewEventScenario(database.EventScenario{
		EventName:    EventName,
		EventVersion: EventVersion,
		//The triggers, which will trigger the event
		Questions: []database.Question{
			{
				Question:      "who are you?",
				Answer:        fmt.Sprintf("Hello, my name is %s", container.C.Config.MessagesAPIConfig.BotName),
				QuestionRegex: "(?i)who are you?",
				QuestionGroup: "",
			},
		},
        RequiredVariables: []database.ScenarioVariable{
            {
                Question: "First scenario question",
            },
            {
                Question: "Second scenario question",
            },
        },
	})
}

As you can see, in the database.EventScenario struct you can define multiple triggers for our event and its variables.

In this example, each database.ScenarioVariable is a variable, which need to be filled. The variable questions will be asked in the order you specified in Install method.

Usage of scenario variables in event

Once the scenario was triggered and your event was called, in order to retrieve the conversation in your event you can call conversation.GetConversation method.

currentConversation := conversation.GetConversation(message.Channel)

Then, in the received object you will find the currentConversation.Scenario.RequiredVariables attribute, which will contain all required variables, you defined in your scenario with their answers.

As an example, please check out the examplescenario event.