Nozioni di base sulle API di pianificazione di Adobe Workfront

L’obiettivo dell’API di pianificazione di Adobe Workfront è semplificare la creazione di integrazioni con Planning introducendo un’architettura RESTful che funziona tramite HTTP. In questo documento si presuppone che tu abbia familiarità con le risposte REST e JSON.

Per informazioni complete sul riferimento all’endpoint, sugli schemi di richiesta/risposta e sui dettagli specifici della versione, vedere la documentazione per gli sviluppatori API di Workfront Planning.

Autenticazione

L’API di pianificazione di Workfront utilizza OAuth 2.0 per l’autenticazione. Le credenziali vengono impostate tramite Adobe Developer Console.

A seconda del tipo di integrazione, sono supportati i due flussi seguenti:

Per iniziare, crea un progetto in Adobe Developer Console e aggiungi Workfront Planning API per ottenere le credenziali.

Per impostare le credenziali, crea un’applicazione OAuth2 in Workfront.

Per informazioni, consulta Creare applicazioni OAuth2 per le integrazioni Workfront.

Controllo delle versioni API

Il controllo delle versioni dell’API di Planning viene eseguito tramite il percorso URL.

Di seguito sono elencate le versioni supportate correnti:

Per ulteriori informazioni sulle versioni supportate correnti, vedere l’articolo Documentazione per gli sviluppatori API di Workfront Planning.

È consigliabile eseguire esplicitamente il targeting di una versione in tutte le integrazioni:

https://{customer-domain}/maestro/api/v2/...

Quando viene rilasciata una nuova versione principale, la versione precedente continuerà a essere disponibile fino a quando non viene comunicata una data di rimozione.

Segui le note sulla versione di Workfront per essere sempre informato sulle modifiche API.

Struttura degli URL e operazioni

Gli oggetti vengono manipolati inviando una richiesta HTTP al relativo URI univoco. Operazione specificata dal metodo HTTP.

Per i percorsi di endpoint completi e gli esempi di richieste/risposte, consulta il riferimento API in developer.adobe.com/wf-planning.

Codici di stato HTTP

L’API Planning restituisce i codici di stato HTTP standard:

Gestione degli errori

L’API di Planning restituisce gli errori in un formato coerente. Ogni risposta di errore include un messaggio leggibile dall’utente, un codice di errore leggibile dal computer e un ID richiesta per l’escalation del supporto.

Esempio di risposta di errore:

json
{
  "title": "Validation failed",
  "status": 400,
  "detail": "Request validation failed. See 'errors' for details.",
  "errorCode": "VALIDATION_FAILED",
  "requestId": "req-123",
  "errors": [
    { "field": "name", "message": "must not be blank" }
  ]
}

Utilizzare errorCode (non status) per gestire gli errori a livello di programmazione. Fornisce la classificazione più specifica dell’errore.

Filtraggio dei record

Utilizzare il parametro filter nelle richieste di ricerca dei record per restituire solo i record che corrispondono a criteri specifici. Per le richieste POST, filter è una proprietà JSON nel corpo della richiesta. Per le richieste GET, filter è un parametro di query contenente un gruppo di filtri con codifica JSON. I filtri utilizzano una struttura composita tipizzata con operatori logici espliciti.

json
{
  "filter": {
    "operator": "AND",
    "conditions": [
      { "fieldId": "<fieldId>", "condition": "IS", "value": "Active" },
      { "fieldId": "<fieldId>", "condition": "CONTAINS", "value": "marketing" }
    ]
  }
}

I filtri possono essere nidificati utilizzando gli operatori AND / OR per creare condizioni composte:

json
{
  "filter": {
    "operator": "OR",
    "conditions": [
      {
        "operator": "AND",
        "conditions": [
          { "fieldId": "<fieldId>", "condition": "BETWEEN", "value": ["2024-03-31T20:00:00.000Z", "2024-04-01T20:00:00.000Z"] },
          { "fieldId": "<fieldId>", "condition": "IS", "value": "active" }
        ]
      },
      {
        "operator": "AND",
        "conditions": [
          { "fieldId": "<fieldId>", "condition": "IS_BETWEEN", "value": ["2024-04-15T00:00:00.000Z", "2024-04-16T00:00:00.000Z"] },
          { "fieldId": "<fieldId>", "condition": "IS", "value": "planned" }
        ]
      }
    ]
  }
}

Tipi di campi e modificatori di ricerca

È possibile utilizzare modificatori e filtri con i campi per controllare quali dati verranno restituiti nei risultati.

Per esempi, vedere la documentazione per gli sviluppatori API di Workfront Planning.

Utilizzo dei modificatori di ricerca

Workfront Planning supporta i seguenti modificatori di ricerca:

Condizioni di filtro supportate per tipo di campo

Filtrare per campi Persone

I filtri dei campi delle persone (user, created-by, updated-by, approved-by) accettano sia gli ID utente Adobe IMS che gli ID utente Workfront. Un valore di stringa semplice viene interpretato come un ID utente Adobe IMS.

Per impostare il tipo di identificatore per controllare l’ID utente di Workfront, è necessario trasmettere esplicitamente i parametri id e idType. I valori supportati per idType sono “WF” per gli ID utente di Workfront e “IMS” per gli ID utente di Adobe IMS.

{
  "filter": {
   "operator": "AND",
    "conditions": [
      {
        "fieldId": "<userFieldId>",
        "condition": "HAS_ANY_OF",
        "value": [
          { "id": "63e3b13000078c1795146248182d15dc", "idType": "WF" }
        ]
      }
    ]
  }
}

Filtraggio dei campi di riferimento esterni per ID esterno

I campi di riferimento esterni collegano i record a oggetti in altri sistemi Adobe (come progetti Workfront o AEM Assets). Internamente, Planning assegna gli ID record di Planning a questi oggetti. Per filtrare questi campi direttamente in base al loro ID oggetto originale, aggiungi "matchExternalId": true a una condizione di filtro.

Questo flag è valido solo per i campi di riferimento in cui referenceOptions.isExternal è true; viene ignorato per i campi di riferimento non esterni. Se non è possibile risolvere un singolo valore stringa, la richiesta non riesce con 400 Bad Request. Se viene fornito un valore di elenco, le voci non risolte passano attraverso invariate e semplicemente non corrispondono.

{
  "filter": {
    "operator": "AND",
    "conditions": [
      {
        "fieldId": "<externalReferenceFieldId>",
        "condition": "IS_ANY_OF",
        "value": [
          "5f6a4f6e00000123456789abcdef0123",
          "/content/dam/wknd/en/adventures/bali-surf-camp"
        ],
        "matchExternalId": true
      }
    ]
  }
}

Campi di connessione esterna

I tipi di record di Planning possono ospitare campi di riferimento esterni che collegano i record a oggetti in altri sistemi Adobe anziché ad altri tipi di record di Planning.

Per creare un campo di riferimento esterno tramite API, impostare referenceOptions.recordTypeId su un nuovo campo REFERENCE sull’ID del tipo di record esterno desiderato. Il server deriva automaticamente referenceOptions.isExternal=true e i metadati di connessione (connectionName, objectName) dal tipo di record di destinazione.

I tipi di oggetti esterni supportati includono oggetti Workfront (progetti, attività, programmi, portfolio, aziende, gruppi, team, utenti) e AEM Assets (risorse, frammenti di contenuto).

Ordinamento

Ordinare i risultati in base a qualsiasi campo includendo un array sort nella richiesta:

json
{
  "sort": [
    { "fieldId": "F6527ecb25df57c441d92b9fc", "direction": "asc" },
    { "fieldId": "F658afcbd4a0273c67c346fd5", "direction": "desc" }
  ]
}

Più campi di ordinamento vengono valutati in ordine. Applica sempre un ordinamento durante la paginazione per garantire un ordinamento coerente tra le pagine.

Per raggruppare i risultati, includere una matrice di gruppi insieme all’ordinamento:

{
  "sort": [{ "fieldId": "F001", "direction": "asc" }],
  "group": [{ "fieldId": "F002", "direction": "asc" }]
}

Proiezione sul campo

Per limitare i campi restituiti in una risposta, utilizzare i parametri di query fieldIds o fieldAliases con un elenco separato da virgole. Questo riduce le dimensioni del payload di risposta ed è consigliato per integrazioni con volumi elevati o sensibili alla latenza.

Paginazione

L’API di Planning supporta risposte impaginate per gestire set di dati di grandi dimensioni.

Ad esempio, utilizza la seguente richiesta per recuperare la seconda pagina di 500 record da una ricerca record:

POST /v2/record-types/{recordTypeId}/records/search?page=1&size=500
{
  "sort": [{ "fieldId": "F6527ecb25df57c441d92b9fc", "direction": "asc" }],
  "filter": { "operator": "AND", "conditions": [
    { "fieldId": "<fieldId>", "condition": "IS", "value": "active" }
  ] }
}

Tutte le risposte impaginate includono una busta strutturata che indica se sono disponibili più risultati. Applica sempre un ordinamento durante la paginazione per garantire un ordinamento coerente tra le pagine.

Operazioni in blocco

L’API Planning supporta la creazione, l’aggiornamento, la correzione e l’eliminazione in blocco di record in una singola richiesta. Per i percorsi degli endpoint, i formati di richiesta e i limiti di record per operazione, fare riferimento al riferimento API in developer.adobe.com/wf-planning.

Autorizzazioni

Le autorizzazioni per le entità vengono gestite tramite un’API di autorizzazioni dedicata, separata dagli endpoint di risorsa stessi. Questo consente di leggere le autorizzazioni correnti, gestire l’elenco di condivisione e gestire le richieste di accesso indipendentemente dalle operazioni sui dati. Per ulteriori informazioni, vedere la sezione “Riferimenti API” nell’articolo Workfront Planning API.

Utilizzo dell’API di Planning con i moduli personalizzati di Workfront

È possibile chiamare l’API Planning da un campo di ricerca Esterna in un modulo personalizzato Workfront per rendere visibili i dati di Planning direttamente all’interno di oggetti Workfront. Per ulteriori informazioni, vedere Esempi del campo di ricerca esterna in un modulo personalizzato.

Risorse correlate

Per ulteriore documentazione relativa all’API, consulta anche i seguenti articoli: