Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Prerequisite:

  1. To install the MID agent, you need Python and the Telethon library on a server. To install the library, run the following commands on the command line (after downloading and installing Python):

    Panel

    python3 -m pip install --upgrade pip
    python3 -m pip install --upgrade telethon


  2. You need an Android device with a physical SIM card and with the Telegram application installed. The Telegram account should be created based on the SIM card number.
  3. On the Android device, you also need to install the Pydroid 3 and the Telethon library application to run scripts.

On the Administrator's server


Note

For the swarming session to work smoothly, the MID agent must be hosted on the device, for example, the virtual machine (VM) on which it will run non-stop.

To set up a Telegram group for a major incident, do the following:

On the Administrator's computer

  1. Create a record in the MID Server (sys_mid_server) table. To do so, click New and complete the fields of the new record as follows:

    FieldMandatoryDescription
    NameYA name of the infrastructure server, that will be displayed in the list, for example, TgBotMIDServer.
    Host NameYA host name of the external server to connect to, for example, mid_server.
    UserYA user name who will have access to the functionality of the infrastructure agent. The user must have the admin role. 


  2. Download Infrastructure the MID Agent acrchive.
  3. On disk C, create a folder named MID_agent.

    Info

    To create Telegram groups on different instances, create separate folders for the MID agent of each instance with different names.


  4. Move the downloaded .exe and .env files to the created folder in Step 2.
  5. In the .env file, set the following configurations:

    To continue, ensure that Python and the Telethon library are installed on your computer
    VariableValue
    MID_API_USERNAMEA user login, stated in the MID Server (sys_mid_server) record, created in Step 1.
    MID_API_PASSWORDA user password, stated in the MID Server (sys_mid_server) record, created in Step 1.
    MID_API_SERVERIDID of the earlier created record in the MID Server (sys_mid_server) table.
    MID_API_ENDPOINT Instance, that the MID server will run.
    Note
    .
    To install the library, write in the command line:
    Code Block
    python3 -m pip install --upgrade pip
    python3 -m pip install --upgrade telethon


  6. Create a Telegram client. 

    Info

    To create a Telegram client, complete the steps below:

    1. Get registered in Telegram, using any client name.2. Follow the https://my.telegram.org link for authorization.

    32. Complete the form on the https://my.telegram.org/apps website to receive the URL and parameters of api_id and api_hash needed for the users' authorization.

    It is possible to link only one api_id to the telephone number.


  7. Download a script archive, and add the scripts to the MID_agent folder created at the Step 3. 
    The four scripts in the folder are:
    • createGroup – to create a group,
    • closeGroup – to restrict commenting upon the completion of the incident and changing its state to Completed,
    • deleteGroup – to delete a Telegram group,
    • clientInformation – to store api_id and api_hash.
  8. Open the “clientInformation” script clientInformation script and add the api_id and api_hash values received when creating a Telegram client.
  9. Create a .py file and add the following test start script there:

    Code Block
    languagepy
    titleTest Start script for Telegram
    linenumberstrue
    from telethon import TelegramClient
    import clientInformation 
    
    client = TelegramClient('swarming', clientInformation.api_id, clientInformation.api_hash)
    
    async def main(): 
        me = await client.get_me()
        print(me)
    
    with client:
        client.loop.run_until_complete(main())
    
    
  10. Place the created file in the MID_agent folder created earlier.
  11. Run manually the Python test script using the Telethon library. To do so, in the command line, go to the directory of the created folder (cd full path to the folder) and execute the command python script name.py.
  12. In the command line, you will be asked to enter a mobile phone number. Enter the mobile phone number that the Telegram account is registered with.
  13. In the command line, you will be asked to enter a verification code. Type it in the command line as soon as you receive it.
  14. As a result, the system returns information about the current user in the command line – it means everything has been set correctly.
  15. Complete the user's authorization that the system will require. As a result, in the MID_agent folder, a “swarming.session” file is created.
On the SimpleOne instance

  1. Configure the instance as described below

On the SimpleOne instance
Anchor
instance configuration
instance configuration


  1. Create three scripts in the MID Scripts (sys_mid_script)table. To do so:
    1. In the MID Scripts (sys_mid_script)table, click New. A new script form opens.
    2. Add “createGroup” as createGroup as the name of the script.
    3. In the Script field, add the path to the script on your computer server and the parameters, as shown below.

    4. Repeat the Steps a-c to add “closeGroup” closeGroup and “deleteGroup” deleteGroup scripts.


      createGroup
      Scriptpython C:\User's Path\createGroup.py $botUserName $incidentDispalyName $titleMessage $mainInformation


      closeGroup
      Scriptpython C:\User's Path\closeGroup.py $chatId


      deleteGroup
      Scriptpython C:\User's Path\deleteGroup.py $chatId


      Note

      When using several MID agents for the operation of Telegram groups on different instances, specify the path to the necessary agent folder in the script.



  2. Go to the System Properties (sys_property) table, set the following values for the properties:


    System PropertyValue
    itsm.telegram_bot.swarming_session   true
    itsm.telegram_bot.mid_server_idMID Server Record ID The ID of the MID Script record created in Step 1 of the On the Administrator's computerserver section of this article.
    itsm.telegram_bot.mid_create_group_script_idMID Scripts Record ID The ID of the MID Script record for a group creation (createGroup script)
    itsm.telegram_bot.mid_close_group_script_idMID Scripts Record ID for comments restriction The ID of the MID Script record that disables comments in a Telegram group of the swarming session (closeGroup script)
    itsm.telegram_bot.mid_delete_group_script_idMID Scripts Record ID for a group removal The ID of the MID Script record that deletes a Telegram group of the swarming session (deleteGroup script).


  3. Create connections with the For client and Router bots, which must be created in advance via @BotFather in Telegram.

On the Android device 
Anchor
file
file


  1. Transfer the start script and the clientinformation.py file with the filled information to the Android device.
  2. Using the Pydroid 3 app, run the Python start script using the Telethon library manually.
  3. After successfully running the start script, enter a mobile phone number in the command line. Enter the mobile phone number that the Telegram account is registered with.
  4. If logging into the account is additionally protected by a password, enter it after you have entered the number.
  5. Then enter a verification code. Type it in the command line as soon as you receive it.
  6. As a result, the system returns information about the current user in the command line – it means everything has been set correctly.
  7. A new swarming.session file and a py_cache folder are created. The lifetime of the file is limited to 7–10 days if it is not used. If the file is out of date, it should be recreated.
  8. Transfer the created file and folder to the server in the agent folder. If the server has an older version of swarming.session and a py_cache folder, they must be removed before running the script.

End of setup and testing


  1. Play the start script and enter your Telegram account number.
  2. From the command line, run the MID agent in the folder that you created earlier. Run the MID agent from the file in the earlier created folder MID_agent.
  3. Go to a major incident form. Click Start Swarming on the top of the page. 
  4. The In the modal window that appears, contains there is a list of the recipients of the invitation to the Telegram group. Clicking Clicking Start Swarming on the modal window initiates a Telegram group, and a createGroup record appears in the MID Queue (sys_mid_queue)table. The Description field of the createGroup record is automatically filled with the incident number.

    FieldDescription
    RequestBotUserId, the incident name and the first message content that is sent to the Swarming Session participants
    ServerTgBotMIDServer.
    ScriptThe name of the executed script
    ResponseA chat ID created and a lint to the group. The chat ID is stored in the Telegram Chat Bindings with Incident (sys_telegram_chat_bindings_with_incidents) table.
    StateDone when executed
    Processed atDate and time of the script execution
    DescriptionIncident number

    If the connection with the Telegram bot is lost or failed, (see the ITSM Telegram Botarticle for more information) a toast message “Telegram bot not connected” appears, and a modal window does not open.

  5. When the incident state is changed to Completed,closeGroup record in the MID Queue (sys_mid_queue) table appears. Since then, commenting in the group is unavailable, but the participants can read the messages.

    FieldDescription
    RequestA chatId parameter
    ServerTgBotMIDServer
    ScriptThe name of the executed script
    ResponseNo response
    StateDone when executed
    Processed atDate and time of the execution
    DescriptionEmpty


  6. When the incident state is changed to Closed,a deleteGroup record in the MID Queue (sys_mid_queue)table appears. The linked Telegram group is deleted.

    FieldDescription
    Request

    A chatId parameter

    ServerTgBotMIDServer
    ScriptThe name of the executed script
    ResponseNo response
    StateDone when executed
    Processed atDate and time of the execution
    DescriptionEmpty


Troubleshooting


In cases when a swarming group is not created or communication between the Telegram group and the SimpleOne instance is not configured, do one of the following:

  • Reconnect the Router bot on the instance with a new token. You can request a token through @BotFatner in Telegram.
  • On the server in the MID_agent folder сlose and re-run the start script or create a swarming.session file following the steps above and upload it to this folder again.

Table of Contents
absoluteUrltrue
classfixedPosition
printablefalse