はじめに
TimeTracker NX Web APIの実際の利用場面をイメージできるように、運用シナリオを想定したスクリプトを紹介します。
サンプルスクリプト一覧
ここでは、以下の活用場面で使用できるサンプルスクリプトを紹介します。
| No. | 活用場面 |
|---|---|
| 1 | ユーザー情報を一括で更新する |
| 2 | プロジェクトを立ち上げ、WBSを作成する |
| 3 | 実績工数を他システムから定期的に反映する |
| 4 | 実績工数を定期的に削除する |
| 5 | 実績工数データを他の管理システムに反映する |
| 6 | 定期的にプロジェクト一覧の情報を出力する |
| 7 | プロジェクト単位で当該期間の工数を出力する |
前提条件
上記のサンプルスクリプトはJavaScriptで作成しており、実行環境として「node.js」を採用しています。
サンプルスクリプトを利用するためには、「node.js」と共に以下のライブラリをインストールしておく必要があります。
- axios
- https
- iconv-lite
サンプルスクリプトをコピーしたJavaScriptファイルを、コマンドプロンプトから以下のコマンドにより実行することができます。
例： node sampleScript.js <TimeTracker NXのログイン名> <パスワード>
Note
node.jsを用いた環境構築の詳細は「サンプルスクリプトの実行環境を構築する」をご参照ください。
簡単なお試しツール
前提条件の環境をご用意できないお客様のために、ブラウザ上でWeb APIを簡単に実行できるツールを以下に紹介いたします。 一度の実行につき、一つのWeb APIしか呼び出せませんが、Web APIでできることの具体的なイメージを掴むことができます。
ブラウザ上で実行するツール
以下に紹介するコードはそのままHTMLファイルとして一つのWeb APIを実行するツールになります。 利用するための手順は以下のとおりです。
利用手順
- テキストファイル(※)に「サンプルコード」で紹介するコードをコピーする。
※テキストファイルのファイル名は任意の名前で問題ありません。 -
以下のコメントに挟まれた間の変数を環境や実行するWeb APIに合わせて変更する。
ユーザー設定項目 ここから ・ ・ ・ ユーザー設定項目 ここまでNote
追加や更新、削除を行う場合は、以下としてください。
- MethodTypeをPOST、PUT、DELETEに変更してください。
- 指定する値が分からない場合は、Web APIヘルプのリファレンスをご覧ください。Note
追加や更新のAPIを実行する際にサーバーに渡す情報は、RequestBody(※)に情報を設定してください。
※サンプルコードの「// この間にJSON形式でリクエストを記入する」のコメントの間に入力してください。
設定する内容が分からない場合は、Web APIヘルプのリファレンスをご覧ください。 -
手順1のテキストファイルの拡張子を「.htm」か「.html」に変更する。
- 手順3で拡張子を変更したファイルをTimeTracker NXのWebサーバーに接続可能なPC（サーバー自身も可）に配置する。
- 配置したファイルをダブルクリックし、ブラウザで開く。
- ブラウザで［Web APIを実行する］ボタンをクリックする。
- 正常終了のダイアログが表示されたら［OK］ボタンをクリックする。
-
ブラウザの下半分にWeb APIの実行結果が表示される。
Note
表示される実行結果はサーバーからの戻り値です。
サンプルコード
<html>
<head>
<meta http-equiv="content-type" charset="utf-8">
<title>Web API実行ツール</title>
</head>
<body>
<script>
// JavaScript実装部 Webページのボタンクリック時の挙動を設定
function WebAPI_Run() {
var request = new XMLHttpRequest();
// サーバーとの通信状態が変わるたびに実行
request.onreadystatechange = function () {
const READYSTATE_COMPLETED = 4;
const HTTP_STATUS_OK = 200;
// サーバーとの通信が完了したかチェック
if (request.readyState == READYSTATE_COMPLETED){
// サーバーとの通信が完了し、通信ステータスが正常終了以外の場合
if(request.status != HTTP_STATUS_OK) {
// 異常終了の表示
alert("【Status: " + request.status + "】\n\n" + request.responseText);
}
// サーバーとの通信が完了し、通信ステータスが正常終了の場合
else {
// 正常終了(実行完了のダイアログとともに結果をWebページに出力)
alert("Web APIの実行が完了しました");
document.getElementById("result").innerHTML = request.responseText;
}
}
}
////////////////////////////////////////////////////////////////////////////////
// ユーザー設定項目 ここから //
////////////////////////////////////////////////////////////////////////////////
// ServerNameとSiteNameを環境に合わせて変更する
// 以下の初期設定はURLが"http://localhost/TimeTrackerNX/#timesheet/・・・"ような場合の例
var ServerName = 'localhost';
var SiteName = 'TimeTrackerNX';
// Web APIを実行するユーザーの認証情報を設定する
// Web APIはここで指定するユーザーの権限に従って実行される
// 以下の初期設定はサンプルデータの岡本さんの例
var UserName = 'okamoto';
var Password = '';
// 実行するメソッドを設定する
// 以下の初期設定はユーザー情報の一覧を取得する例
var MethodType = 'GET' // 実行する処理により変更する(追加:POST,更新:PUT,削除：DELETE)
var APIString = '/system/users' // 呼び出すAPIに変更する。
// こちらの変数は「MethodType」に"PUT"、"POST"を指定した時に使用してください。
var RequestBody =
// ↓この間にJSON形式でリクエストを記入する(Web APIヘルプにあるリファレンスのサンプルを参照)
{
fields: {
"ActualProgress": 80,
"PlannedTime": 3000
}
}
// ↑この間にJSON形式でリクエストを記入する
; //この「;」は消さない。
////////////////////////////////////////////////////////////////////////////////
// ユーザー設定項目 ここまで //
////////////////////////////////////////////////////////////////////////////////
// Basic認証の情報を作成する
var AuthorizeString = 'Basic ' + window.btoa(UserName + ':' + Password);
// 実行するWeb APIのURL設定
var URL = 'http://' + ServerName + '/' + SiteName + '/api' + APIString;
// Web APIの実行
request.open(MethodType, URL);
request.setRequestHeader("Authorization",AuthorizeString); // 基本認証の設定
if(MethodType == 'GET'){
request.send();
} else {
request.setRequestHeader("Content-Type","application/json"); // 送信する情報のフォーマットを指定
request.send(JSON.stringify(RequestBody));// サーバーに情報を送信する場合(PUTやPOST)、JSON形式のデータを送信する
}
}
</script>
<h2>Web API実行ツール</h2>
<p>下記ボタンをクリックするとWeb APIを実行します。</p>
<!-- ブラウザ上のボタンクリックで上記のWeb API処理を実行する -->
<input type="button" value="Web APIを実行" onclick="WebAPI_Run();" />
<hr />
<!-- 実行したAPIの返信内容をこの箇所に出力する -->
<div id="result"></div>
</body>
</html>
出力結果の整形
出力結果はJSON形式で出力されます。
Webサイト上に、無償でデータを整形するサイトがございますので、必要に応じてご活用ください。
注意事項
-
利用するブラウザや導入されているセキュリティソフトによっては、JavaScriptの実行が制限されている場合があります。
この場合はシステム管理者に相談して、JavaScriptが実行できるようにこれらのソフトの設定を変更してください。 -
ブラウザに表示される出力結果はサーバーからの戻り値になるので、アイテムの追加や削除などはTimeTracker NXの画面で確認する必要があります。