ドキュメントWorkfrontWorkfront ガイド

カスタムフォームの外部検索フィールドの例

Last update: Wed Oct 23 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

作成対象：

  • 管理者

カスタムフォームの外部参照フィールドが外部 API を呼び出し、ドロップダウンフィールドのオプションとして値を返します。 カスタムフォームが添付されているオブジェクトを使用するユーザーは、ドロップダウンからこれらのオプションを 1 つ以上選択できます。

この記事では、外部検索フィールドを使用して、同じWorkfront インスタンスまたはパブリック API を呼び出す例を示します。 また、外部参照を使用して、Jira、Salesforce、ServiceNow などの外部システムと通信することもできます。

外部検索フィールドをカスタムフォームに追加する方法と、外部検索コンポーネントのその他の定義について詳しくは、 カスタムフォームの作成を参照してください。

Workfrontの同じインスタンスに対して外部検索フィールドを設定する

外部検索を使用して、Workfront インスタンスからカスタムフォームにデータを取り込むことができます。

外部検索でのネイティブのWorkfront フィールド値の使用

この例は、Workfront API を呼び出し、既存の「ステータスクエリ」フィールドから外部ルックアップフィールドにデータを取り込む方法を示しています。

  1. カスタムフォームを開きます。

  2. 画面の左側で、「外部ルックアップ」を見つけて、キャンバス上のセクションにドラッグします。

  3. フィールドの​ ラベル ​と​ 名前 ​を入力します。

  4. フィールドの​ 形式 ​を選択します。

  5. API 呼び出しを「ベース API URL」フィールドに入力します。

    • カスタムフォームと同じWorkfrontのインスタンスを参照するには、URL に$$HOST を使用します。
    • 別のフィールドに対するクエリに基づいて結果をフィルタリングするには、$$QUERY を追加します。

    例
    $$HOST/attask/api/v15.0/project/search?status={DE:StatusQuery}&$$QUERY

  6. このルックアップフィールドが API で参照しているフィールドの​ 依存関係 ​を確認します。

    「依存関係」フィールドには、オブジェクトの詳細ページに存在する任意のカスタムフィールドまたはネイティブフィールドを使用できます。

    この例では、{DE:StatusQuery} が StatusQuery カスタムフィールドの値に置き換えられます。

  7. 「HTTP メソッド」を選択します。

    これは、ほとんどの場合、Get になります。

  8. JSON パス ​を入力して、API 呼び出しの結果を取得します。

    例
    $.data[*].name

    note note
    NOTE
    同じ Workfront インスタンスに対して呼び出しを行う場合は、ヘッダー ​の情報は必要ありません。

  9. 「適用」をクリックします。

    カスタムフォームでの Workfront に対する API 呼び出しの設定

    カスタムフォームが Workfront オブジェクト（この例ではプロジェクト）に追加されると、次のようになります。

    「外部ルックアップ」フィールドを含むカスタムフォーム

    ステータスに基づく「外部ルックアップ」オプション

外部参照でのカスタムフィールド値の使用

この例では、Workfront API を呼び出し、カスタムフィールドから外部検索フィールドにデータを取り込む方法を示しています。 例えば、カスタムフィールドは「Custom Colors」と呼ばれます。

  1. カスタムフォームを開きます。

  2. 画面の左側で、「外部ルックアップ」を見つけて、キャンバス上のセクションにドラッグします。

  3. フィールドの​ ラベル ​と​ 名前 ​を入力します。

  4. フィールドの​ 形式 ​を選択します。

  5. API の URL 呼び出しを「ベース API の URL」フィールドに入力します。

    例
    $$HOST/attask/api/v18.0/PORT/search?ID={portfolioID}&fields=parameterValues

  6. このルックアップフィールドが API で参照しているフィールドの​ 依存関係 ​を確認します。

    「依存関係」フィールドには、オブジェクトの詳細ページに存在する任意のカスタムフィールドまたはネイティブフィールドを使用できます。

  7. 「HTTP メソッド」を選択します。

    これは、ほとんどの場合、Get になります。

  8. JSON パス ​を入力して、API 呼び出しの結果を取得します。

    例
    $.data[*].parameterValues.["DE:Combo Colors"]

    • 「parameterValues」は、操作しているオブジェクトのWorkfront内のカスタムフィールドを指します。
    • 例えば、「DE:Combo Colors」は、取得する値を含む特定のカスタムフィールドです。
    note note
    NOTE
    同じ Workfront インスタンスに対して呼び出しを行う場合は、ヘッダー ​の情報は必要ありません。

  9. 「適用」をクリックします。

    カスタムフォームがWorkfront オブジェクトに追加されると、「コンボカラー」フィールドのすべての値が外部検索フィールドドロップダウンに表示されます。

Workfront Planning API 用の外部参照フィールドの設定

Workfront Planning API では、Get メソッドを使用してレコードタイプ ID でレコードを検索するためのエンドポイントを使用できます。 このエンドポイントを使用して、外部参照フィールドで Planning レコードを参照できます。

  • ベース API の URL: $$HOST/maestro/api/v1/records/search?recordTypeId={recordTypeID}

  • HTTP メソッド： Get

  • JSON パス： $.records[*].data.{fieldID}

    {fieldID} は、エンドユーザーのカスタムフォーム上で外部検索の検索結果に表示するフィールドです。

詳しくは、Workfront Planning API を参照してください。

パブリック API 用の外部参照フィールドの設定

外部検索を使用して、外部のパブリック API を呼び出し、データを取得できます。

この例では、ドロップダウンオプションにすべての国名をハードコーディングする必要がないように、国の API（https://api.first.org/data/v1/countries など）を呼び出す方法を示します。

  1. カスタムフォームを開きます。

  2. 画面の左側で、「外部ルックアップ」を見つけて、キャンバス上のセクションにドラッグします。

  3. フィールドの​ ラベル ​と​ 名前 ​を入力します。

  4. フィールドの​ 形式 ​を選択します。

  5. API の URL 呼び出しを「ベース API の URL」フィールドに入力します。

    • $$QUERY を追加すると、エンドユーザーに対するクエリフィルタリングを実装できます。

    例
    すべての国を一覧表示します。https://api.first.org/data/v1/countries

    ユーザーがドロップダウンフィールド内の任意の国を検索できるようにします。https://api.first.org/data/v1/countries?q=$$QUERY

    ユーザーが地域内の国を検索できるようにします。https://api.first.org/data/v1/countries?region={DE:Region}&q=$$QUERY

    • 使用可能なは、Workfront の別のカスタムフィールドで定義されます。
    • ユーザーがフォーム上で地域を選択すると、外部検索フィールドには、その地域の国（API で地域が定義されている国）のみが表示されます。 また、ユーザーは、選択した地域の国を検索することもできます。

  6. このルックアップフィールドが API で参照しているフィールドの​ 依存関係 ​を確認します。

    「依存関係」フィールドには、オブジェクトの詳細ページに存在する任意のカスタムフィールドまたはネイティブフィールドを使用できます。

    この例では、{DE:Region} は、地域カスタムフィールドの値に置き換えられます。

  7. 「HTTP メソッド」を選択します。

    これは、ほとんどの場合、Get になります。

  8. JSON パス ​を入力して、API 呼び出しから結果を取得します。

    このオプションを使用すると、API URL から返された JSON からデータを抽出できます。これは、JSON 内のどの値がドロップダウンオプションに表示されるかを選択する手段の役割を果たします。

    例
    $.data[*].country

  9. （オプション）「ヘッダーを追加」をクリックし、API での認証に必要なキーと値のペアを入力するか貼り付けます。

    note note
    NOTE
    「ヘッダー」フィールドは、資格情報を保存する安全な場所ではないので、入力して保存する内容には注意する必要があります。

  10. （オプション）ユーザーがドロップダウンで複数の値を選択できるようにするには、「複数選択ドロップダウン」を選択します。

  11. 「適用」をクリックします。

    カスタムフォームでのパブリック API への API 呼び出しの設定

    カスタムフォームが Workfront オブジェクト（この例ではプロジェクト）に追加されると、次のようになります。

    「外部ルックアップ」フィールドを含むカスタムフォーム

    地域に基づく国の「外部ルックアップ」オプション

外部検索フィールドのその他のユースケース

外部参照を作成するユースケースは他にも多数あります。

ユースケース： typeahead フィールドは、レポートで問題を引き起こす可能性があるので、置き換えます。
解決策： システム内の既存のオブジェクトへの API 呼び出しを使用します。

typeahead フィールドを置き換えるためのテンプレートのベース API URL の例：
$$HOST/attask/api/v17.0/tmpl/search?isActive=true&name_Sort=asc

ユースケース： より多くの機能を含むドロップダウンフィールドを作成する（例えば、外部 eookup フィールドに折り返し線がある）。
解決策： システム内の既存のオブジェクトへの API 呼び出しを使用するか、新しいオブジェクトを作成してこのオブジェクトへの API 呼び出しを使用します。

ユースケース： ユーザーがカスタムフォーム領域外で独自のフィールドを維持する方法を定義します。 外部検索フィールドを設定し、フィールドを構成するオブジェクトにユーザーを指定できます。 このオプションは、メンテナンスの多いフィールドやチームに適しています。
解決策： 新しいオブジェクトを作成し、このオブジェクトへの API 呼び出しを使用します。

ユースケース： ​Workfront外のオブジェクトとの統合。 例えば、typeahead フィールドで制限されているのではなく、別のシステムにアクセスして各ユーザーの名前を取得するような場合です。
解決策： 他のシステムに接続するための Webhook/Fusion 自動処理。

recommendation-more-help
5f00cc6b-2202-40d6-bcd0-3ee0c2316b43