文档WorkfrontWorkfront 指南

自定义表单中的外部查找字段示例

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

创建对象：

  • 管理员

自定义表单中的外部查找字段调用外部API，并在下拉字段中作为选项返回值。 使用自定义表单附加到的对象的用户可以从下拉菜单中选择一个或多个选项。

本文提供了使用外部查找字段调用Workfront或公共API的相同实例的示例。 您还可以使用外部查找与外部系统（如Jira、Salesforce或ServiceNow）通信。

有关将外部查找字段添加到自定义表单以及外部查找组件的其他定义的详细信息，请参阅创建自定义表单。

为同一Workfront实例设置外部查找字段

您可以使用外部查找将Workfront实例中的数据纳入自定义表单。

在外部查找中使用本机Workfront字段值

此示例说明如何调用Workfront API，并将现有“状态查询”字段中的数据引入外部查找字段。

  1. 打开自定义表单。

  2. 在屏幕左侧，找到​ 外部查找 ​并将其拖动到画布上的某个部分。

  3. 输入字段的​ 标签 ​和​ 名称。

  4. 为字段选择​ 格式。

  5. 在​ 基本API URL ​字段中输入API调用。

    • 要引用自定义表单所在的相同Workfront实例，请将$$HOST用于URL。
    • 要根据查询其他字段来筛选结果，请添加$$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，并将自定义字段中的数据引入外部查找字段。 该示例自定义字段称为“自定义颜色”。

  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：组合颜色”是包含要检索的值的特定自定义字段。
    note note
    NOTE
    调用同一Workfront实例不需要​ 标头 ​信息。

  9. 单击​ 应用。

    将自定义表单添加到Workfront对象后，“组合颜色”字段中的所有值都会显示在外部查找字段下拉列表中。

为Workfront计划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计划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对象（在本例中是项目）时，它类似于此。

    具有外部查找字段的自定义表单

    根据地区 国家/地区的外部查找选项

外部查找字段的其他用例

创建外部查找还有许多其他用例。

用例： ​替换预输入字段，因为它们可能导致报告问题。
解决方案： ​使用对系统中现有对象的API调用。

模板的基本API URL示例，用于替换预输入字段：
$$HOST/attask/api/v17.0/tmpl/search?isActive=true&name_Sort=asc

用例： ​创建包含更多功能的下拉字段（例如，外部eokup字段中有换行符）。
解决方案： ​使用对系统中现有对象的API调用，或者创建新对象并使用对此对象的API调用。

用例： ​为用户定义在自定义表单区域外维护他们自己的字段的方法。 设置“外部查找”字段，您可以将用户提供给组成该字段的对象。 此选项适合高维护性字段和团队。
解决方案： ​创建新对象并使用对此对象的API调用。

用例： ​与Workfront之外的对象集成。 例如，访问另一个系统以获取每个用户的名称，而不是被限制在预输入字段中。
解决方案： Webhook/Fusion自动化以连接到其他系统。

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