Modifiche alle API nella versione di agosto 2026 di Adobe Learning Manager

API di amministrazione gruppi di utenti in Adobe Learning Manager

Questa versione aggiunge tre nuovi endpoint API pubblici con ambito di amministrazione per la gestione di gruppi di utenti personalizzati a livello di programmazione. Puoi creare, rinominare ed eliminare gruppi di utenti personalizzati senza utilizzare l’app di amministrazione, consentendo di automatizzare la gestione dei gruppi come parte dei flussi di lavoro di identità o provisioning.

Questi endpoint funzionano solo con gruppi di utenti personalizzati. I gruppi gestiti dal sistema, ad esempio il gruppo Tutti gli utenti e i gruppi di utenti generati automaticamente, hanno il valore readOnly: true nella risposta API e non possono essere modificati o eliminati tramite questi endpoint.

Per i requisiti di autenticazione API, vedere Autenticazione API Adobe Learning Manager.

Endpoint API gruppi di utenti

Tutti e tre gli endpoint richiedono un token di accesso amministratore con autorizzazioni di scrittura (ROLE_ADMIN).

Intestazioni di richiesta comuni

Tutti e tre gli endpoint richiedono le intestazioni seguenti.

Authorization: Bearer \<access-token\>
X-acap-user: \<user-id\>
X-acap-account: \<account-id\>
X-acap-caller-role: ROLE_ADMIN
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

Creare un gruppo di utenti

POST /primeapi/v2/userGroups

Crea un nuovo gruppo di utenti personalizzato con un elenco iniziale di membri. Il gruppo è immediatamente disponibile per l’uso nell’app per amministratori.

Corpo della richiesta

{
  "name": "Marketing Team",
  "description": "Custom user group for marketing onboarding",
  "data": [
    { "type": "user", "id": "11282373" },
    { "type": "user", "id": "11282374" }
  ]
}

Parametri richiesta

Nota: la matrice di dati viene utilizzata solo al momento della creazione per impostare l’elenco di membri iniziale. Per aggiungere o rimuovere membri dopo la creazione, utilizzare gli endpoint di appartenenza al gruppo di utenti esistenti.

Risposta 201 creata

{
  "links": {
    "self": "https://<host>/primeapi/v2/userGroups"
  },
  "data": {
    "id": "2769204",
    "type": "userGroup",
    "attributes": {
      "dateCreated": "2026-06-04T14:19:53.000Z",
      "description": "Custom user group for marketing onboarding",
      "name": "Marketing Team",
      "readOnly": false,
      "userCount": 2
    }
  }
}

POST delle regole di convalida

Aggiornare un gruppo di utenti

PUT /primeapi/v2/userGroups/{id}

Aggiorna il nome e/o la descrizione di un gruppo di utenti personalizzato esistente. Questo endpoint non può aggiungere o rimuovere membri del gruppo.

Entrambi i campi possono essere omessi; se si omette un campo, il suo valore corrente rimane invariato. Se si passa il valore null per la descrizione, il valore viene cancellato. Il passaggio di una stringa vuota per il nome è rifiutato.

Corpo della richiesta

{
  "name": "Updated Group Name",
  "description": "Updated description text"
}

Parametri richiesta

Risposta 200 OK

{
  "data": {
    "type": "userGroup",
    "id": "2767870",
    "attributes": {
      "name": "Updated Group Name",
      "description": "Updated description text",
      "readOnly": false,
      "state": "Active",
      "userCount": 3
    }
  }
}

PUT delle regole di convalida

Eliminare un gruppo di utenti

DELETE /primeapi/v2/userGroups/{id}

Contrassegna il gruppo di utenti personalizzato specificato come eliminato. Il record del gruppo non viene rimosso in modo permanente: il suo stato è impostato su ELIMINATO e questo lo rende invisibile nell’app per amministratori e non idoneo per l’uso in nuove configurazioni. Impossibile riutilizzare l’ID gruppo.

Esempio di richiesta

DELETE /primeapi/v2/userGroups/2767870
Authorization: Bearer <access-token>
X-acap-user: <user-id>
X-acap-account: <account-id>
X-acap-caller-role: ROLE_ADMIN

Risposta 204 senza contenuto

Il corpo della risposta è vuoto.

Nota: DELETE non è idempotente. L’invio di una seconda richiesta DELETE allo stesso ID gruppo restituisce un errore 400 con il codice DELETED_USERGROUP (non 204). Considera una risposta 400 DELETED_USERGROUP come conferma che il gruppo è già stato eliminato. L’eliminazione in blocco non è supportata. Ogni gruppo richiede una richiesta DELETE separata.

DELETE delle regole di convalida

API di apprendimento esterno in Adobe Learning Manager

Questa versione aggiunge cinque nuovi endpoint API con ambito Allievo per la funzione di apprendimento esterno. Questi endpoint consentono agli Allievi di creare, recuperare e aggiornare gli invii di apprendimento esterni a livello di programmazione, ad esempio, da un’app per dispositivi mobili, un sistema HR integrato o un portale di apprendimento personalizzato.

Il flusso di lavoro di apprendimento esterno tramite API riflette il flusso di lavoro nell’app per allievi: un Allievo invia i dettagli del corso di formazione e un documento di prova opzionale, il suo Direct Manager riceve una notifica per esaminare l’invio e, all’approvazione, il record viene visualizzato nella trascrizione dell’Allievo.

Tutti e cinque gli endpoint hanno un ambito Allievo. Un Allievo può accedere solo ai propri invii: l’API restituisce un errore se un Allievo tenta di accedere ai dati di un altro Allievo.

Per i requisiti di autenticazione API, vedere Autenticazione API Adobe Learning Manager.

Endpoint API di apprendimento esterni

Tutti gli endpoint richiedono un token di accesso Allievo (ROLE_LEARNER).

Intestazioni di richiesta comuni

Authorization: Bearer <access-token>
X-acap-user: <user-id>
X-acap-account: <account-id>
X-acap-caller-role: ROLE_LEARNER
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json (POST and PUT only)

Ciclo di vita stato invio

APPROVATI e RIFIUTATI sono stati terminali. Un inoltro rifiutato non può essere riaperto; l’Allievo deve creare un nuovo inoltro.

Recupera configurazione modulo account

GET /primeapi/v2/externalLearningSettings

Restituisce la configurazione del modulo a livello di account. Chiamare questo endpoint prima di eseguire il rendering di un modulo di invio. La risposta definisce i campi da visualizzare, i campi obbligatori, i relativi tipi di dati e tutti i campi personalizzati configurati dall’amministratore.

Verifica l’attributo abilitato di primo livello prima di procedere. Se è false, la funzione di apprendimento esterno non è attiva per questo account e gli endpoint di invio restituiranno errori.

Risposta 200 OK

{
  "data": {
    "id": "8627",
    "type": "externalLearningSettings",
    "attributes": {
      "enabled": true,
      "updatedAt": "2026-06-05T06:51:20.000Z",
      "coreFields": [
        { "id": "title", "type": "TEXT", "mandatory": true, "editable": false, "order": 0 },
        { "id": "description_notes", "type": "TEXT", "mandatory": false, "editable": true, "order": 1 },
        { "id": "date", "type": "TIMESTAMP", "mandatory": false, "editable": true, "order": 2 },
        { "id": "score", "type": "NUMBER", "mandatory": true, "editable": true, "order": 3 },
        { "id": "duration", "type": "TEXT", "mandatory": false, "editable": true, "order": 4 },
        { "id": "attachments", "type": "FILE_UPLOAD", "mandatory": true, "editable": true, "order": 5 }
      ],
      "customFields": [
        {
          "id": "960369b2-...",
          "type": "NUMBER",
          "mandatory": true,
          "order": 0,
          "label": { "en_US": "Employee Code" }
        },
        {
          "id": "3c6cc6d9-...",
          "type": "DROPDOWN",
          "mandatory": true,
          "order": 1,
          "label": { "en_US": "Department" },
          "options": [
            { "option_id": "opt_1", "label": { "en_US": "IT" } },
            { "option_id": "opt_2", "label": { "en_US": "HR" } },
            { "option_id": "opt_3", "label": { "en_US": "FIN" } }
          ]
        }
      ]
    }
  }
}

Riferimento campo core

I campi personalizzati sono definiti dall’amministratore e restituiti in customFields[]. Gli ID, i tipi, i contrassegni obbligatori, le etichette e le opzioni del menu a discesa variano a seconda della configurazione dell’account.

Elenca invii

GET /primeapi/v2/externalLearnings

Restituisce un elenco impaginato degli invii dell’Allievo autenticato, ordinati in ordine decrescente in base all’ultima modifica.

Parametri di query

Risposta 200 OK

{
  "links": {
    "next": "/primeapi/v2/externalLearnings?page[offset]=10&page[limit]=10"
  },
  "data": [
    { "id": "1001", "type": "externalLearning", "attributes": { "status": "PENDING", ... } },
    { "id": "1002", "type": "externalLearning", "attributes": { "status": "APPROVED", ... } }
  ]
}

Recuperare un inoltro

GET /primeapi/v2/externalLearnings/{id}

Restituisce il record completo di un singolo invio appartenente all’Allievo autenticato.

**Risposta 200 OK

{
  "data": {
    "id": "1001",
    "type": "externalLearning",
    "attributes": {
      "submissionUrl": "https://<cdn-url>/cert.pdf",
      "title": "Java Fundamentals Certification",
      "status": "PENDING",
      "creationSource": "LEARNER",
      "createdAt": "2026-04-14T08:30:00.000Z",
      "modifiedAt": "2026-04-16T11:45:00.000Z",
      "fields": [ "...resolved against live settings..." ]
    },
    "relationships": {
      "reviewerUser": { "data": null }
    }
  }
}

Creare un inoltro

POST /primeapi/v2/externalLearnings

Crea un nuovo invio di apprendimento esterno in stato IN SOSPESO. Tutti i campi obbligatori definiti nelle impostazioni dell’account devono essere inclusi. Dopo un POST riuscito, il manager dell’Allievo riceve una notifica nella piattaforma per esaminare l’invio.

Caricamento file

Il campo degli allegati viene gestito separatamente dagli altri campi. Non includerlo nei campi []. Invece:

​1. Ottenere un URL di caricamento S3 pre-firmato dall’endpoint di caricamento del file ALM.

​2. Carica il file in tale URL.

​3. Passa l’URL risultante come attributo submissionUrl di primo livello nella richiesta POST.

Corpo della richiesta

{
  "data": {
    "type": "externalLearning",
    "attributes": {
      "submissionUrl": "<pre-signed-upload-url>",
      "fields": [
        { "id": "title", "type": "TEXT", "value": "Java Fundamentals Certification" },
        { "id": "description_notes", "type": "TEXT", "value": "Completed via online course platform." },
        { "id": "date", "type": "TIMESTAMP", "value": { "start_date": "2026-05-01T00:00:00.000Z", "end_date": "2026-05-15T00:00:00.000Z" } },
        { "id": "score", "type": "NUMBER", "value": { "achieved_score": 88, "max_score": 100 } },
        { "id": "duration", "type": "TEXT", "value": "40 hours" },
        { "id": "960369b2-...", "type": "NUMBER", "value": "1225" },
        { "id": "3c6cc6d9-...", "type": "DROPDOWN", "value": "opt_3" }
      ]
    }
  }
}

Forme valore campo

POST delle regole di convalida

Aggiornare un inoltro

PUT /primeapi/v2/externalLearnings/{id}

Aggiorna un inoltro in SOSPESO esistente. È possibile aggiornare solo gli invii IN SOSPESO. Se si tenta di applicare il PUT a un inoltro APPROVATO o RIFIUTATO, viene restituito un errore 409.

Questo endpoint utilizza la semantica di sostituzione completa. Fornire la matrice completa dei campi [] in ogni richiesta PUT, non solo i campi che si stanno modificando. I campi omessi dalla matrice vengono cancellati.

Campi che l’Allievo può aggiornare

Corpo della richiesta

{
  "data": {
    "type": "externalLearning",
    "attributes": {
      "submissionUrl": "<cdn-url>/cert-v2.pdf",
      "fields": [
        { "id": "title", "type": "TEXT", "value": "Java Fundamentals — Updated" },
        { "id": "description_notes", "type": "TEXT", "value": "Updated notes." },
        { "id": "date", "type": "TIMESTAMP", "value": { "start_date": null, "end_date": null } },
        { "id": "score", "type": "NUMBER", "value": { "achieved_score": 92, "max_score": 100 } },
        { "id": "duration", "type": "TEXT", "value": "42 hours" },
        { "id": "960369b2-...", "type": "NUMBER", "value": "1227" },
        { "id": "3c6cc6d9-...", "type": "DROPDOWN", "value": "opt_2" }
      ]
    }
  }
}

API per ID di certificazione e ID di certificazione principale pertinenti per gli Allievi in LT

Quando una certificazione ricorrente si rinnova, Adobe Learning Manager crea una nuova versione della certificazione e vi iscrive automaticamente gli Allievi attivi. Se l’integrazione richiede direttamente i dati di certificazione anziché basarsi sull’esperienza dell’Allievo in Adobe Learning Manager, è possibile utilizzare questa API per determinare con esattezza quale versione di una certificazione ricorrente è rilevante per uno specifico Allievo in qualsiasi momento.

Scopo dell’API

Le certificazioni ricorrenti generano un nuovo ID di certificazione ogni volta che vengono rinnovate. Nell’esperienza nativa di un Allievo Adobe Learning Manager, viene visualizzata solo la versione relativa a ciascun Allievo. Le versioni precedenti venivano nascoste automaticamente quando un Allievo passava a una più recente.

Se l’integrazione recupera i dati di certificazione in modo indipendente, ad esempio per visualizzare le informazioni di certificazione su un portale esterno, è possibile che non applichi automaticamente questo filtro. Senza tale certificazione, un Allievo poteva visualizzare tutte le versioni storiche di una certificazione ricorrente, comprese quelle che non lo riguardavano più, senza alcuna indicazione su cui agire.

Questa API ha risolto tale lacuna. Dato l’ID di certificazione principale, restituisce la versione della certificazione specifica che si applica a un determinato Allievo, tenendo conto della cronologia di iscrizione e di eventuali ricorrenze.

Informazioni sulla ricorrenza della certificazione

Quando una certificazione è configurata per essere ricorrente, ogni rinnovo crea una nuova versione della certificazione con il proprio ID univoco. Tutte le versioni riconducono a un singolo ID di certificazione radice l’ID della certificazione originale al momento della creazione.

Ad esempio, una certificazione che si ripete ogni mese può produrre una sequenza di versioni nel tempo, in cui ogni nuova versione viene generata automaticamente al raggiungimento dell’intervallo di ricorrenza. Gli Allievi iscritti attivamente quando si verifica una ricorrenza vengono iscritti automaticamente alla nuova versione.

Poiché ogni versione ha un ID distinto, la versione pertinente di un Allievo dipende dalla propria tempistica di iscrizione individuale:

Determinare la versione di certificazione pertinente

Utilizza l’API della versione di certificazione per identificare la versione di una certificazione ricorrente rilevante per un Allievo specifico.

Fornire l’ID certificazione radice come input. L’API valuta la cronologia di iscrizione dell’Allievo e restituisce la versione appropriata in base alle seguenti regole:

Ciò significa che due Allievi che eseguono contemporaneamente una query sullo stesso ID di certificazione principale possono ricevere risultati diversi, a seconda della cronologia di iscrizione individuale di ciascun Allievo.

Esempio

Si consideri una certificazione che ricorre mensilmente, in cui sono state create quattro versioni nel tempo a causa di ricorrenze successive:

Ciò consente all’integrazione di indirizzare sempre un Allievo alla versione di certificazione a lui pertinente, anziché mostrare ogni versione storica o indovinare quale sia applicabile.

Riferimento API

Ottenere la certificazione applicabile per una certificazione radice

GET /primeapi/v2/learningObjects/{loId}/applicableCertification

Risolve la versione della certificazione che si applica all’Allievo corrente, dato l’ID di una certificazione radice. Per gli Allievi iscritti, restituisce la versione a cui sono attualmente iscritti. Per gli Allievi non iscritti, questa opzione restituisce la versione attiva più recente.

Nota: questa API restituisce informazioni sulla versione per un singolo Allievo alla volta. Non restituisce un elenco di tutte le versioni di una certificazione.

Parametri del percorso

Parametri di query

Esempio di richiesta

GET /primeapi/v2/learningObjects/certification%3A167658/applicableCertification?include=subLOs
Accept: application/vnd.api+json
Authorization: oauth <access-token>

curl -X GET --header 'Accept: application/vnd.api+json' \
--header 'Authorization: oauth <access-token>' \
'https://<host>/primeapi/v2/learningObjects/certification%3A167658/applicableCertification?include=subLOs'

Nota: il valore loId deve essere codificato con URL. I due punti in un ID di certificazione, ad esempio certificazione:167658, sono codificati come %3A.

Esempio di risposta 200 OK

La risposta utilizza la stessa struttura di una risposta standard all’oggetto di apprendimento e restituisce la certificazione risolta.

Importante: il campo ID nella risposta è l’ID della certificazione risolta, ovvero la versione specifica applicabile a questo Allievo. In genere sarà diverso dall’ID di certificazione principale che hai passato come loId, poiché lo scopo di questa API è quello di tradurre un ID principale nella versione corrente corretta.

{
  "data": {
    "id": "string",
    "type": "string",
    "attributes": {
      "authorNames": [
        "string"
      ],
      "bannerUrl": "string",
      "catalogs": [
        ...
      ]
    }
  }
}

Codici di risposta

Esempio di risposta di errore

{
  "meta": {
    "error": "string",
    "detail": "string"
  }
}

Nota: questa API risolve la versione per un Allievo per chiamata. Non restituisce un elenco di tutte le versioni esistenti per una certificazione radice.

Punti importanti

Nota: un equivalente con ambito amministratore di questa API non è attualmente disponibile ed è in fase di valutazione per una versione futura.

Utilizza questa API nell’integrazione

Uno use case comune è una pagina o un portale esterno in cui sono elencate le certificazioni a cui un Allievo può accedere. Invece di collegarti direttamente a uno specifico ID di certificazione, che potrebbe diventare obsoleto dopo una ricorrenza. Esegui il collegamento utilizzando l’ID di certificazione principale e risolvi la versione corretta quando l’Allievo la seleziona.

1.Memorizzare o fare riferimento alle certificazioni nell’integrazione utilizzando l’ID di certificazione radice l’ID della certificazione creato inizialmente, prima di qualsiasi ricorrenza.

​2. Quando un Allievo seleziona una certificazione da visualizzare o su cui agire, chiama GET /primeapi/v2/learningObjects/{loId}/applicableCertification, passando l’ID della certificazione principale come loId.

​3. Utilizza la versione di certificazione restituita nella risposta per indirizzare l’Allievo alla destinazione corretta, che si tratti di un’azione di iscrizione o di una visualizzazione dell’avanzamento corrente.

Ciò garantisce che gli Allievi ottengano sempre la versione della certificazione che corrisponde alla loro iscrizione e al loro avanzamento effettivi, anche se la certificazione si ripete nel tempo e genera nuove versioni.

Report: ID del corso di formazione principale nella Trascrizione Allievo

Per impostazione predefinita, la colonna ID del corso di formazione radice è disponibile nella Trascrizione Allievo per tutti gli account.

Nota: per gli account di grandi dimensioni con un volume elevato di certificazioni, i valori dell’ID del corso di formazione principale nelle trascrizioni degli Allievi vengono risolti in batch. Questo non modifica l’accuratezza dei dati, ma la generazione di trascrizioni molto grandi potrebbe richiedere più tempo.

Questa colonna consente di raggruppare e generare report sulla cronologia completa di un Allievo in ogni versione di una certificazione ricorrente, anziché trattare ogni ricorrenza come un record indipendente e non correlato. Ogni ricorrenza viene comunque visualizzata come riga propria nella Trascrizione Allievo. La colonna ID del corso di formazione principale identifica semplicemente le righe appartenenti alla stessa certificazione sottostante.

Nota: utilizza la colonna ID del corso di formazione principale quando devi tracciare la cronologia completa delle partecipazioni di un Allievo in una certificazione ricorrente.