Envio de dados no Conduit

Envio de dados

Há três abordagens para o envio de suas informações ao Conduit:

1. Edições diretas. Você pode adicionar diretamente novos registros ao Conduit por meio da guia Edit (Editar). É possível modificar ou criar novos registros para todos os tipos de registro aqui. 

2. Fazer upload de um arquivo. O Conduit oferece suporte ao consumo automático de arquivos carregados para o ponto de extremidade SFTP e ao upload e processamento diretos de arquivos na guia Operações. O Conduit pode lidar com arquivos CSV e XML com base nos mapeamentos fornecidos.

3. Serviços da Web. Os pontos de extremidade RESTful permitem que os serviços da Web atualizem o Conduit com informações e alterações - não é necessário fazer upload, basta ter um agente ou uma fonte de informações que envie mensagens de serviço da Web. Esses endpoints também suportam métodos GET para recuperar informações. Para obter mais informações, consulte Exemplos e serviços da Web do Conduit.

Formato de dados

Cada registro, uma linha em um CSV ou objeto de dados em um pacote XML que é um objeto para passar pelo Conduit, precisa ter uma ação, um valor de chave de registro e os dados necessários para criar ou atualizar o registro. As exclusões precisam apenas da ação e da chave de registro. 

Exemplo: Um CSV de exclusão pode ter a seguinte aparência:

action, username

delete, user1

delete, user2

Exemplo: Um pacote XML para criar um inscriçãoou matrícula poderia ser:

<?xml version="1.0" encoding="UTF-8"?>

<data>

    <datum action="create">

        <mapping name="course">course_id</mapping>

        <mapping name="user">user_id</mapping>

        <mapping name="role">rolename</mapping>

    </datum>

</data>

Se o Conduit receber mais campos do que mapeou para esse tipo de registro, ele ignorará as informações não mapeadas e registrará um aviso de que dados não mapeados foram passados. Se houver algo errado com as informações do registro, o Conduit registrará uma mensagem de erro detalhando o problema. Para obter mais informações sobre erros e avisos, consulte essas páginas de documentação.

Tip:

Você pode obter uma vantagem inicial na estrutura CSV ou XML acessando a subguia Mappings da guia Conduit Settings e clicando nos botões Download example mappings (Baixar exemplos de mapeamentos) para baixar os cabeçalhos CSV ou o esquema XML para seus mapeamentos de dados configurados.

Ações

Cada registro do Conduit precisa de uma ação, seja em um pacote XML ou no formato CSV. Para a nossa discussão aqui, usaremos o formato CSV mais comum. Para obter detalhes sobre pacotes XML por meio dos serviços da Web, visite a documentação de exemplos e serviços da Web do Conduit. <link para os serviços e exemplos do Conduit Web>

Uma ação informa ao Conduit o que ele deve fazer com o registro de dados a seguir. As ações válidas dependem do tipo de registro, mas sempre incluem criar e excluir. As informações diferenciam maiúsculas de minúsculas. As ações do Conduit são todos comandos em letras minúsculas. 

Ações do curso: create, update, e delete

Ações do usuário: create, update, e delete

Ações de inscrição: create, update, e delete

Ações de atribuição de função: create, update, e delete

Ações de grupos: create, update, e delete

Ações de membros do grupo: create, update, e delete

Cohort Members Actions (Ações dos membros da coorte): create e delete

Nota:

O Conduit não pode excluir usuários que tenham seu tipo de autenticação (mapeamento do campo auth) definido para uma autenticação diferente de “conduit”. Essa ferramenta de autenticação controla esse registro e o Conduit não os excluirá do site. O Conduit tem uma configuração para suspender automaticamente uma conta de usuário que é excluída do Conduit. Recomendamos usar esse recurso para preservar as informações do usuário para relatórios. 

Campos obrigatórios

Os campos obrigatórios são indicados na página Mappings (Mapeamentos) no Conduit, na guia Settings (Configurações). Para referência, veja a seguir os campos obrigatórios para cada tipo de registro.

Usuário: 

O valor do registro principal, conforme definido nas Configurações gerais no Conduit. Pode ser nome de usuário, endereço de e-mail ou número de identificação. Na prática, os registros de usuário sempre precisarão de um nome de usuário, um valor de e-mail, um nome, um sobrenome e um valor de cidade/bairro. 

Curso:

O valor do registro principal, conforme definido nas Configurações gerais no Conduit. Nome abreviado ou número de identificação. Na prática, um curso exigirá um nome abreviado e um nome completo.

Inscrição:

As inscrições exigem um coursekey e um userkey. Na prática, as inscrições também exigem uma função. A função será identificada pelo valor de registro da chave, conforme definido nas Configurações gerais do Conduit. Nome abreviado ou nome. 

Atribuições de função:

Normalmente, as funções não precisam ser separadas das inscrições. Essa funcionalidade serve para a atribuição de funções em espaços incomuns, como categorias ou conteúdo específico em um curso. Não é aconselhável usá-la para inscrições normais. Entre em contato com o suporte ou trabalhe com sua equipe de configuração para determinar se essa funcionalidade é adequada para você. 

As funções exigem um contexto, moodlekey, userkey e rolekey para funcionar. O contexto define o nível de contexto no sistema (categoria, curso, item de conteúdo) e a moodlekey é o valor de registro interno para esse contexto. 

Grupos:

A criação de grupos em um curso requer um coursekey e um groupkey, que podem ser usados para identificar o grupo ao lidar com ações de inscrição em grupo. 

Membros do grupo: 

Os membros do grupo podem ser adicionados depois que os grupos forem criados. Isso requer uma coursekey, uma userkey e uma groupkey. 

Membros da coorte:

A adição de usuários a grupos pode ser feita por meio do Conduit. Isso requer uma userkey e uma cohortkey, que é o número de identificação da coorte de destino. 

Todo o restante dos dados do registro pode ser adicionado e é definido na página Mappings (Mapeamentos) para cada tipo de registro. Nem todos os campos precisam ser mapeados e nem todos os campos mapeados precisam ser preenchidos na mensagem para o Conduit. 

Configuração de padrões

O Conduit também suporta a configuração de valores padrão para campos de registro para usuários e cursos. Na página Mappings (Mapeamentos), para cada campo mapeado, é possível definir um valor padrão para esse registro, de modo que, quando um novo registro for criado, mas esse campo não for fornecido, o Conduit usará o valor padrão fornecido no mapeamento. 

Nota:

Os campos de perfil personalizados (para Usuários e Cursos) estão disponíveis nos mapeamentos, mas não suportam o comportamento do valor padrão. Ao criar um campo personalizado, você pode especificar o valor padrão lá. 

Nomeação de arquivos

Cada tipo de registro tem seu próprio nome de arquivo e o Conduit procurará esses arquivos especificamente nomeados no SFTP e na ferramenta de importação de upload. Cada tipo de registro tem o seu próprio arquivo, portanto, há uma nomenclatura disponível para curso, usuário, matrícula, grupo e associação de grupo, atribuições de função (separadas das matrículas) e associação de coorte na guia Configurações do Conduit > subguia Arquivo.

Por exemplo: O nome do arquivo Usuários é definido como auth.csv para o arquivo CSV de dados do usuário (ou auth.xml para arquivos em formato XML). Quando o Conduit encontrar um arquivo com o nome auth.csv, ele processará esse arquivo para os dados do usuário.

Suporte flexível a nomes de arquivos

Onde os arquivos course.csv podem funcionar como um nome de arquivo fixo para alguns processos, outros podem precisar de suporte para nomes que indexam ou mudam. Você pode configurar o Conduit para usar padrões simples para corresponder a nomes de arquivos que mudam. No mapeamento do nome do arquivo, um asterisco (*) corresponde a qualquer número de caracteres (inclusive nenhum) e um ponto de interrogação (?) corresponde a qualquer caractere único. O (?) está disponível para permitir que você especifique o número de caracteres necessários no espaço variável. 

Exemplo: Fizemos upload dos seguintes arquivos para o diretório SFTP: course_.csv, course_1.csv, course_abcdefghij.csv e course_1667332994.csv.

Atribuir o nome de um arquivo como course_*.csv corresponderia a todos esses arquivos.

Atribuir o nome de um arquivo como course_?.csv corresponderia a course_1.csv, mas não aos outros. 

Atribuir o nome de um arquivo como course_??????????.csv corresponderia a course_abcdefghij.csv e course_1667332994.csv somente porque são necessários 10 caracteres após o course_ e antes do .csv.

Arquivos SFTP

Depois de preparados, os arquivos podem ser carregados no diretório do servidor especificado na guia Conduit Settings > subguia File usando o seu programa SFTP favorito ou a linha de comando SFTP do seu sistema operacional. Aqui estão alguns programas SFTP que você pode usar se ainda não tiver um favorito.

FileZilla http://filezilla-project.org/

WinSCP http://winscp.net/eng/index.php

Se não tiver certeza de suas credenciais de SFTP, poderá solicitá-las em um tíquete de suporte.

Cron do Conduit

O Conduit usa dois crons para realizar as tarefas que possui. Há tarefas na lista de tarefas do cron principal para manter a correspondência de dados entre os registros do Moodle™ e os registros do Conduit. Há também um cron específico do Conduíte que é executado a cada 15 a 20 minutos. Quando o cron do Conduíte é executado, ele pega os arquivos e os processa. Uma vez concluído (com sucesso ou sem sucesso), ele removerá os arquivos do ponto de extremidade SFTP e armazenará todos os arquivos problemáticos no diretório de quarentena especificado na página de configurações Arquivos, a menos que esse comportamento tenha sido desativado pelo administrador do site. 

Nota:

Um Cron é um trabalho agendado que os servidores executam para cuidar de tarefas. Esse trabalho lida com algumas ou muitas tarefas, dependendo do projeto e do que precisa ser feito no momento. O cron do Conduit tem a função principal de procurar arquivos para processar no ponto de entrega SFTP.

Processamento de arquivos

Os arquivos são primeiro agrupados por tipo, curso, usuário, etc., depois classificados por nome de arquivo e enfileirados nessa ordem de prioridade:

• curso
• usuário
• inscrições
• atribuição_de_funções
• grupos
• group_members
• usuários da coorte

O processamento é adiado para uma fila de tarefas do Conduit, com uma tarefa por arquivo. Cada tarefa de arquivo tem um tempo limitado de execução que depende das configurações de processamento de tarefas do site. Cada site também tem uma capacidade de fila de tarefas do Conduíte, cujo padrão é 20. Se fizer upload de arquivos diretamente na guia Operações, o Conduit ainda colocará esses arquivos na fila e aplicará a ordem de prioridade a vários arquivos carregados um após o outro. No entanto, ainda é melhor carregar o lote de arquivos na ordem de prioridade (cursos e usuários antes das matrículas). 

Recomenda-se que a tarefa agendada “Process any Conduit files” (Processar quaisquer arquivos do Conduit) seja definida para ser executada como sua configuração padrão para que os novos arquivos sejam enfileirados o mais rápido possível.

Exemplos:

• 3 arquivos de curso, course_1.csv, course_2.csv e course_3.csv, são coletados pelo Conduit. Quando o cron é executado, todos os arquivos são enfileirados, mas course_1.csv é um arquivo grande que leva muito tempo para ser processado, portanto, os próximos arquivos são ignorados do processamento. Depois de processados, os arquivos course_2.csv e course_3.csv são processados pela próxima execução do cron do Conduit. Quaisquer outros tipos de arquivos, usuários, grupos, inscrições, etc., serão processados da mesma maneira.

• Os 3 arquivos de curso, course_4.csv, course_5.csv e course_6.csv, são todos arquivos relativamente pequenos e são coletados pelo Conduit. Como os três são arquivos pequenos, eles são enfileirados e processados na mesma execução do cron.

Tip: 

Ao fazer upload de novos arquivos via SFTP, nunca sobrescreva um arquivo existente; ele pode conter dados que você precisa preservar. Se estiver usando um script, verifique se há um arquivo existente ou use os curingas na nomeação que permitem criar um novo nome de arquivo para cada upload.

Valores do campo de dados

Cada valor de registro aceita tipos específicos de formatos e usa validação com base no tipo de dados que o campo contém. Por exemplo, se os usuários estiverem sendo criados com um modo de autenticação interna (manual ou conduíte) e o site estiver usando políticas de força de senha, essas políticas também serão aplicadas às senhas fornecidas ao Conduíte. A criação de registros com senhas que falham resultará em uma mensagem de erro.

Para obter mais informações sobre valores de campo e validação do Conduit, consulte o artigo Mapeamentos do Conduit.