勤怠管理 Bot の概要

    ★ 注意: フリープランの場合、カレンダーAPIの利用が制限されるため、勤怠管理 Botを利用することはできません。

    勤怠管理 Bot では、Bot との対話形式による出退勤時間の登録を提供します。メンバーが Bot を利用して出退勤時間を入力すると、管理者の共有カレンダーにその時間を予定として書き込みます。Bot と連携した管理者アカウントのカレンダーにすべてのメンバーの出退勤情報が記録されるので、他人の出退勤予定を見ることはできないよう制限されます。

    参考

    • フリープランではカレンダー API を利用できないため、勤怠管理 Bot からカレンダーへの登録に対応できません。ソースコードを参考に出退勤時間をトーク送信するよう切り替えるなど改修を検討してください。

    会話シナリオ

    勤怠管理 Bot のすべての会話シナリオと使用されるテンプレートメッセージは以下の通りです。 これらの内容が自分達に適しているか確認し、必要に応じてシナリオを変更することも検討してください。

    ソースコード説明

    Heroku アプリの配布後は Procfile ファイルに定義された操作が自動で実行されます。勤怠管理 Bot の Procfile は環境を初期化し main.py を実行して Daemon を起動します。

    その他、勤怠管理 Bot に含まれるトーク Bot API やカレンダー API を使用する関数は以下を参照してください。

    例) attendance_management_bot.externals.calendar_req.create_calendar の実際のソースコードはattendance_management_bot/externals/calendar_req.py 内の create_calendar 関数で確認できます。

    参考

    開発言語及び環境

    開発環境及び使用された開発言語は以下のとおりです。

    • Python3
    • Tornado framework
    • Postgres

    Procfile

    https://devcenter.heroku.com/articles/procfile:

    Heroku アプリは、起動時にアプリで実行される命令を指定する Procfile を含みます。Procfile を利用して以下のようなさまざまなプロセスタイプを宣言することができます。

    • アプリの Web サーバー
    • さまざまなワーカープロセスタイプ
    • clock などのシングルトンプロセス
    • 新しいリリースが配布される前に実行するタスク

    勤怠管理 Bot の Procfile は以下の通りです。

    release: python scripts/initialize.py
    web: python main.py --port=$PORT
    

    Initialize environment

    #!/bin/env python
    # -*- coding: utf-8 -*-
    import sys
    sys.path.append('./')
    from attendance_management_bot.initDB import init_db
    from attendance_management_bot.registerBot import init_bot
    
    
    def main():
        init_db()
        init_bot()
    
    
    if __name__ == "__main__":
        main()
    

    データベース初期化

    attendance_management_bot.initDB.init_db()

    データ構造を初期化します。

    テーブルリスト:

    • bot_calendar_record
    • system_init_status
    • bot_process_status

    attendance_management_bot.initDB.create_calendar_table()

    カレンダーテーブルを作成します。 メンバーの出勤および退勤情報を保存します。

    カラム 説明
    schedule_id 予定ID。各メンバーの出退勤の予定を作成します。
    account ユーザーアカウント
    cur_date 現地時間を基準にした現在の日付
    begin_time 予定開始時間 (出勤時間)
    end_time 予定終了時間(退勤時間)
    create_time 予定の作成時間

    attendance_management_bot.initDB.create_init_status_table()

    初期化状態テーブルを作成してシステム初期化情報を保存します。(Botの登録、リッチメニューの登録、カレンダー作成)。

    カラム 説明
    action 初期化項目(Bot 番号、リッチメニュー、カレンダー ID…)
    extra        初期化データまたは状態
    create_time       記録作成時間

    attendance_management_bot.initDB.create_process_status_table()

    タイプと状態テーブルを作成します。ユーザーの状態情報を保存します。

    m_status:enum タイプ値

    タイプ 説明
    wait_in メンバーによる出勤時間の入力待ち
    in_done 出勤時間の入力完了
    wait_out メンバーによる退勤時間の入力待ち
    out_done 退勤時間の入力完了

    m_process:enumタイプ値

    タイプ 説明
    sign_in_done 出勤操作の完了
    sign_out_done 退勤操作の完了

    タイプがすでに存在している場合、duplicateobject の例外が発生します。

    bot_process_status table

    カラム 説明
    account   ユーザーアカウント  
    cur_date 現地時間を基準にした現在の日付
    status m_status 値
    process m_process 値
    create_time 記録作成時間

    Bot の登録

    attendance_management_bot.registerBot.init_bot()

    Bot 情報を初期化します。Bot が登録されていない場合、システムの開始時点で失敗します。

    Bot 登録の前に system_init_status テーブルをクエリします。 Bot がすでに登録されている場合、もう一度登録する必要はありません。 未登録の場合、初期化プロセス中に Bot はシステム初期化状態テーブル(system init status table)に保存されます。これは Bot の登録が完了したことを意味します。

    attendance_management_bot.registerBot.register_bot(photo_address)

    トーク Bot を登録します。

    参考

    パラメータ 説明
    photo_address Bot プロフィール画像のアドレス
    プロフィール画像を変更する場合、
    image/にある当該ファイルを変更する。PNGのみ可。
    戻り値
    Bot 番号

    attendance_management_bot.registerBot.register_bot_domain(bot_no)

    トーク Bot のドメイン登録を行います。

    参考

    パラメータ 説明
    bot_no Bot 番号

    Bot の実行

    #!/bin/env python
    # -*- encoding: utf-8 -*-
    
    # from gevent import monkey
    # monkey.patch_all()
    """
    main function for attendance_management_bot
    """
    import signal
    from daemonize import Daemonize
    from tornado.options import define, options
    from attendance_management_bot.attendance_management_bot import *
    from attendance_management_bot.settings import *
    
    
    define("daemonize", default=False, help="daemon mode")
    define("pidfile", default=CALENDAR_PID_FILE,
           help="the path of pid file, default None")
    
    
    if __name__ == "__main__":
        options.parse_command_line()
    
        signal.signal(signal.SIGPIPE, signal.SIG_IGN)
        signal.signal(signal.SIGINT, sig_handler)
        signal.signal(signal.SIGQUIT, sig_handler)
        signal.signal(signal.SIGTERM, sig_handler)
        signal.signal(signal.SIGHUP, sig_handler)
    
        if options.daemonize:
            daemon = Daemonize(app="attendance_management_bot",
                               action=start_attendance_management_bot,
                               pid=options.pidfile)
            daemon.start()
        else:
            start_attendance_management_bot()
    

    attendance_management_bot.attendance_management_bot.start_attendance_management_bot()

    attendance_management_bot 実行コード

    tornado.httpserver ノンブロッキング、シングルスレッド HTTP サーバー

    参考

    tornado.routing ルーティング設定

    参考

    Tornado と共に提供されるイベントループを使用する場合、aioredis など asyncio を基盤とした他パッケージを併用することはできません。

    attendance_management_bot.router.getRouter()

    パス情報でアプリを照会します。

    参考

    StaticFileHandler はディレクトリから静的コンテンツを提供できるシンプルなハンドラです。

    参考

    class attendance_management_bot.callbackHandler.CallbackHandler(application, request, **kwargs)

    ユーザーのリクエストを処理します。

    HTTP リクエストハンドラのための tornado.web.RequestHandler 基本クラスです。

    参考

    post()

    ハンドラを該当する HTTP メソッドで実装します。 参考項目:attendance_management_bot/router.py

    class attendance_management_bot.check_and_handle_actions.CheckAndHandleActions()

    ハンドラを作成し実行する際に利用されるファクトリ。

    execute(body)

    body パラメータを確認してハンドラを実行します。 参考リンクを参照してください。

    参考

    Bot API 関数

    attendance_management_bot.model.data.make_text(text, i18n_texts=None)

    テキストを作成します。

    参考

    戻り値
    テキストコンテンツ

    attendance_management_bot.model.data.make_quick_reply(replay_items)

    クイック返信メッセージを作成します。

    参考

    パラメータ 説明
    replay_items make_quick_reply_item 関数が返すオブジェクト配列。
    戻り値
    クイック返信コンテンツ

    画像カルーセル:

    参考

    Request URL https://apis.worksmobile.com/r/{API ID}/message/v1/bot/{botNo}/message/push

    POST (Content-Type: application / json; charset = UTF-8)

    パラメータ 説明
    columns 画像カルーセル
    戻り値
    画像カルーセルコンテンツ

    attendance_management_bot.externals.send_message.push_message(account_id, content, header=None)

    ユーザーにメッセージを送信します。パッケージは JSON 構造に従います。

    参考

    パラメータ 説明
    account_id ユーザーアカウント
    content トークコンテンツ
    header HTTP ヘッダー

    Calendar API 関数

    attendance_management_bot.externals.calendar_req.create_calendar()

    カレンダーを作成します。

    参考

    戻り値
    カレンダー ID

    attendance_management_bot.externals.calendar_req.create_schedule(current, end, begin, account_id, title)

    予定を作成します。

    参考

    戻り値
    予定 ID

    attendance_management_bot.externals.calendar_req.modify_schedule(calendar_uid, current, end, begin, account_id, title)

    予定を修正します。

    参考

    戻り値
    予定 ID

    Bot のリッチメニューの関数

    attendance_management_bot.externals.richmenu.upload_content(file_path)

    リッチメニューの背景画像をアップロードします。

    参考

    パラメータ 説明
    file_path リソースのローカルパス
    戻り値
    リソース ID

    attendance_management_bot.externals.richmenu.make_add_rich_menu_body(rich_menu_name)

    リッチメニューの本文を追加します。

    参考

    パラメータ 説明
    rich_menu_name リッチメニュー名
    戻り値
    リッチメニュー ID

    attendance_management_bot.externals.richmenu.set_rich_menu_image(resource_id, rich_menu_id)

    リッチメニュー画像を設定します。

    参考

    パラメータ 説明
    resource_id リソース ID
    rich_menu_id リッチメニュー ID
    戻り値

    attendance_management_bot.externals.richmenu.set_user_specific_rich_menu(rich_menu_id, account_id)

    メンバー個別のリッチメニューを設定します。

    参考

    パラメータ 説明
    rich_menu_id リッチメニュー ID
    account_id ユーザーアカウント

    attendance_management_bot.externals.richmenu.get_rich_menus()

    リッチメニューを照会します。

    参考

    戻り値
    リッチメニューリスト

    attendance_management_bot.externals.richmenu.cancel_user_specific_rich_menu(account_id)

    メンバー個別のリッチメニューを解除します。

    参考

    パラメータ 説明
    account_id ユーザーアカウント

    Bot i18n 関数

    /tools/gen.sh ツールを利用して.po、.mo ファイルを作成できます。

    参考

    実行

    $ ./tools/gen.sh [filename] [po|mo] [path]

    パラメータ 説明
    filename .po、.mo ファイルを作成する際に利用されるPythonソースファイル名
    type 「po」は.poファイル、「mo」は.moファイルの作成を意味します。
    path Python ソースファイルの相対パス。末尾は「/」にしないでください。

    ソースファイル名に応じて .po ファイルは「locales/../LC_MESSAGES」に配置します。

    ステップ

    1. 「.po」ファイルを作成します。

      ./tools/gen.sh test_i18n.py po test
      確認:locales/../LC_MESSAGES/test_i18n.po

    1. 多言語の文言を「.po」ファイルに入力します。
    1. 「.mo」ファイルを作成します。

      ./tools/gen.sh test_i18n.py mo test
      確認:locales/../LC_MESSAGES/test_i18n.mo

    attendance_management_bot.model.i18n_data.get_i18n_content_by_lang(fmt, local, lang, **kw)

    キーストリングに応じて他言語の文言を照会します。

    参考

    パラメータ 説明
    fmt 多言語のキーストリング 例:'This is a translatable string.'
    local 'fmt'に該当する地域
    lang 言語['en', 'ko', 'ja']
    kw 変数パラメータリスト
    fmt1:キーストリングはフォーマットストリングにあるサブストリングの多言語パラメータです。日付の形式を定めるのに使用されます。
    date:日時(datetime)オブジェクトの現地時間
    戻り値
    多言語の文言

    attendance_management_bot.model.i18n_data.get_i18n_content(fmt, local, **kw)

    フォーマットパラメータ ID に応じた多言語データ構造を照会します。

    参考

    パラメータ 説明
    fmt 多言語のキーストリング 例:'This is a translatable string.'
    local 'fmt'に該当する地域
    kw 変数パラメータリスト
    Common parameters:function:さまざまな言語をカプセル化するのに利用されるコールバック関数
    fmt1:キーストリングはフォーマットストリングにあるサブストリングの多言語パラメータです。日付の形式を定めるのに使用されます。
    date:日時(datetime)オブジェクトの現地時間
    戻り値
    パラメータに当該パッケージのパッケージ関数が含まれている場合、カプセル化された多言語辞書オブジェクトが返されます。
    パラメータにパッケージ関数が含まれていない場合、多言語リストオブジェクトが返されます。

    attendance_management_bot.model.i18n_data.make_i18n_button(text, actions, local, fmt)

    多言語ボタンオブジェクトを作成します。

    参考

    attendance_management_bot.model.i18n_data.make_i18n_text(text, local, fmt, **kw)

    多言語テキストオブジェクトを作成します。

    参考

    attendance_management_bot.model.i18n_data.make_i18n_message_action(post_back, local, label, fmt_label=None, text=None, fmt_text=None)

    多言語メッセージアクションオブジェクトを作成します。

    参考

    • Action Objects
    • 参考:attendance_management_bot/model/data.py::make_message_action

    多言語画像カルーセルオブジェクトを作成します。

    参考

    タイムゾーン設定

    勤怠管理 Bot のタイムゾーンは Asia/Tokyo に設定されています。必要に応じて、ソースコードから希望する国/都市の時間帯に変更することができます。

    タイムゾーンを変更するには、conf フォルダ内にある config.py ファイル内の #Timezone を修正してください。

    TZone =”{希望する国/都市}”に変更することができます。

    参考

    予定名の言語コード設定

    勤怠管理 Bot は基本的に出退勤の予定名を日本語で作成します。必要に応じて、ソースコードから英語や韓国語で予定タイトルを作成するよう言語コードを変更できます。

    言語コードを変更する場合、conf フォルダ内の config.py ファイルで# default language 項目を修正します。

    DEFAULT_LANG =”{言語コード}”で変更できます。

    参考

    • 言語コードは'ja(日本語)'、'en(英語)'、'ko(韓国語)'のうち1つに設定できます。