github.com/sharovik/devbot@v1.0.1-0.20240308094637-4a0387c40516/documentation/scenarios.md (about) 1 # Scenarios 2 This feature can help with attributes guessing for your custom event. 3 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. 4 5 ## Demo 6 ### With tagging of the bot-user 7  8 9 ### Without tagging of the bot-user 10  11 12 ### How to stop active scenario 13 To stop the scenario, please use the following phrases: 14 - `stop!` 15 - `stop scenario!` 16 - `exit` 17 - `stop` 18 - `cancel` 19 Once bot receives some of these phrases, he will try to stop the active scenario in the current channel, where the message posted. 20 21 ## Database 22 Before describing of the code base, let's check the database schema and see how on the database level the scenario looks like. 23 First, let's have a look on the database schema 24 25  26 27 As you can see we have the scenario_id in the questions table. This field will be used for grouping of the questions. 28 29 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**. 30 And in case of the scenario, the bot **asks user** and **we don't expect the question** from the user. 31 32  33 34 Each scenario must have: 35 1. at least 1 question 36 2. a connected event with the alias defined(otherwise the custom event will not be triggered) 37 3. only first question of scenario should have the filled `question` attribute and all next questions should have that field as empty string 38 39 ## Conversations 40 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. 41 42 Below you can see how the example of how the scenario processing looks like 43 44  45 46 ## Installation of scenario 47 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. 48 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. 49 50 Here you can see the example of Install method for your custom event, where we install the scenario 51 ```go 52 53 // Install method for installation of event 54 func (e EventStruct) Install() error { 55 log.Logger().Debug(). 56 Str("event_name", EventName). 57 Str("event_version", EventVersion). 58 Msg("Triggered event installation") 59 60 return container.C.Dictionary.InstallNewEventScenario(database.EventScenario{ 61 EventName: EventName, 62 EventVersion: EventVersion, 63 //The triggers, which will trigger the event 64 Questions: []database.Question{ 65 { 66 Question: "who are you?", 67 Answer: fmt.Sprintf("Hello, my name is %s", container.C.Config.MessagesAPIConfig.BotName), 68 QuestionRegex: "(?i)who are you?", 69 QuestionGroup: "", 70 }, 71 }, 72 RequiredVariables: []database.ScenarioVariable{ 73 { 74 Question: "First scenario question", 75 }, 76 { 77 Question: "Second scenario question", 78 }, 79 }, 80 }) 81 } 82 ``` 83 84 As you can see, in the `database.EventScenario` struct you can define multiple triggers for our event and its variables. 85 86 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. 87 88 ## Usage of scenario variables in event 89 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. 90 ```go 91 currentConversation := conversation.GetConversation(message.Channel) 92 ``` 93 94 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. 95 96 As an example, please check out the [examplescenario](../events/examplescenario/event.go) event.