Beispiele für das externe Suchfeld in einem benutzerdefinierten Formular

Letzte Aktualisierung: 31. Dezember 2024

Erstellt für:

  • Admin

Ein externes Suchfeld in einem benutzerdefinierten Formular ruft eine externe API auf und gibt Werte als Optionen in einem Dropdown-Feld zurück. Benutzer, die mit dem Objekt arbeiten, an das das benutzerdefinierte Formular angehängt ist, können eine oder mehrere dieser Optionen aus der Dropdown-Liste auswählen.

Dieser Artikel enthält Beispiele für die Verwendung des externen Suchfelds, um dieselbe Instanz von Workfront oder eine öffentliche API aufzurufen. Sie können die externe Suche auch verwenden, um mit einem externen System wie Jira, Salesforce oder ServiceNow zu kommunizieren.

Weitere Informationen zum Hinzufügen eines externen Suchfelds zu einem benutzerdefinierten Formular und zusätzliche Definitionen der externen Suchkomponenten finden Sie unter Erstellen eines benutzerdefinierten Formulars.

Einrichten eines externen Suchfelds für dieselbe Instanz von Workfront

Sie können die externe Suche verwenden, um Daten aus Ihrer Workfront-Instanz in das benutzerdefinierte Formular zu übertragen.

Verwenden von nativen Workfront-Feldwerten in der externen Suche

Dieses Beispiel zeigt, wie Sie die Workfront-API aufrufen und Daten aus dem bestehenden Feld „Statusabfrage“ in Ihr externes Suchfeld importieren.

  1. Öffnen Sie das benutzerdefinierte Formular.

  2. Suchen Sie auf der linken Seite des Bildschirms nach Externe Suche und ziehen Sie sie in einen Abschnitt auf der Arbeitsfläche.

  3. Geben Sie die Bezeichnung und Name für das Feld ein.

  4. Wählen Sie das Format für das Feld aus.

  5. Geben Sie den API-Aufruf in das Feld Basis-API URL ein.

    • Um auf dieselbe Instanz von Workfront zu verweisen, in der sich das benutzerdefinierte Formular befindet, verwenden Sie $$HOST für die URL.
    • Um die Ergebnisse basierend auf der Abfrage eines anderen Felds zu filtern, fügen Sie $$QUERY hinzu.

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

  6. Überprüfen Sie Abhängigkeiten für die Felder, auf die dieses Suchfeld in der API verweist.

    Ein Abhängigkeitsfeld kann jedes benutzerdefinierte oder native Feld sein, das auf der Detailseite des -Objekts vorhanden ist.

    In diesem Beispiel wird der {DE:StatusQuery} durch den Wert des benutzerdefinierten StatusQuery-Felds ersetzt.

  7. Wählen Sie die HTTP-Methode.

    Dies wird höchstwahrscheinlich "".

  8. Geben Sie den JSON-Pfad ein, um die Ergebnisse aus Ihrem API-Aufruf abzurufen.

    Beispiel
    $.data[*].name

    NOTE
    Header-Informationen sind für einen Aufruf derselben Workfront-Instanz nicht erforderlich.

  9. Klicken Sie Apply.

    Einrichtung eines API-Aufrufs an Workfront in benutzerdefinierter Form

    Wenn das benutzerdefinierte Formular einem Workfront-Objekt (in diesem Beispiel einem Projekt) hinzugefügt wird, sieht es in etwa wie folgt aus.

    Benutzerdefiniertes Formular mit externem Suchfeld

    Externe Suchoptionen basierend auf dem Status

Verwenden benutzerdefinierter Feldwerte in der externen Suche

Dieses Beispiel zeigt, wie Sie die Workfront-API aufrufen und Daten aus einem benutzerdefinierten Feld in Ihr externes Suchfeld einfügen. Das benutzerdefinierte Beispielfeld heißt „Benutzerdefinierte Farben“.

  1. Öffnen Sie das benutzerdefinierte Formular.

  2. Suchen Sie auf der linken Seite des Bildschirms nach Externe Suche und ziehen Sie sie in einen Abschnitt auf der Arbeitsfläche.

  3. Geben Sie die Bezeichnung und Name für das Feld ein.

  4. Wählen Sie das Format für das Feld aus.

  5. Geben Sie den API-URL-Aufruf in das Feld Basis-API URL ein.

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

  6. Überprüfen Sie Abhängigkeiten für die Felder, auf die dieses Suchfeld in der API verweist.

    Ein Abhängigkeitsfeld kann jedes benutzerdefinierte oder native Feld sein, das auf der Detailseite des -Objekts vorhanden ist.

  7. Wählen Sie die HTTP-Methode.

    Dies wird höchstwahrscheinlich "".

  8. Geben Sie den JSON-Pfad ein, um die Ergebnisse aus Ihrem API-Aufruf abzurufen.

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

    • „parameterValues“ bezieht sich auf jedes benutzerdefinierte Feld in Workfront für das Objekt, an dem Sie sich befinden.
    • In diesem Beispiel ist „DE:Combo Colors“ das spezifische benutzerdefinierte Feld, das die abzurufenden Werte enthält.
    NOTE
    Header-Informationen sind für einen Aufruf derselben Workfront-Instanz nicht erforderlich.

  9. Klicken Sie Apply.

    Wenn das benutzerdefinierte Formular zu einem Workfront-Objekt hinzugefügt wird, werden alle Werte im Feld „Kombinationsfarben“ in der Dropdown-Liste Externes Suchfeld angezeigt.

Einrichten eines externen Suchfelds für die Workfront Planning-API

In der Workfront Planning-API ist ein Endpunkt verfügbar, mit dem Datensätze nach Datensatztyp-ID über die Get-Methode gesucht werden können. Sie können diesen Endpunkt verwenden, um Planungsdatensätze in externen Suchfeldern zu referenzieren.

  • Basis-API-URL: $$HOST/maestro/api/v1/records/search?recordTypeId={recordTypeID}

  • HTTP-Methode: GET

  • JSON-Pfad: $.records[*].data.{fieldID}

    {fieldID} ist das Feld, das im benutzerdefinierten Formular für Endbenutzer in den externen Suchergebnissen angezeigt werden soll.

Weitere Informationen finden Sie unter Workfront Planning API.

Einrichten eines externen Suchfelds für eine öffentliche API

Mit der externen Suche können Sie eine externe, öffentliche API aufrufen und Daten abrufen.

Dieses Beispiel zeigt, wie Sie eine API von Ländern aufrufen (z. B. https://api.first.org/data/v1/countries), damit Sie nicht alle Ländernamen in den Dropdown-Optionen hart codieren müssen.

  1. Öffnen Sie das benutzerdefinierte Formular.

  2. Suchen Sie auf der linken Seite des Bildschirms nach Externe Suche und ziehen Sie sie in einen Abschnitt auf der Arbeitsfläche.

  3. Geben Sie die Bezeichnung und Name für das Feld ein.

  4. Wählen Sie das Format für das Feld aus.

  5. Geben Sie den API-URL-Aufruf in das Feld Basis-API URL ein.

    • Sie können $$QUERY hinzufügen, um die Abfragefilterung für Ihre Endbenutzer zu implementieren.

    Beispiele
    Listet alle Länder auf: https://api.first.org/data/v1/countries

    Ermöglicht dem Benutzer, im Dropdown-Feld nach einem beliebigen Land zu suchen: https://api.first.org/data/v1/countries?q=$$QUERY

    Ermöglicht die Suche nach einem Land in einer Region: https://api.first.org/data/v1/countries?region={DE:Region}&q=$$QUERY

    • Die verfügbaren Regionen werden in Workfront in einem separaten benutzerdefinierten Feld definiert.
    • Wenn Benutzende im Formular eine Region auswählen, zeigt das Feld Externe Suche nur die Länder in dieser Region an (welches Land sich in welcher Region befindet, wird in der API definiert). Der Benutzer kann auch in der ausgewählten Region nach einem Land suchen.

  6. Überprüfen Sie Abhängigkeiten für die Felder, auf die dieses Suchfeld in der API verweist.

    Ein Abhängigkeitsfeld kann jedes benutzerdefinierte oder native Feld sein, das auf der Detailseite des -Objekts vorhanden ist.

    In diesem Beispiel wird der {DE:Region} durch den Wert des benutzerdefinierten Felds Region ersetzt.

  7. Wählen Sie die HTTP-Methode.

    Dies wird höchstwahrscheinlich "".

  8. Geben Sie den JSON-Pfad ein, um die Ergebnisse aus Ihrem API-Aufruf abzurufen.

    Diese Option ermöglicht das Extrahieren von Daten aus der von der API-URL zurückgegebenen JSON. Sie dient als Möglichkeit, festzulegen, welche Werte aus dem JSON-Code in den Dropdown-Optionen angezeigt werden.

    Beispiel
    $.data[*].country

  9. (Optional) Klicken Sie auf Kopfzeile hinzufügen und geben Sie das Schlüssel-Wert-Paar ein, das für die Authentifizierung mit der API erforderlich ist, oder fügen Sie es ein.

    NOTE
    Die Header-Felder sind kein sicherer Ort zum Speichern von Anmeldeinformationen, und Sie sollten darauf achten, was Sie eingeben und speichern.

  10. (Optional) Wählen Sie Mehrfachauswahl-Dropdown aus, damit Benutzende mehr als einen Wert im Dropdown-Menü auswählen können.

  11. Klicken Sie Apply.

    Einrichtung eines API-Aufrufs an eine öffentliche API in benutzerdefinierter Form

    Wenn das benutzerdefinierte Formular einem Workfront-Objekt (in diesem Beispiel einem Projekt) hinzugefügt wird, sieht es in etwa wie folgt aus.

    Benutzerdefiniertes Formular mit externem Suchfeld

    Externe Suchoptionen für ein Land basierend auf einer Region