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  ![demo-tagging](images/scenario-demo-tagging.gif)
     8  
     9  ### Without tagging of the bot-user
    10  ![non-demo-tagging](images/scenario-demo-without-tagging.gif)
    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  ![database-schema](images/database-structure.png)
    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  ![scenario-list-questions](images/scenario-list-questions.png)
    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  ![scenario-message-processing](images/scenario-message-processing.png)
    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.