iPhoneでサクサク工数を登録しよう: TimeTracker NX × ショートカットアプリのカスタマイズ術

## この記事の概要
**TimeTracker NXを活用して、日々の工数実績登録を爆速＆超手軽にしませんか** :rocket: 

本記事では、TimeTracker NXのWeb APIとiPhoneのショートカットアプリを連携して工数実績登録を行う方法を解説します。とっても簡単です :muscle: 

:::note
TimeTracker NXはデンソークリエイト様が提供する、「工数管理・プロジェクト管理の見える化により、業務改善を支援するソフトウェア」です。 https://www.timetracker.jp
:::

:::note
本記事は[TimeTracker NXでプロジェクト管理を効率化しよう！ by グローバル・アスピレーションズ Advent Calendar 2024](https://qiita.com/advent-calendar/2024/timetrackercloud)に参加しています。
:::

### 成果物イメージ
![output.gif](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1553191/793bab5e-e194-89c9-d737-8ec53185b1c7.gif)

### 感想 & TimeTracker NXの推しポイント
本記事執筆にあたり、はじめてTimeTracker NXを使用しましたが、Web APIが提供されているため、外部のソフトウェアや、今回使用するショートカットアプリ等のツールと容易に組み合わせられます。それにより、**現在の業務の進め方に自然に溶け込めさせられそうであり、その点がTimeTracke NXの魅力なのでは**と感じました。

では、本文に入っていきましょう！

## 対象読者
- TimeTracker NXを現在使っていて、さらに便利に活用したい人
- TimeTracker NXは使ったことがないが、工数管理ツールに興味がある人
- iPhoneのショートカットアプリが好きな人

## この記事の構成
この記事では、架空のプロジェクト「家事・育児」に対して、頻繁に入力する「掃除」「洗濯」などの工数を爆速で記録することをテーマにします。

提供されているWeb UIから工数を登録してももちろん問題ないのですが、私自身の経験上、**工数登録はさっとできないと忘れる**という辛みがあります。これを解決するには身近なデバイス=スマートフォンでさっと入力できたら良いのでは？と思いませんか。

スマートフォンからもTimeTracker NXを操作できるのですが、**いやもっと爆速で操作することに価値がある！** と考え、この記事ではTimeTracker NXのWeb APIを活用し、iPhoneのショートカットアプリから工数を登録していきたいと思います。

説明のため、必要最低限ではありますが、TimeTracker NXの工数管理の機能から順に述べていきます。

1. TimeTracker NXを使った工数管理の全体像
1. TimeTracker NXのWeb API
1. ショートカットアプリのアクション作成

## TimeTracker NXを使った工数管理の全体像
TimeTracker NXで工数管理を行う上で押さえておきたい用語と大まかな進め方は以下の通りです。

### 押さえておきたい用語
| 用語 | 内容 | 例 |
| --- | --- | --- |
| プロジェクト | （そのまま） | 家事・育児プロジェクト |
| ワークアイテム | プロジェクト内で実施するアイテム。分類分けのための**パッケージ**と、実際の作業を表す**タスク**があり、どちらもワークアイテムである。 | パッケージ:掃除、タスク:風呂掃除 |

例えば下図のように、「掃除」というパッケージの下に、「風呂掃除」のようなタスクを作ることができます。

![スクリーンショット 2024-12-11 23.02.11.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1553191/fab8627d-55d0-9e7b-8e8c-e847f6205fab.png)

### 工数管理の大まかな進め方
1. プロジェクトを作成する。
1. ワークアイテムを定義し、メンバーを割り当てる。このメンバー割り当てはTimeTracker NX内では「リソース割り当て」と表記されています。
1. メンバーは作業を行うと、自分に割り当てられたワークアイテム一覧の中から該当するアイテムを選び、開始時間と終了時間を登録する。
1. 登録された工数を見える化・分析する。

工数を登録した後の画面は以下のようになります。（めっちゃ掃除するやん）

![スクリーンショット 2024-12-11 23.07.50.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1553191/dbb6e5ca-eb51-5cab-ee29-fae78698db01.png)

本記事では上記ステップのうち、3.の工数実績の登録にフォーカスします。


## TimeTracker NXのWeb API
TimeTracker NXは、クラウドサービスであるという特性を活かして、Web APIを提供して下さっています。Web APIを活用すれば、iPhoneのショートカットアプリなど、HTTPリクエストを取り扱えるツールからTimeTracker NXを操作可能！

ということで、本章ではWeb APIの仕様について要点をかい摘んで解説します。詳細なWeb API仕様は[こちら](https://docs.timetracker.jp/webapi/)をご覧ください。

### Web APIの概要
ベースURI(※後述)+リソース(例:`/auth/token`)を指定し、GET/POSTなどのリクエストを送ることで様々な操作が可能です。

[TimeTracker NXでプロジェクト管理を効率化しよう！](https://qiita.com/advent-calendar/2024/timetrackercloud)アドベントカレンダーで提供されているトライアル環境の場合、通常のGUIのURLと、それに対応するWeb APIのURIは以下のような関係です。シンプルですね。

| 項目 | URL/URI |
| --- | --- |
| GUI | https://ttnxevent.azurevm.net/advent/ |
| ベースURI | https://ttnxevent.azurevm.net/advent/api/ |

例えば以下のようなコマンドで、認証用トークンを取得できます。

```bash
curl -H "Content-Type:application/json" \
    -d '{"loginName":"foo", "password":"bar"}' \
    https://ttnxevent.azurevm.net/advent/api/auth/token
```

本記事では、公式リファレンス同様に、Web APIのURIはベースURIを除いた`/auth/token`のような表記を用いることにします。

### Web APIを活用した工数登録の流れ
[こちらの例](https://docs.timetracker.jp/webapi/sample/code/register-actual-time)や公式ドキュメントを参照しながら、今回実施したい工数登録に必要な事前準備とワークフローを整理しました。

#### 事前準備
- ユーザーの作成（トライアル環境では作成済み）
- プロジェクトの作成
- ワークアイテム(パッケージ・タスク)の作成
- ワークアイテムへのリソース割り当て(メンバーをアサインすること)

必須はここまでですが、後で必要になるため、よく使うワークアイテムのworkItemIdも控えておきます。

<details>
<summary>workItemIdの調べ方</summary>
<ol>
<li>認証用トークンの取得</li>
<li>プロジェクトのworkItemRootFolderのID取得。プロジェクトのIDが必要になりますが、これはGUIの管理画面でプロジェクトを開き、URLから調べるのが早いです。</li>
<li>ワークアイテム一覧の取得</li>
</ol>

ショートカットアプリでのキャプチャ画面ですが、すべて繋げるとこのようになります。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1553191/f463062b-650b-c80a-3b17-ae56e4b5f920.png)

得られたレスポンスから、例えば「風呂掃除」のIDは2220であることが分かります。（分かりやすさのため、下記のレスポンス例は不要な値などを除外した上で整形してあります。）

```json
{
  "fields": {
    "Name": "家事・育児",
    "SubItems": [
      {
        "fields": {
          "Name": "掃除",
          "SubItems": [
            {
              "fields": {
                "Name": "風呂掃除",
                "Id": "2220"
              }
            },
            {
              "fields": {
                "Name": "キッチン掃除",
                "Id": "2221"
              }
            }
          ],
          "Id": "2219"
        }
      }
    ],
    "Id": "2217"
  }
}
```

</details>

## ショートカットアプリのアクション作成
さて、いよいよショートカットアプリのアクション作成を行います！

全体的な処理の流れは以下の通りです。
1. 登録するワークアイテムの`{分かりやすい名前:ID}`の辞書を作っておく。
1. 認証用トークンを取得する。
1. ワークアイテム、終了日時、所要時間をユーザーに入力させる。
1. Web APIにリクエストを送り工数を登録する。

以下に、各処理ごとのショートカットアプリのキャプチャを掲載します。もし詳細について質問があれば、お気軽にコメントを下さい。補足いたします。

### 登録するワークアイテムの辞書を作っておく
2220などのIDの調べ方が不明な場合は、事前準備の章をご確認ください。

![スクリーンショット 2024-12-12 23.08.29.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1553191/37b28a4d-ce98-462e-5804-ca240fcf96b1.png)

### 認証用トークンを取得する
公式リファレンスそのままですね。Content-Typeをapplication/jsonに明示しないといけないところだけがやや落とし穴でした。

![スクリーンショット 2024-12-12 23.08.19.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1553191/72d16199-b269-491f-ce95-f60925a5c920.png)

参考：
https://docs.timetracker.jp/webapi/docs/reference/auth/token/postToken

### ワークアイテム、終了日時、所要時間をユーザーに入力させる
ここが正直一番複雑ですね…！
![スクリーンショット 2024-12-12 23.08.50.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1553191/f6ab7ec5-d33b-17e4-9b4f-535847a727c9.png)

:::note warn
ワークアイテムの終了日時と経過時間から、開始日時を算出するようにアクションを組んであります。終了日時と開始日時は、TimeTracker NXのプロジェクトで設定した時間刻み(例：15分)になっていないとエラーになってしまうのですが、今回作成したショートカットではそこまでケアできていません。
:::

### Web APIにリクエストを送り工数を登録する
ここまでに準備した情報を使ってリクエストを投げるだけです！

![スクリーンショット 2024-12-12 23.09.13.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1553191/cc1993e5-9376-b83f-3e91-ceff59808139.png)

参考：
https://docs.timetracker.jp/webapi/docs/reference/system/users/timeEntries/postTimeEntry

以上で、冒頭に示したようにサクサクっと工数登録ができるようになります！ :rocket: 

## おわりに
本記事ではTimeTracker NXのWeb APIとiPhoneのショートカットアプリを組み合わせて爆速で工数を記録する方法を紹介しました。ショートカットは一度作ってしまえば配布することができるので、iPhoneユーザー向けに開発元から配布頂いたらヒットするのでは？？とも思いました :smile: 。

ショートカットをコネコネするのが楽しかったです！それでは皆様良い年末を〜。