Guias Canvas (pt-br)Guia do Administrador Importações SISComo eu formato arquivos de texto CSV para enviar dados SIS para uma conta do Canvas?

Como eu formato arquivos de texto CSV para enviar dados SIS para uma conta do Canvas?

O Canvas permite que você manualmente crie usuários, contas, períodos, cursos, seções e matrículas em massa através da interface de Administração.

Este documento refere-se à página API do Formato CSV de Importação do SIS, onde a maioria das informações sobre CSV estão localizadas. Cada arquivo CSV é simbiótico com outro e informam ao Canvas como administrar todas as informações para a conta. Veja um diagrama da relação do SIS.

Cada etapa nesta lição oferece arquivos CSV de amostra com descrições de cada campo obrigatório e opcional. Você também vai encontrar um link para baixar cada arquivo em que queira dar uma olhada mais aprofundada na formatação. Baixe um pacote em zip com todos os arquivos de amostra.

Você deve praticar a importação de dados em seu ambiente teste do Canvas antes de importar qualquer conteúdo para seu ambiente de produção.

Formato de Arquivo CSV

Para fazer o envio em massa de dados para o Canvas, você deve criar um ou mais arquivos de texto CSV. Arquivos CSV podem ser gerados por diversos programas. Sistemas de Informação Estudantil (Student Information Systems SIS) frequentemente possuem um método para gerar relatórios em formato CSV que podem ser modificados para se adequar ao formato requerido pelo Canvas. Se você não sabe como salvar um arquivo em formato CSV, consulte a documentação para o programa que estiver utilizando ao criar seu arquivo CSV (por ex., Excel).

Ao usar o formato Instructure para importar arquivos na página de Importação do SIS, você pode importar um arquivo de texto CSV individual ou você pode comprimir vários arquivos em um único arquivo ZIP para a importação de dados em massa. Se você estiver enviando arquivos individuais manualmente, os arquivos devem ser enviados na ordem mostrada nesta lição.

Formatação do Campo CSV

A primeira fileira de seu arquivo CSV (cabeçalho) deve incluir o nome do campo completo para cada arquivo. A ordem das colunas não importa, mas organizar as fileiras adequadamente é essencial para arquivos como accounts.csv. Quando quaisquer desses dados forem modificados na Interface do Usuário (UI), o Canvas irá definir novos valores como "fixos" (sticky). Quando um novo envio básico for realizado, os dados existentes no Canvas irão permanecer "fixos" e quaisquer dados importados que tentarem atualizá-los serão ignorados. Saiba mais sobre campos fixos.

Uma importação só pode substituir alterações na UI se as opções adequadas forem selecionadas ao usar a ferramenta de importação do SIS.

Documentação da API

Os arquivos CSV só incluem um conjunto específico de campos. O Canvas contém valores adicionais disponíveis por cada API individual. Após executar os arquivos CSV para sua instituição, a prática padrão para a maioria das instituição é enviar todos os arquivos CSV do SIS e, em seguida, usar a API do Canvas para atualizar todos os atributos do curso e da conta. Para mais informações, visualize Documentação da API do Canvas para Usuários, Contas, Períodos, Cursos, Turmas, Matrículas e Grupos.

 

users.csv

Os usuários são as pessoas que têm contas de usuário em uma instituição. O arquivo users.csv adiciona pessoas no sistema como usuários genéricos. O arquivo enrollments.csv irá atribuir uma função (professor, estudante, etc.) para esses usuários. Quando uma conta de usuário é "excluída", todas as matrículas serão excluídas também e o usuário não poderá se conectar na conta Canvas. Se você ainda quiser que o usuário consiga se conectar, mas sem participar ou se você quiser apenas excluí-lo de um curso específico, então, deixe a conta de usuário como "ativa" e altere a matrícula (no arquivo enrollments.csv) para "concluído" ou "excluído" respectivamente.

Baixe um arquivo de amostra users.csv com 10 contas de usuário do Canvas.

Campos Obrigatórios*

  • *user_id: Esse é um valor único utilizado para identificar qualquer um com uma conta no Canvas. Esse valor não deve ser alterado para o usuário e deve permanecer único entre todos os usuários. Na interface de usuário, esse campo é chamado SIS ID e pode ser composto por qualquer combinação de caracteres. Você pode encontrar esse SIS ID visitando qualquer conta de usuário e então visualizando sua "Informação de Autenticação" (Login Information)
  • integration_id: Este é um identificador único secundário útil para integrações SIS mais complexas. Este identificador não deve ser alterado para o usuário, e deve ser mundialmente único.
  • *login_id: Esse é o nome de usuário que será utilizando para entrar no Canvas. Se você tem um serviço de autenticação configurado (como LDAP), esse campo tipicamente irá coincidir com o seu nome de usuário no sistema remoto. Login_id pode conter letras, números ou qualquer um dos seguintes símbolos: - _ = + . @
  • password: Se uma conta é configurada para usar LDAP ou qualquer outro protocolo de Single-Sign-On (SSO), então esse campo não é requerido. Caso contrário, essa é a senha para o “login_id” acima. Essa senha deve ter pelo menos 8 caracteres.
  • ssha_password: Em vez de uma senha em texto simples, você pode usar uma senha pré-hasheada utilizando o esquema de geração da senha SSHA neste campo. Apesar de ser melhor do que utilizar uma senha com texto simples, você ainda deve incentivar os usuários a alterarem suas senhas após se conectarem pela primeira vez. Saiba como gerar senhas SSHA.
  • first_name: Esse é o primeiro nome do usuário.
  • last_name: Esse é o sobrenome (último) do usuário.
  • full_name: Esse é o nome e sobrenome do usuário.
  • sortable_name: Esta é a opção de nomes ordenáveis no Canvas, normalmente determinados a partir do nome de usuário, mas podem ser personalizáveis.
  • short_name:Esse é o nome de usuário exibido, normalmente determinado a partir do nome de usuário, mas pode ser personalizado.
  • email: Esse é o "endereço de e-mail atribuído pela instituição" e também será marcado como "endereço de e-mail padrão" para esta conta de usuário. Esse endereço de e-mail ainda deve permanecer mesmo que seja o mesmo que o login_id do usuário.
  • *status: Esse é o campo onde você pode adicionar ou remover usuários do Canvas. Marque como "ativo" ("active") para adicionar um usuário ou "excluído" ("deleted") para remover um usuário existente.

Conflitos de Endereço de E-mail

O Canvas identifica usuários por endereço de e-mail. Quando os alunos são adicionados a um curso, o Canvas tenta conciliar qualquer conflito de endereço de e-mail quando o usuário acessa o curso pela a primeira vez.

Normalmente, endereços de e-mail são exclusivos para cada aluno. Às vezes, vários estudantes podem partilhar um endereço de e-mail único. Quando estiver adicionando os estudantes de cursos através de importação do SIS, o Canvas reconhece quando um endereço de e-mail está atribuído a mais de um aluno.

  • Se um novo ID SIS está associado com um endereço de e-mail já atribuído a um ID SIS existente, o Canvas envia um e-mail para o endereço de e-mail.
  • Quando os usuários são adicionados a uma conta através de importação SIS, eles não receberão uma notificação por e-mail, a menos que o sistema detecte um usuário duplicado. No entanto, se um usuário é adicionado ou matriculado manualmente, eles receberão um e-mail notificando-os que foram adicionados ou matriculados em um curso novo. O aluno que compartilha um endereço de e-mail receberá uma notificação de que o endereço de e-mail já está em uso e é convidado para criar uma nova conta no Canvas. Esse processo também pode ser aplicado ao adicionar um usuário a uma inscrição de curso.

accounts.csv

Uma conta é uma unidade de organização no Canvas (por ex., a conta pai para uma instituição). Cada conta pode conter uma hierarquia de subcontas, como criar contas para faculdades individuais em uma instituição, ou para escolas individuais em um distrito. Subcontas também podem conter várias subcontas, como quando uma faculdade subdivide-se em departamentos ou programas, ou uma escola subdivide-se em níveis escolares ou matérias.

Baixe um arquivo accounts.csv de exemplo com as seguintes subcontas:

  • 3 subcontas em sua conta principal/conta raiz. (Artes & Humanidades, Negócios, Matemática & Ciência) (Arts & Humanities, Business, Math & Science)
  • 4 subcontas em sua subconta Negócios. (Contabilidade, Ciência da Computação, Economia e Marketing) (Accounting, Computer Science, Economics e Marketing)
  • 3 subcontas em sua subconta Matemática & Ciência. (Biologia, Física e Estatística) (Biology, Physics e Statistics)
  • 1 subconta em sua subconta Artes & Humanidades. (Artes Visuais) (Visual Arts)
  • 2 subcontas em sua subconta Artes Visuais. (Fotografia e Mídia Digital) (Photography e Digital Media)

Campos Obrigatórios*

  • *account_id: Esse é um identificador único para criar uma subconta. O arquivo courses.csv irá permitir que você faça a atribuição de um curso para um id de conta (account_id) específico. Esse identificador único não pode ser mudado para a conta e deve ser globalmente único entre todas as contas. Na Interface de Usuário do Canvas (UI), esse campo é chamado SIS ID e pode ser modificado visitando as "Configurações" para cada subconta respectivamente.
  • parent_account_id: Esse identificador indica que uma subconta deve ser alinhada abaixo de sua conta pai. Se esse campo estiver em branco, então a subconta será alinhada abaixo de sua conta raiz ou conta principal. Observe que mesmo se os valores estiverem em branco, a coluna deve ser incluída para diferenciar o arquivo de uma importação de grupo.
  • *name: Esse é o nome para a subconta.
  • *status*: É assim que você pode criar ou remover uma subconta. Marcar ela como "ativa" ("active") para adicionar a subconta ou “excluída” ("deleted") para remover uma subconta existente.

terms.csv

Um período oferece um conjunto padrão de datas iniciais e finais para qualquer curso atribuído para ele. As datas do período para os cursos podem ser administradas manualmente no nível do curso sem um arquivo de importação. No entanto, anexar um term_id para muitos cursos diferentes garante que todos os cursos nesse período irão começar/terminar ao mesmo tempo. As datas do período enviadas também irão ajudar você a ordenar e organizar os cursos ao exibir dados e relatórios na interface do Administrador.

Baixe um arquivo terms.csv de exemplo com 10 períodos.

Campos Obrigatórios*

  • *term_id: Esse é um identificador único para o período. O arquivo courses.csv permite a você referenciar esse term_id para que saiba quando seus cursos irão começar e quando irão ser concluídos. Esse identificador não pode ser mudado para um período e deve ser globalmente único entre todos os períodos. Na interface de usuário, esse campo é chamado SIS ID.
  • *name: Esse é o nome do seu período. Iniciar com uma boa convenção de nomes irá ajudá-lo a referenciar facilmente seus períodos. Existem diversas ferramentas de administração que permitem a você procurar ou consultar dados pelo nome do período.
  • *status: É assim que você pode criar ou remover um período. Marque ele como "ativo" ("active") para adicionar um período ou "excluído" ("deleted") para remover um período existente.
  • start_date: Essa é a data inicial do período. O formato deve ser do ISO 8601: AAAA-MM-DDTHH:MM:SSZ ("T" pode ser substituído por um espaço, como pode se ver na captura de tela de exemplo.) Por exemplo, 26 de agosto de 2013 às 17h EST seria escrito como 2013-08-26T17:00-5:00.
  • end_date: Essa é a data de término do período. O formato deve ser do ISO 8601: AAAA-MM-DDTHH:MM:SSZ ("T" pode ser substituído por um espaço, como pode se ver na captura de tela de exemplo.) Por padrão, o acesso do usuário é cortado à meia-noite na data de término indicada, significando que o dia anterior é o último dia inteiro que os usuários têm acesso ao período. A melhor prática é definir sua data final para o dia após o término do período.

courses.csv

Um curso é uma apresentação organizada sobre um assunto específico. Às vezes um curso pode incluir uma série de cursos. Os cursos são colocados em períodos para criar datas inicias e finais padrão. No entanto, se um curso inclui datas de cursos específicas, essas datas irão substituir as datas de acesso do estudante no período, identificado por term_id (se incluído). A importância de anexar um term_id é que você poderá ordenar e organizar os cursos ao exibir dados e relatórios, na interface do Administrador. Um term_id pode ser facilmente anexado à muitos cursos diferentes que começam/terminam ao mesmo tempo. Se você não vincular um curso à um período, o curso será vinculado ao período chamado "Período Padrão".

Baixe um arquivo courses.csv de exemplo com 10 cursos; eles estão localizados em suas subcontas respectivas em um período específico.

Campos Obrigatórios*

  • *course_id: Esse é um identificador único usado para diferenciar cursos no Canvas. Esse identificador não pode ser mudado para um curso e deve ser globalmente único entre todos os cursos. Na interface de usuário, esse é chamado SIS ID.
  • *short_name: Esse é um nome curto para o curso. Na Interface de Usuário do Canvas esse campo é chamado "Código do Curso" (Course Code).
  • *long_name: Esse é o nome longo (completo) para o curso. (Ele pode ser o mesmo que o nome curto, mas se ambos estão disponíveis, ele irá fornecer uma melhor experiência para o usuário quando os dois forem fornecidos.)
  • account_id: Esse é um identificador único de conta (do arquivo accounts.csv) que diz para o curso, em qual subconta ele reside. Se um account_id não é especificado, então o curso será alinhado abaixo de sua conta principal/raiz.
  • term_id: Esse é um identificador único de período (do arquivo terms.csv) que diz quando o curso deve começar e quando deve concluir. Se associado um term_id com o curso, não será necessário que você insira uma data inicial (start_date) ou data final (end_date).
  • *status: É assim que você pode criar, remover ou concluir um curso. Marque como "ativo" ("active") para adicionar um curso ou "excluído" ("deleted") para remover um curso existente, ou "concluído" ("completed") para concluir um curso existente.
  • start_date: Essa é a data em que o curso se inicia. O formato deve ser do ISO 8601: AAAA-MM-DDTHH:MM:SSZ ("T" pode ser substituído por um espaço.)
  • end_date: Essa é a data em que o curso é concluído. O formato deve ser do ISO 8601: AAAA-MM-DDTHH:MM:SSZ ("T" pode ser substituído por um espaço). Por padrão, o acesso do usuário é cortado à meia-noite na data de término indicada, significando que o dia anterior é o último dia completo que os usuários têm acesso ao curso. A melhor prática é definir sua data final para o dia após o término do curso.
  • course_format: Este é o formato para o curso. O formato pode ser "online", "on_campus", ou "misto" ("blended").

sections.csv

Uma turma subdivide estudantes em um curso. Várias turmas também podem ser adicionadas em um curso, especialmente se todas as turmas do estudante estiverem aprendendo o mesmo material de curso. Várias turmas podem ser colocadas em um curso, mas um turma não pode ser colocada em várias turmas. As turmas herdam as datas do curso, conforme definidas pelo período. No entanto, se uma turma incluir datas específicas, essas datas irão substituir as datas de acesso do estudante para as datas iniciais e finais do curso e do período.

Se você estiver tentando excluir um curso e os usuários estiverem associados com seções, você precisa incluir o parâmetro section_id na importação do CSV, assim como nos SIS IDs da turma.

Baixe um arquivo sections.csv de exemplo com as seguintes seções:

  • 4 turmas no curso "ACCT300 - Contabilidade de Custos" ("ACCT300 - Cost Accounting")
  • 4 turmas no curso "ACCT310 - Contabilidade Gerencial" ("ACCT310 - Managerial Accounting")
  • 2 turmas no curso "BIO101 - Introdução a Biologia" ("BIO101 - Intro to Biology")

Este arquivo supõe que você tem várias turmas em um curso. Muitas instituições importam turmas de cursos como cursos separados. Isto pode ser feito ao (1) criar um curso do Canvas para cada turma no seu arquivo courses.csv, em seguida (2) criar uma única turma em cada um desses cursos. Você pode usar essencialmente os mesmos dados para o curso e turma, incluindo o SIS ID que será o mesmo para o course_id e section_id.

Campos Obrigatórios*

  • *section_id: Esse é um identificador único usado para criar turmas em um curso. Esse identificador não pode ser alterado para a turma e deve ser globalmente único. Na interface de usuário, esse é chamado SIS ID.
  • *course_id: Esse é um identificador único do curso onde as turmas serão adicionadas ou excluídas.
  • *name: Esse é o nome da turma. Turmas são ordenadas alfabeticamente pelo nome.
  • *status: É assim que você pode criar ou remover uma turma de um curso. Marque como "ativa" ("active") para criar uma turma ou "excluída" ("deleted") para remover uma turma existente.
  • start_date: Essa é a data de início da turma. O formato deve ser do ISO 8601: AAAA-MM-DDTHH:MM:SSZ ("T" pode ser substituído por um espaço). Por padrão, o acesso do usuário é cortado à meia-noite na data de término indicada, significando que o dia anterior é o último dia inteiro que os usuários têm acesso à turma. A melhor prática é definir a data de término para o dia após a conclusão da turma.
  • end_date: Essa é a data de finalização da turma. O formato deve ser do ISO 8601: AAAA-MM-DDTHH:MM:SSZ ("T" pode ser substituído por um espaço.)

enrollments.csv

Uma matrícula é um usuário que foi matriculado em um curso sob uma função específica. Um arquivo enrollment.csv permite que você atribua funções aos usuários e os coloque em cursos apropriados. Quando o status da matrícula de qualquer usuário for marcado como "concluído" (Completed), ele estará limitado ao acesso somente leitura para esse curso.

Baixe um arquivo enrollments.csv de exemplo com as seguintes matrículas:

  • 1 usuário como professor no curso "ACCT300 - Contabilidade de Custo" ("ACCT300 - Cost Accounting")
  • 1 usuário como professor assistente (ta) no curso "ACCT300 - Contabilidade de Custo" ("ACCT300 - Cost Accounting")
  • 1 usuário como autor no curso "ACCT300 - Contabilidade de Custo" ("ACCT300 - Cost Accounting")
  • 3 usuários como estudantes na seção 1 do curso "ACCT300 - Contabilidade de Custo" ("ACCT300 - Cost Accounting")
  • 3 usuários como estudantes na seção 2 do curso "ACCT300 - Contabilidade de Custo" ("ACCT300 - Cost Accounting")
  • 1 usuário como observador de um estudante na seção 1 do curso "ACCT300 - Contabilidade de Custo" ("ACCT300 - Cost Accounting")

Campos Obrigatórios*

  • *course_id: (Requerido se o campo section_id não for inserido) Esse é um identificador único para um curso onde o usuário será matriculado. Se estudantes são matriculados em um curso ao invés de matriculados em uma seção específica, coloque o course_id neste campo. Caso contrário, deixe em branco.
  • root_account: Esse é o domínio da conta para pesquisar pelo usuário.
  • *user_id: Esse é o identificador único do usuário que será matriculado nos cursos designados. (adicionado em users.csv).
  • *role: Essa é a função a que o usuário será designado para um curso. Você matricula um usuário para qualquer uma das funções a seguir: professor, autor, professor assistente (ta), aluno, observador ou função personalizada definida por você. Cada função tem um conjunto de permissões que Administradores podem personalizar na conta principal/raiz ou nível de subconta.
  • role_id: (Exigido se o campo função não for inserido) Esse é o identificador único para a funçãoem que o usuário será adicionado como parte de uma matrícula.
  • *section_id: (Requerido se o campo course_id não for inserido) Esse é um identificador único para uma turma em que o usuário será matriculado. Se usuários são matriculados em uma seção específica de um curso, coloque o campo section_id da seção aqui. Caso contrário, deixe em branco. Se nenhum section_id é especificado, o section_id padrão para o curso será usado. Se a turma padrão não for definida, uma turma será automaticamente criada sem um SIS ID.
  • *status: É assim que você matricula, conclui uma matrícula, desativa (torna inativa) ou remove uma matrícula em um curso. Marque como "ativa" (active) para matricular um usuário em um curso, "concluída" (completed) para concluir a matrícula de um usuário no curso, "inativo" (inactive) para desativar o usuário no curso, e "excluído" (deleted) para remover um usuário do curso. Quando estiver em um estado 'inativo' (inactive), um estudante será listado na chamada do curso para os instrutores, mas ele não poderá visualizar ou participar do curso até que sua matrícula seja ativada.
  • associated_user_id: (Apenas função Observador) Esse é um identificador único do usuário ao qual o observador terá acesso a ver informações (incluindo notas). O observador deve ser matriculado no mesmo curso/seção do usuário que você quer que seja observado. Esse campo será ignorado para qualquer outra função que não seja Observador.

groups.csv

Um grupo pode ser usado para fornecer oportunidades de colaboração para estudantes, instrutores, administradores ou outros usuários. Um groups.csv permite que você crie grupos de nível de conta. Grupos carregados através do SIS só podem ser atualizados ou excluídos através do SIS.

Baixe um arquivo de groups.csv de amostra com os seguintes grupos:

  • Administradores
  • Professores de Matemática
  • Designers

Campos Obrigatórios*

  • * group_id: Este é o identificador exclusivo usado para fazer referência a seu grupo. Ele não deve mudar para o grupo e deve ser exclusivo.
  • account_id: Este é o identificador que conecta o grupo a uma conta (adicionada em accounts.csv). Se nenhum for especificado, o grupo será conectado à conta raiz.
  • * name: Este é o nome do grupo.
  • * status: Este é o status do grupo. Marque como "disponível" ("available") para definir o grupo como aberto para a adesão ou "excluído" ("deleted") para excluir o grupo.

groups_membership.csv

Associação (Membership) é um grupo que permite usuários colaborarem em atividades no Canvas. O groups_membership.csv permite que você faça adição ou remoção em massa de pessoas a um grupo que você criou pelo groups.csv.

Download de uma amostra do arquivo groups_membership.csv com as seguintes associações de grupos:

  • 1 usuário aceito no grupo Administradores
  • 1 usuário aceito no grupo Professores de Matemática
  • 1 usuário excluído no grupo Professores de Matemática

Campos Obrigatórios*

  • * group_id: Este é o identificador único utilizado para referenciar seu grupo (adicionado no groups.csv).
  • * user_id: Este é o identificador único do usuário que você quer adicionar ao grupo.
  • * status: Este é o estado dos usuários no grupo. Marque como aceito (accepted) para adicionar um usuário ao grupo ou excluído (deleted) para remover um usuário de um grupo.

xlists.csv

Lista cruzada permite você mover turmas para outro curso. O arquivo xlist.csv permite que você faça listas cruzadas de turmas em cursos existentes e criar uma hierarquia de turmas.

É experado que existam ids de turmas e já referenciando outros ids de cursos. Se um id de turma é fornecido neste arquivo, ele será movido de seu id existente de curso para um novo id de curso, tal como se um novo curso é removido ou a lista cruzada removida, esta turma irá ser revertida para o id de curso anterior. Se o campo xlist_course_id não fizer referência a um curso existente, ele será criado. Se você deseja fornecer maiores informações sobre lista cruzada de curso, por favor faça em courses.csv.

Download de um arquivo de exemplo xlists.csv com os seguintes cursos e turmas:

  • 4 turmas ativas do curso ACCT300 - Contabilidade de Custo (ACCT300 - Cost Accounting) cruzado com o curso ACCT310 - Contabilidade Gerencial (ACCT310 - Managerial Accounting)

Campos Obrigatórios*

  • * xlist_course_id: Esse é o identificador do novo curso (adicionado em courses.csv).
  • * section_id: Esse é o identificador da turma (adicionado em sections.csv).
  • * status: Esse é o status da turma. Marque como ativo (active) para tornar a turma ativa ou excluído (deleted) para remover a turma.

user_observers.csv

A função de observador pode ser usada para matricular pais e conectá-los a um estudante, permitindo a eles visualizar as notas do estudante e interações do curso. O arquivo user_observers.csv permite que você matricule e conecte observadores a cada uma das matrículas dos estudantes designados.

Download de um arquivo de exemplo user_observers.csv com as seguintes matrículas:

  • 2 observadores ativos
  • 1 observador excluído

Campos Obrigatórios*

  • * observer_id: Esse é o identificador único do observador.
  • * student_id: Esse é o identificador único do estudante.
  • * status: Esse é o estado do observador. Marque como ativo (active) para matricular o observador para cada matrícula do estudante ou excluído (deleted) para remover todas as matrículas do observador.