Alterações na API na versão de abril de 2026

A versão de abril de 2026 do Adobe Learning Manager apresenta aprimoramentos focados na API pública em torno de alternativas e equivalentes, acesso em janela de tempo ao conteúdo, tentativas de questionário orientadas por conteúdo, experiências não conectadas e manipulação de ajuda de tarefa. As alterações são projetadas para serem amplamente compatíveis com versões anteriores, permitindo integrações mais precisas.

Aprendizado adaptável para caminhos de aprendizado

Esta versão adiciona suporte total à API pública para caminhos de aprendizado adaptáveis. Os Caminhos de aprendizado (LPs) agora podem definir regras adaptáveis que controlam quais seções e objetos de subaprendizado (sub LOs) estão visíveis para diferentes grupos de alunos, e a API pública reflete esse comportamento.

Os seguintes endpoints são afetados:

Um novo atributo booleano, attributes.isAdaptive, indica que um programa de aprendizado usa regras adaptáveis. Quando esse sinalizador é true, o atributo sections é interpretado de forma adaptativa.

Para chamadas do aluno, apenas as seções visíveis para o aluno atual são retornadas. Cada seção inclui a lista de IDs de objetos de aprendizado (loIds), um sinalizador obrigatório e um mandatoryLOCount que são calculados com base na configuração adaptável para esse aluno, bem como o sectionId. A relação relationship.subLOs agora também é filtrada, portanto contém somente os objetos de sub-aprendizado visíveis para esse aluno.

Para chamadas de administrador, as seções também podem expor uma matriz adaptiveConfig. Isso descreve as regras adaptáveis por grupo de usuários, incluindo userGroupId, userGroupName e se a seção é obrigatória para esse grupo. As ferramentas voltadas para o administrador podem usar isso para visualizar e gerenciar regras adaptativas.

Redefinir conclusão de programas de aprendizado

A versão apresenta uma API para atualizar (redefinir) a conclusão de objetos de aprendizado, incluindo programas de aprendizado adaptáveis. Isso suporta cenários como novo treinamento, atualizações periódicas de conformidade ou reinicializações de programas.

Um novo ponto de extremidade está disponível:

POST /primeapi/v2/learningObjects/{loId}/instances/{loInstanceId}/refreshCompletion

Essa operação requer permissões de gravação apropriadas e redefine o estado de conclusão para a instância do objeto de aprendizado especificada no contexto de usuário especificado. Ele deve ser usado por automações do lado do administrador ou ferramentas do aluno com escopo cuidadoso.

Uma versão em massa desse recurso é planejada por meio de uma API de trabalhos. A forma de solicitação é projetada para direcionar usuários por email, ID de usuário ou ID de grupo de usuários, por exemplo:

{
  "emails": ["[user1@example.com](mailto:user1@example.com)", "[user2@example.com](mailto:user2@example.com)"],
  "userIds": ["12345", "67890"],
  "userGroupIds": ["ug1", "ug2"]
}

As integrações devem usar essa API quando precisarem reiniciar os alunos em cada programa ou curso. Os clientes devem tratar as respostas de erro normalmente: a API pode rejeitar solicitações de atualização, quando uma redefinição não é aplicável (por exemplo, quando não existe conclusão ou tipos de objeto de aprendizado sem suporte).

Equivalentes e conclusões alternativas

Para suportar implementações em que vários objetos de aprendizado podem atender ao mesmo requisito, a versão introduz conclusões de equivalentes e alternativas como APIs públicas.

Os pontos de extremidade do Objeto de aprendizado agora contêm estas informações:

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

Um novo atributo booleano attributes.isAlternateComplete indica se a conclusão do aluno para um determinado objeto de aprendizado é o resultado de um objeto de aprendizado alternativo ou equivalente em vez do próprio objeto. Quando isso é verdadeiro, a relação relationship.alternateCompletions lista os objetos de aprendizado que agiam como alternativas. Isso permite que relatórios e painéis de controle de downstream diferenciem conclusões diretas e alternativas e mostrem qual alternativa atendeu ao requisito.

Além disso, uma exibição de objetos de aprendizado relacionados permite a descoberta de alternativas potenciais que podem satisfazer um objeto de aprendizado. Isso é exposto por meio de:

GET /primeapi/v2/learningObjects/{loId}/relatedLOs?type=sourceAlternateLOs&limit={n}

A resposta retorna objetos de aprendizado que podem atuar como alternativas e inclui um campo meta.count que indica o número total dessas alternativas, independentemente do limite atual. As integrações podem usar isso para apresentar equivalentes recomendados ou para criar exibições administrativas de mapeamentos alternativos.

Casos de uso do Reporting and analytics

Os usuários que geram relatórios ou análises devem atualizar sua lógica para adicionar isAlternateComplete e alternateCompletions em seus fluxos de trabalho de relatórios.

As integrações de relatórios que consomem dados de conclusão (por exemplo, exportação de LT, feeds de data warehouse personalizados ou painéis de BI) devem estender sua lógica para ler e persistir os atributos. isAlternateComplete e relationship.alternateCompletions das APIs do LO:

Casos de uso típicos:

Sem incorporar esses dois campos, os relatórios de downstream tratarão as conclusões alternativas como conclusões regulares e não poderão explicar por que um aluno mostra como concluído um treinamento que nunca fez diretamente.

Comportamento do aluno vs. da API do OA do administrador

A estrutura de ajuda de tarefa multilíngue é idêntica nas APIs do aluno e do administrador. O escopo do aluno retorna apenas as ajudas de tarefa visíveis para o aluno, mas para cada ajuda de tarefa visível ele expõe todas as localidades configuradas por meio de várias entidades de recurso (uma por localidade) e vários localidades localizedMetadata. O escopo do administrador retorna todas as ajudas de tarefa que o administrador pode gerenciar, com o mesmo modelo de OA e IDs de recurso específicas da localidade. Os clientes com escopo do aluno devem escolher o recurso cujos attributes.locale melhor correspondam ao idioma do conteúdo do aluno, enquanto as ferramentas de administrador podem enumerar todas as localidades para relatório e gerenciamento.

Lista de verificação com recurso de comentários

Para oferecer suporte a fluxos de trabalho em que os revisores podem compartilhar feedback estruturado em atividades baseadas em listas de verificação, esta versão mostra comentários de listas de verificação e controles de visibilidade do revisor por meio da API de recurso do objeto de aprendizado.

Os metadados relacionados à lista de verificação são expostos nas entidades learningObjectResource (JApiLOResource, “type”: “learningObjectResource”) que representam recursos da lista de verificação em um curso ou outro objeto de aprendizado.

As informações estão disponíveis através de:

GET /primeapi/v2/learningObjects/{loId}?include=instances.loResources

Quando a instância do objeto de aprendizado contém recursos do tipo lista de verificação, as entradas learningObjectResource correspondentes na matriz incluída expõem os atributos comment e reviewer-visibility em atributos em atributos e a identidade do revisor em relacionamentos.

Novos atributos de comentário na lista de verificação

Para recursos de lista de verificação, os seguintes atributos podem estar presentes em learningObjectResource:

Outro contexto específico da lista de verificação, como checklistEvaluationStatus, isChecklistMandatory, resourceSubType: “CHECKLIST” e submissionDate também estão disponíveis no mesmo learningObjectResource para oferecer suporte a interfaces de usuário e relatórios de lista de verificação mais avançados.

Relacionamento de identidade do revisor

Quando os nomes dos revisores devem ser visíveis, o learningObjectResource inclui um relacionamento que aponta para o usuário do revisor:

"relationships": {
  "checklistReviewedBy": {
    "data": {
      "id": "user_id",
      "type": "user"
    }
  }
}

Esta relação é populada somente se:

Os aplicativos cliente devem:

Acessando recursos e comentários da lista de verificação

Para recuperar recursos de lista de verificação e seus comentários para um determinado objeto de aprendizado, os clientes devem:

GET /primeapi/v2/learningObjects/{loId}?include=instances.loResources

Esse padrão permite que clientes sem periféricos ou personalizados renderizem uma experiência abrangente de lista de verificação, incluindo status, sinalizadores obrigatórios/opcionais e feedback do revisor, diretamente das APIs do Prime.

Considerações sobre emissão de relatórios e UX

Suporte multilíngue para ajuda de tarefa

Para oferecer suporte a implementações em que as ajudas de tarefa devem ser entregues em vários idiomas para alunos e administradores, esta versão estende a manipulação da ajuda de tarefa para retornar um recurso por localidade em vez de um único recurso en-US codificado.

As ajudas de tarefa em vários idiomas continuam a usar a hierarquia existente:

Objeto de aprendizado (lo) → learningObjectResource (loResource) → recurso

Nenhuma alteração é necessária no contrato de API. Qualquer ajuda de tarefa localizada se encaixa naturalmente nessa estrutura, com entidades de recurso separadas por localidade e metadados localizados compartilhados nos níveis learningObject/learningObjectResource.

Os dados de ajuda de tarefa são expostos por meio de:

GET /primeapi/v2/learningObjects/jobAid:{jobAidId}?include=instances.loResources.resources

Quando uma ajuda de tarefa tem várias variantes de idioma, a matriz incluída contém várias entradas “type”: “resource” — uma para cada localidade (por exemplo, en-US, fr-FR, es-ES), todas vinculadas a partir de um único learningObjectResource.

Estrutura de ajuda de tarefa em vários idiomas

Uso de ajudas de tarefa em vários idiomas:

Para uma ajuda de tarefa em vários idiomas, um padrão típico é:

Os clientes podem selecionar o recurso apropriado fazendo a correspondência da localidade do aluno com o campo resource.attributes.locale.

Novo formato de ID de recurso para ajudas de tarefa

Para diferenciar corretamente várias variantes localizadas de um recurso de ajuda de tarefa, o formato da ID de recurso foi alterado.

Formato de ID de recurso antigo (herdado)

Anteriormente, os recursos de ajuda de tarefa usavam um formato de ID opaco, como:

jobAid:131032_-1_-1_2_resource

Esse formato não codificava a localidade, e as APIs apresentavam efetivamente apenas um único recurso (geralmente en-US).

Novo formato de ID de recurso (com reconhecimento de vários idiomas)

O novo formato é:

jobAid:<jobAidId>_<version>_<localeCode>

Exemplos:

Discriminação visual:

jobAid:131032_2_fr_FR

        │      │ │ │

        │      │ │ └──► Locale Code (fr_FR, en_US, es_ES, etc.)

        │      │ └────► Version (2)

        │      └──────► JobAid ID (131032)

        └─────────────► Resource Type Prefix ("jobAid:")

Essa estrutura permite aos clientes:

Compatibilidade com versões anteriores:

/resources/{resourceId}

O ponto de extremidade do recurso herdado permanece disponível:

Agora, ele é compatível com versões anteriores com os formatos de ID antigo e novo:

Integrações que atualmente armazenam ou fazem referência às IDs de recurso antigas podem continuar a funcionar sem alteração, enquanto implementações mais recentes são incentivadas a adotar o novo formato de ID para operações específicas da localidade.

Considerações sobre integração e UX

Restrições de timeslot para iniciar módulos

Algumas experiências de aprendizado devem estar disponíveis somente dentro de uma janela de tempo definida. A versão exibe informações de intervalo de tempo nos recursos do objeto de aprendizado e introduz um ponto de extremidade de validação que verifica se um aluno pode iniciar um recurso no tempo atual.

Os metadados de intervalo de tempo estão disponíveis no endpoint:

GET /primeapi/v2/learningObjects/{loId}?include=instances.loResources

No nível de recurso do objeto de aprendizado, um objeto timeSlot agora pode estar presente nos atributos, com valores startTime e endTime em UTC. Especifica a janela durante a qual o recurso pode ser iniciado.

Antes de iniciar um módulo, as integrações podem chamar um novo ponto de extremidade de validação:

GET /primeapi/v2/learningObjects/{loId}/instances/{loInstanceId}/loResources/{loResourceId}/canStart

Esse ponto de extremidade, destinado a cenários lidos pelo aluno, retorna se o aluno tem permissão atualmente para iniciar o recurso, considerando o intervalo de tempo configurado, o tipo de entrega e outras regras de back-end.

Os players personalizados e aplicativos clientes devem usar canStart para impor o acesso baseado em tempo e usar os metadados timeSlot para exibir mensagens claras sobre quando o conteúdo se torna disponível ou expira. As respostas negativas de canStart devem ser tratadas explicitamente para informar aos alunos por que o conteúdo não pode ser iniciado ainda ou mais.

Quizzes de várias tentativas orientados por conteúdo

Alguns pacotes de conteúdo implementam seu próprio rastreamento de tentativas em vez de depender exclusivamente da Adobe Learning Manager. A versão introduz um sinalizador que indica quando as tentativas são orientadas pelo próprio conteúdo.

Até:

GET /primeapi/v2/learningObjects/{loId}?include=instances.loResources

os recursos do objeto de aprendizado agora podem expor um atributo booleano hasContentDrivenAttemptTracking. Quando isso é verdadeiro, o quiz ou o módulo gerencia as tentativas internamente (por exemplo, por meio do SCORM ou da lógica da xAPI), e os contadores de tentativas padrão da plataforma podem não refletir totalmente a experiência do aluno.

As integrações que exibem contagens de tentativas ou controlam o comportamento da repetição devem marcar esse sinalizador. Quando ativada, elas não devem inferir os limites de tentativa apenas a partir dos metadados da plataforma e devem estar preparadas para confiar nos relatórios do lado do conteúdo (por exemplo, por meio de instruções da xAPI) ou em regras específicas dos negócios.

Alteração de comportamento no formato da ID de recurso da ajuda de tarefa

Esta versão apresenta uma importante alteração comportamental no formato de IDs de recursos de Ajuda de tarefa. Embora nenhum novo ponto de extremidade esteja envolvido, isso tem um impacto direto nos sistemas que armazenam ou analisam essas IDs.

Anteriormente, as IDs de recurso de ajuda de tarefa usavam um formato como:

jobAid:<jobAidId>_-1_-1_2_resource

Na versão de abril de 2026, esse texto foi substituído por um formato simplificado e mais explícito:

jobAid:<jobAidId>_<version>_<localeCode>

Por exemplo:

jobAid:131032_2_fr_FR

Os componentes são:

Qualquer integração que indexe recursos ou persista em IDs de recurso de ajuda de tarefa deve atualizar sua lógica de análise e armazenamento para reconhecer o novo formato. Como os próprios identificadores são alterados, é altamente recomendável reconstruir todos os índices locais chaveados por IDs de recurso de ajuda de tarefa após atualizar para a versão de abril de 2026.

Definir imagens de banner do curso por migração

Agora você pode definir ou atualizar imagens de banner do curso no Adobe Learning Manager como parte do fluxo de trabalho de migração padrão. Isso ajuda a iniciar ou limpar grandes catálogos, mantendo as páginas do curso visualmente consistentes, sem editar manualmente

Onde as imagens do banner são definidas

As imagens de banner são configuradas no arquivo de migração do course.csv, que você já usa para fornecer metadados do curso, como:

Com esse aprimoramento, a especificação course.csv inclui uma coluna opcional adicional para a imagem de banner do curso. O nome exato do cabeçalho é definido na especificação do CSV baixada da sua conta do Learning Manager (por exemplo, ele pode aparecer como bannerUrl ou bannerImageUrl).

A coluna do banner:

Preparação de imagens de banner para migração

id,courseName,courseCreationDate,state,author,thumbnailUrl,bannerUrl
12345,DEMO1,2018-05-05T08:56:21.000Z,Published,Sudheer,pic1.png,banners/banner1.png
45678,DEMO2,2018-05-05T08:56:21.000Z,Published,Sudheer,pic2.png,banners/banner2.png

Aplicar banners durante a execução da migração

Depois que seu course.csv é atualizado, o fluxo é o mesmo de qualquer outra migração:

Novos cursos vs. cursos existentes

O campo do banner funciona em ambos os cenários:

Os nomes e caminhos das colunas reais devem corresponder à especificação de CSV baixada e ao layout do repositório de conteúdo.

Remover coluna de ordem em LearningProgramCourse

O Adobe Learning Manager agora oferece suporte a um modelo simplificado de solicitação de cursos nos Caminhos de Aprendizado (Programas de Aprendizado) durante a migração. Como parte dessa alteração, a coluna de ordem é removida do arquivo de migração learning_program_course.csv.

Anteriormente, o arquivo learning_program_course.csv incluía uma coluna (geralmente chamada de ordem ou semelhante) usada para:

Agora, o Adobe Learning Manager não usa mais a coluna de ordem em learning_program_course.csv para determinar a ordem dos cursos. Em vez disso, o CSV de migração se concentra em quais cursos pertencem a qual programa de aprendizado, em vez de como eles são ordenados numericamente.

Impacto nos CSVs de migração

learning_program_course.csv

Você deve tratar a coluna de ordem herdada como removida ou ignorada:

Sempre consulte as especificações do CSV mais recentes da sua conta do Learning Manager (via csv_specifications.zip) para confirmar o conjunto de cabeçalhos e os requisitos atuais.

timeZoneCode em instâncias de curso

A partir desta versão, o modelo Instância do curso (learningObjectInstance) expõe um novo atributo:

timeZoneCode — um campo de string que vincula explicitamente uma instância do curso a um dos fusos horários configurados da conta.

Isso permite que os clientes:

Onde timeZoneCode aparece

O campo é adicionado aos atributos do modelo learningObjectInstance
somente para instâncias do curso.

Exemplo:

{
  "id": "course:1262748_1359228",
  "type": "learningObjectInstance",
  "attributes": {
    "dateCreated": "2019-08-06T13:50:39.000Z",
    "isAET": false,
    "isDefault": true,
    "timeZoneCode": "356",
    "isFlexible": false,
    "state": "Active",
    "localizedMetadata": [
      {
        "locale": "en-US",
        "name": "Default instance"
      }
    ]
  }
}

Como resolver timeZoneCode

O timeZoneCode numérico é uma chave de pesquisa no catálogo de fuso horário da conta, que é exposta pela API Account:

GET /primeapi/v2/account
Authorization: Bearer <access_token>

Na resposta, os fusos horários estão listados em:

"data": {
  "attributes": {
    "timeZones": [
      {
        "name": "Etc/GMT+12",
        "timeZoneCode": "356",
        "utcOffset": -720,
        "utcOffsetCode": "UTC-12:00(Etc/GMT+12)",
        "zoneId": "Etc/GMT+12"
      },
      "..."
    ]
  }
}

Fluxo de cliente recomendado:

APIs públicas assíncronas para associação a grupo de usuários

Introdução

O Adobe Learning Manager expõe duas APIs assíncronas de administrador para gerenciar a associação de grupo de usuários (UG):

Em vez de atualizar a associação na mesma solicitação, essas APIs aceitam seu lote e retornam uma ID de evento. O resultado real é fornecido posteriormente por meio de webhooks.

Use-os quando:

Para ações administrativas pequenas e interativas, você pode continuar usando as APIs síncronas /userGroups/{id}/users.

Autenticação e URL base

Estas APIs fazem parte da superfície padrão API de Administração v2.

Para o comportamento e os escopos gerais da API de administração, consulte:

Formato de solicitação

adicionar e remover usam exatamente a mesma forma de corpo.

Corpo

{
  "metadata": {
    "event_id": "my-optional-correlation-id",
    "sourceSystem": "HRIS",
    "batchId": "hr_2026_03_30_0001"
  },
  "data": [
    { "type": "user", "id": "11101219" },
    { "type": "user", "id": "11101220" }
  ]
}

dados (obrigatório)

dados é a lista de identificadores de recursos do usuário para este lote.

Restrições

Se qualquer uma dessas condições falhar, a API retornará um erro e nada será colocado em fila.

metadados (opcional)

metadata é qualquer dado de correlação adicional que você deseja que seja repetido no Webhook.

Uso típico:

O serviço retorna este objeto inalterado na resposta do Webhook, para que você possa corresponder o retorno de chamada ao seu trabalho interno.

Restrições:

Formato da resposta

Os dois pontos de extremidade respondem de forma síncrona com uma ID de evento:

{ "event_id": "cd2972c8-cb15-47a0-a23f-e4a16cb720f5" }

Comportamento:

Você deve sempre:

Exiba Webhooks para adicionar e remover a associação de grupo de usuários para obter mais informações.

Perguntas frequentes

Como a versão de abril de 2026 altera a API learningObjects para programas de aprendizado adaptáveis?

Esta versão adiciona um sinalizador isAdaptive nos programas de aprendizado e torna as seções e sub-LOs sensíveis ao aluno. Nos programas adaptáveis, os alunos veem apenas as seções e os objetos de subaprendizado que estão visíveis a eles com base em regras adaptáveis, enquanto os administradores podem ver a configuração adaptável subjacente de um grupo de usuários.

Preciso atualizar minha integração se ela considerar que todas as seções e sub-LOs sempre são retornados?

Sim Para programas de aprendizado adaptáveis, a API agora retorna apenas as seções e sub LOs que estão visíveis para o aluno atual. O código do cliente deve tratar a resposta como a exibição autoritativa e possivelmente filtrada, em vez de assumir uma lista completa.

Como redefinir programaticamente a conclusão de um aluno para um curso ou programa de aprendizado?

Usar o novo ponto de extremidade:

POST /primeapi/v2/learningObjects/{loId}/instances/{loInstanceId}/refreshCompletion
Isso redefine a conclusão da instância de destino quando as permissões e o estado permitirem.

Como saber se um aluno concluiu algo por meio de um objeto de aprendizado alternativo ou equivalente?

Verifique o atributo isAlternateComplete no objeto de aprendizado. Se for verdadeiro, o relacionamento alternateCompletions lista os objetos de aprendizado que agiam como alternativas para a conclusão desse aluno.

Como posso encontrar todas as alternativas que podem satisfazer um determinado objeto de aprendizado?

Use o seguinte ponto de extremidade:

GET /primeapi/v2/learningObjects/{loId}/relatedLOs?type=sourceAlternateLOs&limit={n}

e use a matriz de dados (para as alternativas) e meta.count (para o número total de alternativas).

Como saber se um aluno tem permissão para iniciar um módulo neste momento?

Primeiro, busque o timeSlot do recurso de:

GET /primeapi/v2/learningObjects/{loId}?include=instances.loResources
e use:

GET /primeapi/v2/learningObjects/{loId}/instances/{loInstanceId}/loResources/{loResourceId}/canStart

O que significa ContentDrivenAttemptTracking em um recurso?

Indica que o controle de tentativas é controlado pelo próprio conteúdo (por exemplo, por meio da lógica SCORM/xAPI) e não apenas por contadores de plataforma. Quando for verdade, não confie apenas nas contagens ou limites de tentativas de plataforma para sua UX e relatórios.

Como obter menus apropriados para usuários não conectados (experiências públicas)?

Usar:

GET /primeapi/v2/templates/menus?include=pages,subMenus.pages&isNonLoggedIn=true

Isso retorna estruturas de menu e página filtradas para usuários anônimos, adequadas para o Experience Builder ou outros sites sem periféricos.

O que mudou na filtragem da Ajuda de tarefa com effectiveModifiedDate?

As solicitações que combinam filter.effectiveModifiedDate com filter.loTypes=jobAid agora retornam corretamente apenas ajudas de tarefa na janela de data especificada.

O que mudou no formato de ID de recurso de Ajuda de Trabalho e como devo lidar com isso?

O formato da ID mudou de valores como:

jobAid:<jobAidId>_-1_-1_2_resource

até:

jobAid:<jobAidId>_<version>_<localeCode>

por exemplo jobAid:131032_2_fr_FR. Qualquer sistema que armazena ou analisa IDs de recursos de ajuda de tarefa deve ser atualizado, e você deve planejar recriar índices locais chaveados por esses IDs após atualizar para a versão de abril de 2026.