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 matrícula 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ção | Descrição |
|---|---|
| Armazenamento | Ao 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 completa | Essa 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. |
| Excluir | Esta 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 dados | Apresentada 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:
| Objeto | Operações |
|---|---|
| associação | Armazenamento, 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 esse registro de associação. Para organizações, isso é 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 código do usuário a quem a associação se aplica.
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 as informações sobre a associação STORE, resultando na adição ou atualização de registros conforme apresentado no feed de dados. O segundo é executar as informações sobre a associação REFRESH já presentes no Learn, resultando na adição de novos registros ou na atualização de registros já existentes, conforme apresentado no arquivo de dados, ao mesmo tempo que desativa os registros existentes do Learn, que não estão presentes no arquivo de dados da 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ê quer 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 pessoas com testPerson1, testPerson2 como 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 a 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 do 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
Crie um membership.txt arquivo de dados que contenha os cabeçalhos exigidos e os dados associados por associação que você quer criar/atualizar ou desativar. Por exemplo:
EXTERNAL_COURSE_KEY|EXTERNAL_PERSON_KEY|ROW_STATUS
testcourse2|testPerson3|disabled
testcourse1|testPerson3|enabled
Como STORE opera somente nos dados contidos no arquivo, os dados enviados anteriormente dos registros da associação não são afetados. A operação STORE exigirá a manipulação explícita de 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 da 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 no 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 adicionar, registros de associação a atualizar e exclui registros que foram removidos desde as operações COMPLETE REFRESH anteriores, que devem ser manipuladas corretamente de acordo com a 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çar com os dados da nossa primeira operação de armazenamento de associação e adicionar a associação correta para testPerson3 em testcourse1 e remover a associação incorreta para testPerson3 em testcourse2 oferece resultados semelhantes às várias operações STORE apresentadas acima, uma vez que COMPLETE REFRESH desativa implicitamente todos os registros que não estão 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 é retido e atualizado.
O registro de associação para testcourse1|testPerson3 é adicionado ao Learn.
O registro de associação para testcourse2|testPerson3, porque não está incluído no feed de dados, é marcado como desativado ou pronto para remoção de acordo com a configuração de integração.
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 somente à fonte de dados de integração.
Exemplo: Atualização completa pela fonte de dados
Os dados fornecidos pelo SIA contêm um instantâneo completo de PERSONs que devem ter acesso ao Learn. Esses dados contêm registros PERSON a serem adicionados, registros PERSON a serem atualizados e registros que foram removidos desde as operações anteriores REFRESH, que devem ser manipuladas corretamente de acordo com a 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, porque não está incluído no feed de dados, é marcado como desativado ou pronto para remoção de acordo com a configuração de integração.
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 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. 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
Adicione o cabeçalho AVAILABLE_IND ao feed de dados e forneça 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
ARMAZENAMENTO
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 por causa de sua ausência no feed de dados, a menos que tenham a mesma fonte de dados especificada pela integração. COMPLETE REFRESH BY DATA SOURCE opera apenas nos registros da fonte de dados de 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 pelo 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 removê-la. 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
Adicione o cabeçalho ROW_STATUS ao feed de dados e forneça 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 o ROW_STATUS explicitamente atualizado. 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 o ROW_STATUS explicitamente atualizado. 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 com correspondência com a 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 seria 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 define o controle na integração, de modo que a integração do SIA não impeça qualquer matrícula válida por restrições de lista cruzada. Isso significa que, ao seguir a referência course_child2/course_child1 acima, 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 código 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. Ou seja, 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 de 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 explicitamente atualizados 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 sã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. COMPLETE REFRESH BY DATA SOURCE opera somente nos registros da fonte de dados de integração.
Saiba mais
Visão geral da estrutura do SIA
Descrições de cabeçalho do arquivo simples de instantâneo
