Os exemplos a seguir demonstram a composição dos feeds de dados da associação enquanto atendem a uma variedade de casos de uso. Esses exemplos usam o feed de dados mais simples possível exigido para atender ao caso de uso. Há mais cabeçalhos do feed de MEMBERSHIP para uso na criação de registros de associação. A análise do sistema de informações da sua instituição e os requisitos e o planejamento do registrador ajudarão a determinar a profundidade dos dados necessários para preencher corretamente o Learn para atender aos seus dados e às metas do ciclo de vida da associação.

Os exemplos são baseados nas configurações padrão do Learn na IU de configuração da integração. Alterar esses elementos de configuração resultará em alterações nos resultados de exemplo. Explicações dessas configurações estão disponíveis em Visão geral da estrutura do SIA. Além disso, supõe-se que, a menos que observado de outra forma, a integração esteja configurada para usar a mesma fonte de dados para todos os dados de entrada.

Notas sobre associações em cursos mesclados

Ao criar associações em cursos mesclados, os seguintes critérios garantem o sucesso:

  • Siga as informações do SIA. As associações devem manter um padrão pelo SIA. Não force todas as associações ao curso pai.
  • Uma associação pode não existir em mais de um curso filho em cursos mesclados. O SP 12 introduziu um novo mapeamento de campo em associações de curso para auxiliar no gerenciamento de matrículas em cursos mesclados (Mover inscrição cruzada), que, quando aplicado, fará com que a associação e os dados/conteúdos associados sejam movidos do curso atual para um novo curso secundário (consulte o seguinte exemplo de uso).
  • Ao mover a matrícula cruzada, você deve desativar a associação em um curso secundário antes de criar uma associação em outro. Se sua instituição permitir uma ampla política de matrícula no curso em que os alunos possam se matricular em mais de uma instância do curso, você terá erros de integração nas solicitações de associação adicionais. Por exemplo, Math100 tem três cursos secundários (Math100.1, Math100.2 e Math100.3) e um aluno seleciona Math100.2 e Math100.3 como opções durante o período de matrícula. Um ou outro produzirá um erro no processamento no Learn, dependendo da associação filha que for processada primeiro.

Sobre dados de associação

Os dados de associação são o conjunto de informações principais que determina o acesso a um curso ou organização por um usuário com uma função não administrativa.

Operações

Os dados podem ser fornecidos ao Learn e, posteriormente, atualizados, removidos ou corrigidos. Assim, você pode começar com o conjunto de dados mais simples e aumentar conforme a mudança nos requisitos de dados da sua instituição.

Gerenciamento de dados do arquivo simples de instantâneo

A estrutura do SIA é compatível com uploads do feed de dados de arquivos simples de instantâneos por meio de um upload do feed de IU e por meio de um conjunto de URLs fornecido pelo sistema do Learn.

Acesse as informações de HTTP e carregue os arquivos do feed por meio do menu de integração na IU de integração de sistemas de informações do aluno de integração de dados de administração do sistema.

Em ambos os casos, o comportamento da operação de dados é orientado pela configuração da integração e pelo tipo de operação selecionado. O tipo de operação de dados selecionado controla como os dados no feed são "interpretados" e cada URL fornecerá diferentes resultados para atender às metas desejadas da sua integração.

OperaçãoDescrição
ArmazenarAo usar esse tipo de operação, os dados contidos no arquivo de feed são armazenados ou atualizados (por definições de configuração) em todas as fontes de dados que pertencem à integração. (consulte Visão geral da estrutura do SIA para ver a "propriedade" e a fonte de dados.)
Atualização completaEssa operação armazena ou atualiza os dados contidos no feed de dados e, ao mesmo tempo, desabilita os dados que não estão contidos no feed de dados associado à integração em todas as fontes de dados.
DeleteEsta operação desabilita, por configurações de integração, os registros contidos no feed de dados associado à integração em todas as fontes de dados.
Atualização completa pela fonte de dadosApresentada no SP 12, essa operação executa uma atualização completa dos dados associados APENAS à fonte de dados configurada para integração. Esta operação emula mais de perto o processo de instantâneo da linha de comando para atualizar dados.

Os objetos associados às operações de associação são:

ObjetoOperações
associaçãoArmazenamento, atualização completa, exclusão, atualização completa pela fonte de dados

Organizações e cursos compartilham os mesmos padrões para o gerenciamento de associações. Eles precisam de cabeçalhos diferentes, no entanto, e eles serão indicados onde for apropriado, mas os exemplos manterão um foco no gerenciamento da associação do curso.

Os exemplos fornecidos são demonstrados usando o recurso de arquivo de feed de upload da IU da estrutura do instantâneo. Para saber mais sobre como automatizar ou usar outras linhas de comando/operações de programação, consulte Automação de arquivo simples de instantâneo.

Um lembrete sobre chaves de fonte de dados

Todos os objetos de dados oferecem suporte à capacidade de alterar a chave de fonte de dados para o agrupamento do conjunto de dados e podem ser usados para alterar a fonte de dados associada.

Este não é um campo obrigatório em feeds de dados baseados na estrutura e, a menos que indicado, os exemplos fornecidos presumem que a integração esteja configurada para usar uma única fonte de dados. Apresentado no SP 12, é a capacidade de especificar a fonte de dados no feed de dados separadamente da especificação de uma nova fonte de dados. Consulte Gerenciamento da chave de fonte de dados e a seção sobre como alterar a fonte de dados de um registro da associação.

Observações sobre mapeamento de campo

O mapeamento de campo fornece a capacidade de alterar os dados de entrada antes de serem armazenados no Learn. Isso permite que você tenha total controle sobre os dados que são armazenados e permite que você cumpra as regras específicas do Learn quando os dados do SIA fornecidos forem insuficientes, como a criação de uma entrada adequada de nome de associação. Quando aplicado a um campo do objeto de associação, o script associado é executado de acordo com o registro da associação, alterando ou fornecendo os dados antes de serem armazenados no Learn. Uma explicação completa do mapeamento de campo é fornecida em Mapeamento de campo personalizado de arquivo simples de instantâneo.

Exemplos da operação de associação

Em um nível alto, você pode identificar três padrões de feed de dados de integração do SIA que podem ser aplicados a todas as operações de dados de associação e a seleção do padrão depende dos dados que você pode fornecer.

  • Usando um único arquivo de feed, você pode armazenar e atualizar registros (armazenar) utilizando um processo separado para desativar (excluir) registros
  • Usando um único arquivo de feed, você pode armazenar, atualizar e desativar registros (atualização completa)
  • Usando uma combinação de arquivos, você pode armazenar com um, desativar com um segundo.

Finalmente, e esse não é um padrão de feed do SIA, mas vale a pena mencionar, você também pode desativar e limpar com base no DSK sozinho, utilizando a ferramenta de gerenciamento de fonte dados disponível na IU. Você deve ser muito discreto ao gerenciar os dados fornecidos pelo SIA dessa maneira. Isso é extremamente útil ao limpar dados que nunca foram ou não são mais fornecidos pelo SIA ou pelo resultado de operações de teste.

Apenas os princípios básicos: Associações

Todas as associações requerem um conjunto básico de informações a ser estabelecido. Essas informações são detalhadas em Formato de dados do arquivo simples de instantâneo e Descrições do cabeçalho do arquivo simples de instantâneo.

Se você estiver usando as ferramentas de lote da IU alternando para o uso da estrutura do SIA e usando os dados mínimos de associação e os recursos de upload da IU da estrutura do SIA, você terá mais registros e relatórios de uploads de dados sem alterar seus processos de coleta desses dados.

Dados em breve

O conjunto mínimo de dados ou os cabeçalhos necessários para criar uma conta de associação no Learn consistem em:

  • EXTERNAL_COURSE_KEY: um identificador exclusivo para este registro de associação. Para organizações, é EXTERNAL_ORGANIZATION_KEY.
  • NEW_DATA_SOURCE_KEY: um identificador exclusivo para os dados define este registro.
    Observação: isso é fornecido no feed ou por meio da configuração de integração.
  • EXTERNAL_PERSON_KEY: o ID do usuário ao qual a associação é aplicada.

A estrutura do SIA por uma configuração de integração fornece valores padrão para campos não obrigatórios ou os ignora. Três campos úteis que não são obrigatórios para um feed de associação são AVAILABLE_IND, ROW_STATUS e ROLE. Eles serão abordados no seguinte caso de uso.

Cada um desses cabeçalhos é descrito completamente em Descrições do cabeçalho do arquivo simples de instantâneo.

Como adicionar informações sobre a associação

Existem dois casos de uso para adicionar informações sobre a associação. O primeiro é executar STORE informações sobre a associação, resultando na adição ou atualização de registros, conforme apresentado no feed de dados. O segundo é REFRESH informações sobre a associação já presentes no Learn, resultando na adição de registros novos ou na atualização de registros já existentes, conforme apresentado no arquivo de dados, ao mesmo tempo que desativa os registros já existentes do Learn que não estão presentes no arquivo de dados de associação.

Exemplos da operação de armazenamento

Exemplo 1: Criar associações

Você deseja adicionar associações ao Learn sem afetar as contas existentes. Você tem sua integração configurada para usar a mesma fonte de dados para todos os dados de entrada.

Pré-requisito

O curso e o usuário devem existir antes que uma operação de associação seja realizada com sucesso.

Requisitos mínimos do feed de dados

EXTERNAL_COURSE_KEY

EXTERNAL_PERSON_KEY

Solução

Crie um arquivo de dados memberships.txt que contenha os cabeçalhos exigidos e os dados associados por associação que você queira adicionar ao sistema. Por exemplo:

EXTERNAL_COURSE_KEY|EXTERNAL_PERSON_KEY
testcourse1|testPerson1
testcourse1|testPerson2
testcourse2|testPerson3

Use a IU para carregar este arquivo por meio do tipo de dados de associação usando a operação STORE. As contas da associação serão criadas e você poderá descobri-las por meio das ferramentas da associação do administrador do sistema.

Pós-condições

Associações em testcourse1 foram criadas para as pessoas com testPerson1, testPerson2 como sua EXTERNAL_PERSON_KEY e uma associação em testcourse2 foi criada para testperson3.

Exemplo 2: Atualizar associações

Você criou as contas de associação e precisa alterá-las. Por exemplo, o exemplo acima adicionou testPerson3 a testcourse2 quando deveria ter sido para testcourse1.

Observe que embora seja possível fazer a alteração correta no feed de dados: testcourse1|testPerson3, a associação anterior testcourse2 permanecerá em vigor até ser desativada. Isso pode ser feito em um único feed, adicionando o elemento de cabeçalho ROW_STATUS.

Pré-requisito

Os registros pessoais e do curso devem existir no Learn.

O registro para desativar deve ser preexistente no Learn.

Solução

Criar um arquivo de dados membership.txt que contenha os cabeçalhos exigidos e os dados associados por associação que você queira criar/atualizar ou desativar. Por exemplo:

EXTERNAL_COURSE_KEY|EXTERNAL_PERSON_KEY|ROW_STATUS
testcourse2|testPerson3|disabled
testcourse1|testPerson3|enabled

Como STORE opera apenas nos dados contidos no arquivo, os dados enviados anteriormente dos registros de associação não são afetados, a operação STORE exigirá a manipulação explícita dos dados se você quiser que os registros sejam desativados.

Use a IU para carregar este arquivo por meio do tipo de dados de associação usando a operação STORE. Os registros da associação no arquivo serão atualizados.

Pós-condições

Os registros de associação para testPerson3 são atualizados para desativar explicitamente a associação testcourse2 para testPerson3 durante a criação e ativação de uma associação em testcourse1.

Registros de associação criados anteriormente não são afetados.

Associação: Operação de atualização completa

COMPLETE REFRESH opera de maneira diferente de STORE. COMPLETE REFRESH executa duas operações que se aplicam a uma comparação dos dados no arquivo de feed e aos registros do Learn de propriedade da integração: armazenar novos registros, atualizar registros existentes ou desativar registros no Learn que não estejam no arquivo de dados.

Exemplo: Atualização completa

Os dados fornecidos pelo SIA contêm um instantâneo completo das associações de cursos que devem existir no Learn. Esses dados contêm registros de associação a serem adicionados e atualizados, e excluem registros que foram removidos desde as operações anteriores de COMPLETE REFRESH, que devem ser manipuladas corretamente por configuração (desativar ou remover).

Pré-requisito

Os registros pessoais e do curso devem existir no Learn.

Requisitos mínimos do feed de dados

EXTERNAL_COURSE_KEY

EXTERNAL_PERSON_KEY

Solução

Começando com os dados da nossa primeira operação de armazenamento de associação e adicionando a associação correta para testPerson3 em testcourse1 e removendo a associação incorreta para testPerson3 em testcourse2, fornece resultados semelhantes às várias operações STORE apresentadas acima, como COMPLETE REFRESH desativa implicitamente quaisquer registros que não estejam no arquivo.

EXTERNAL_COURSE_KEY|EXTERNAL_PERSON_KEY
testcourse1|testPerson1
testcourse1|testPerson2
testcourse1|testPerson3

Observe que se outros registros de associação forem gerenciados por esta integração, eles serão desativados ou removidos devido à sua ausência no feed de dados acima.

Pós-condições

O registro de associação para testcourse1|testPerson1 e testcourse1|testPerson2 são retidos e atualizados.

O registro de associação para testcourse1|testPerson3 é adicionado ao Learn.

O registro de associação para testcourse2|testPerson3 está marcado como desativado ou pronto para remoção pela configuração de integração porque não está incluído no feed de dados.

Associação: Operação de atualização completa pela fonte de dados

COMPLETE REFRESH BY DATA SOURCE executa uma operação COMPLETE REFRESH, mas restringe os dados afetados àqueles associados apenas à fonte de dados da integração.

Exemplo: Atualização completa pela fonte de dados

Os dados fornecidos pelo SIA contêm um instantâneo completo de PERSON que devem ter acesso ao Learn. Esses dados contêm registros PERSON a serem adicionados, registros de PERSON atualizados e que foram removidos desde as operações anteriores de REFRESH, que devem ser manipuladas corretamente por configuração (desativar ou remover). Além disso, todos os dados nessa atualização são direcionados usando a mesma fonte de dados definida na integração e você quer que apenas os dados relacionados a essa chave de fonte de dados sejam afetados.

Pré-requisito

Os registros pessoais e do curso devem existir no Learn.

Requisitos mínimos do feed de dados

EXTERNAL_COURSE_KEY

EXTERNAL_PERSON_KEY

Solução

Usar os dados da nossa última operação de armazenamento adiciona uma nova associação para testPerson3 em testcourse1 e remover testcourse2|testPerson3 do feed de dados:

EXTERNAL_COURSE_KEY|EXTERNAL_PERSON_KEY
testcourse1|testPerson1
testcourse1|testPerson2
testcourse1|testPerson3

Pós-condições

O registro de associação para testcourse1|testPerson1 e testcourse1|testPerson2 é retido e atualizado.

O registro de associação para testcourse1|testPerson3 é atualizado/adicionado ao Learn

O registro de associação para testcourse2|testPerson3 está marcado como desativado ou pronto para remoção pela configuração de integração porque não está incluído no feed de dados.

Se outros registros de associação forem gerenciados por esta integração, eles não serão desativados ou removidos devido à sua ausência no feed de dados, a menos que tenham a mesma fonte de dados especificada pela integração.

Disponibilidade da associação

A configuração de disponibilidade da associação permite que uma conta do Learn fique visível aos alunos (disponível) ou não visível (não disponível). Observe que isso não é o mesmo que desativar uma associação, o que não apenas torna a associação indisponível a todos, mas também significa que ela não está disponível para outras operações, como gerenciamento de associação por meio da IU. A adição desse cabeçalho do feed de dados não afeta o uso demonstrado acima de STORE, COMPLETE REFRESH, COMPLETE REFRESH BY DATA SOURCE para criar registros de associação.

Observe as configurações de integração padrão quando uma configuração de AVAILABILITY não é fornecida no feed de dados para que o objeto seja disponibilizado em operações de criação/atualização.

Exemplo: Disponibilidade da conta de associação

O SIA controla a disponibilidade de acesso ao Learn e o feed de dados indica a configuração de disponibilidade dos usuários, para controlar quando eles terão acesso ao Learn, e você pode controlar essa configuração de acesso na criação/atualização de PERSON.

Pré-requisito

Os registros pessoais e do curso devem existir no Learn.

Requisitos mínimos do feed de dados

EXTERNAL_COURSE_KEY

EXTERNAL_PERSON_KEY

AVAILABILITY_IND

Solução

Adicionar o cabeçalho AVAILABLE_IND ao feed de dados e fornecer o único caractere de Y para disponível e N para indisponível.

EXTERNAL_COURSE_KEY|EXTERNAL_PERSON_KEY|AVAILABLE_IND
testcourse1|testPerson1|Y
testcourse1|testPerson2|Y
testcourse1|testPerson3|Y
testcourse2|testPerson3|N

Pós-condições

STORE

Apenas os registros de associação para testcourse1 e testcourse2 são criados ou atualizados com o estado de disponibilidade atual.

Operação de atualização completa

Os registros de associação para testcourse1 e testcourse2 são criados ou atualizados com o estado de disponibilidade atual. Todos os outros registros serão desativados ou marcados para remoção devido à ausência no feed de dados acima.

Atualização completa pela fonte de dados

Os registros de associação para testcourse1 e testcourse2 são criados ou atualizados com o estado de disponibilidade atual. Se outros registros de associação forem gerenciados por outra integração, eles não serão desativados ou removidos devido à sua ausência no feed de dados, a menos que tenham a mesma fonte de dados especificada pela integração. A atualização completa pela fonte de dados opera apenas nos registros da fonte de dados da integração.

Desativar registros de associação

Desativar um registro de associação no Learn faz com que ele fique inacessível a todos os usuários (o status desativado substitui a configuração de disponibilidade) e também torna o registro inacessível para operações de IU. Por exemplo, não é possível gerenciar uma associação desativada por meio da IU. Além disso, para remover um registro do Learn, é preciso primeiro desativá-lo.

Desativar um registro e descartar na sequência remove todas as referências a esse registro do Learn. A Blackboard recomenda que a remoção de registros desativados só seja realizada após um período determinado pelo seu negócio e/ou por práticas jurídicas que possam exigir um registro de atividade.

A desativação dos registros pode seguir dois modelos: Desativação pela exclusão de dados do feed em operações REFRESH e desativação pelo uso do cabeçalho do feed ROW_STATUS.

As operações de associação anteriores que usam operações REFRESH demonstram como desativar por exclusão. O caso e o exemplo a seguir demonstram por meio do uso de ROW_STATUS.

Exemplo: Desativar registros de associação

A política determina que você remova completamente as associações do Learn após um período de 5 anos (diferente de tornar o registro indisponível, o que apenas restringe a visibilidade). Se você estiver usando operações STORE, será necessário desativar explicitamente a associação usando o cabeçalho ROW_STATUS para remover a associação. Isso também é útil em operações manuais fora do escopo dos feeds do SIA.

Pré-requisito

Os registros pessoais e do curso devem existir no Learn.

Requisitos mínimos do feed de dados

EXTERNAL_COURSE_KEY

EXTERNAL_PERSON_KEY

ROW_STATUS

Solução

Adicionar o cabeçalho ROW_STATUS ao feed de dados e fornecer ENABLED para ativado e DISABLED para desativado.

EXTERNAL_COURSE_KEY|EXTERNAL_PERSON_KEY|ROW_STATUS
testcourse1|testPerson1|enabled
testcourse1|testPerson2|enabled
testcourse1|testPerson3|enabled
testcourse2|testPerson3|disabled

Pós-condições

Armazenamento

Somente os registros de associação contidos no feed de dados são criados ou atualizados com o ROW_STATUS atualizado explicitamente.

Atualização completa

Os registros de associação contidos no feed de dados são criados ou atualizados com ROW_STATUS atualizado explicitamente. Todos os outros registros serão desativados ou marcados para remoção devido à sua ausência no feed de dados.

Atualização completa pela fonte de dados

Os registros de associação contidos no feed de dados são criados ou atualizados com ROW_STATUS atualizado explicitamente. Se outros registros de associação forem gerenciados por outra integração, eles NÃO serão desativados ou removidos devido à sua ausência no feed de dados acima, a menos que tenham a mesma fonte de dados especificada pela integração. COMPLETE REFRESH BY DATA SOURCE opera apenas em registros correspondentes à fonte de dados de integração.

Novo no SP 12

Exemplo: Mover a matrícula de lista cruzada

O uso de cursos mesclados apresenta algumas restrições sobre o processamento de associação (matrícula). Especificamente, um usuário pode não ter simultaneamente uma associação ativada em mais de um dos cursos mesclados.

Em determinados cenários de lista cruzada, o SIA normalmente será impedido de realizar a matrícula de um usuário em course_child2 se o usuário já estiver matriculado em course_child1 em um conjunto de lista cruzada (mesclada). O campo Move Cross-Listed Enrollment (Mover matrícula de lista cruzada) define o controle na integração, podendo permitir que integração do SIA não impeça qualquer matrícula válida por restrições de lista cruzada. Isso significa, seguindo a referência course_child2/course_child1 acima, que a matrícula para course_child1 seria movida de course_child1 para course_child2.

O mapeamento de campo para o gerenciamento de matrículas em listas cruzadas está disponível por meio da "configuração avançada" de cada instância de integração. Ela é uma parte dos mapeamentos de campo de objeto de "matrícula" e é denominada "Mover matrícula de lista cruzada".

Mover matrícula de lista cruzada usa uma chamada de script interna padrão que sempre retorna "true". Para alterar esse comportamento, você deve fornecer um script que retorne algo diferente de true em algumas ou todas as circunstâncias. Por exemplo, você pode ter um script que simplesmente retorne false ou um script que só retorne false se o ID do curso de Associação atender condicionalmente a algum padrão e assim por diante. Para saber mais, consulte exemplos de mapeamento de campo personalizado.

Esse mapeamento por padrão não espera ser definido "diretamente" como parte do feed para qualquer tipo de integração. Por exemplo, não há nenhuma coluna para ele no arquivo simples de instantâneo, nenhum nó XML para ele no IMS/Vista, etc. Portanto, não há um exemplo de "dados" para esse campo.

Exemplo completo

Combinando os cabeçalhos acima em um único arquivo, podemos abordar a maioria dos casos de uso de uma só vez.

Pré-requisito

Para que a operação de cópia do modelo seja bem-sucedida, testmembership8 não deve ter sido criado anteriormente.

EXTERNAL_COURSE_KEY|EXTERNAL_PERSON_KEY|AVAILABLE_IND|ROW_STATUS
testcourse1|testPerson1|Y|enabled
testcourse1|testPerson2|Y|enabled
testcourse1|testPerson3|Y|enabled
testcourse2|testPerson3|N|disabled

Pós-condições

Armazenamento

Apenas os registros de associação contidos no feed de dados são criados ou atualizados com AVAILABILITY e ROW_STATUS atualizados explicitamente com os seguintes resultados:

Todas as associações têm disponibilidade definida como Sim (Y), exceto para testcourse2|testPerson3, que é definido como Não (N).

Associações para testcourse1 estão definidas como ativadas, enquanto a associação para testcourse2|testPerson3 está desativada.

Atualização completa

Os mesmos resultados da operação de armazenamento com a adição de todos os outros registros gerenciados serão desativados ou marcados para remoção devido à sua ausência no feed de dados.

Atualização completa pela fonte de dados

Os mesmos resultados da operação de armazenamento e também se outros registros de associação forem gerenciados por outra integração não serão desativados ou removidos devido à sua ausência no feed de dados acima, a menos que tenham a mesma fonte de dados especificada pela integração. A atualização completa pela fonte de dados opera apenas nos registros da fonte de dados da integração.

Saiba mais

Visão geral da estrutura SIS

Descrições de cabeçalho do arquivo simples de instantâneo

Formato de dados do arquivo simples de instantâneo

Automação do arquivo simples de instantâneo