# Importação via CSVBOX

Com o intuito de facilitar o dia a dia do time de serviços, foi criado uma integração com uma ferramenta terceira chamada "*csv.io*". O csvbox é um widget de importação de CSV drop-in para permitir que seus usuários carreguem planilhas, mapeiem colunas e validem dados com apenas alguns cliques.

Abaixo estarão descritos todos os processos que são necessários para que seja realizada a importação de registros para o TOTVS CRM. Importante ressaltar que todo o processo é feito diretamente na ferramenta csvbox, não necessitando nenhuma configuração no TOTVS CRM.

## **Conceitos Chaves**
Aqui estão alguns termos que são utilizados durante este documento para uma melhor compreensão:
**Usuário:** Qualquer pessoa que utiliza o aplicativo
**Arquivo:** Arquivo de planilha que os usuários enviarão para o aplicativo
**Planilha:** Refere-se ao modal de dados que especifica a estrutura dos dados que deseja aceitar. Pode-ser adicionar colunas à planilha e configurar critérios de validação por meio do aplicativo csvbox.
**Importar:** Todo o processo em que o usuário utiliza o importador csvbox para selecionar arquivos, fazer o mapeamento de colunas, validação de dados e envio do arquivo para o TOTVS CRM.

## **Importante**
* **Esta funcionalidade é exclusiva para os times internos TOTVS CRM, os clientes não terão acesso.**
* Somente é valido fazer upload dos seguintes formatos de arquivo:
* .csv
* .xlsx
* .xls

---
### **Primeiros passos**

#### Criação de conta no csvbox
1. Acessar o site: https://csvbox.io/;
2. Clicar no botão "*Start for Free*", localizado na parte central da tela;
3. Inserir os dados solicitados e clicar no botão "*Sign up*". Ou se preferir pode realizar o cadastro utilizando o seu e-mail corporativo, clicando no botão "*Sign up with Google*";
#
#### Aba "*Home*"

Na pagina inicial do do csvbox, haverá 3 cards com as seguintes informações:

1. No primeiro card haverá a informação de quantos modelos de planilha foram iseridos na sua conta;
* Apresentará a seguinte mensagem:
* "*You have added X sheets specifying import data format*";
* Abaixo da mensagem citada haverá um botão chamado "*Manage Sheets*". Este botão redireciona para a tela de inserção e configuração de planilhas que será explicado posteriormente neste documento;

2. No segundo card será apresentado as informações de quantas importações já foram utilizadas e quando o plano será ressetado;
* Caso o número de importações não seja superior a 100 por mês, pode-se trabalhar somente com a licença free sem maiores problemas;

3. No terceiro card será apresentada as informações de importações ao longo do tempo, com isso pode-se selecionar um período específico para visualizar as importações feitas;
#
#### Aba "*Sheets*"
Pode-se acessar a pagina de "*Sheets*" tanto pela tela inicial no botão "*Manage Sheets*" ou clicanco na aba "*Sheets*" na parte superior da tela;

1. Ao acessar a pagina de "*Sheets*" para adição de arquivos, clicar no botão "*Add*"
2. Inserir novo nome para a planilha e clicar em "*Next*";

##### A partir deste momento, na tela há algumas subabas: Columns, Destination, Display, Options e Code que serão explicadas uma a uma logo abaixo

1. **Columns**
Para a inserção de uma nova coluna ao arquivo que será importado clicar em "*Add Columns*";

* **Adicionar nome da coluna (Collumn Name) - Obrigatório;**
* **Adicionar rótulo de exibição (Display label) - Opcional;**
* *Os rótulos de exibição serão mostrados na linha de cabeçalho que o usuário verá ao fazer uma importação. Cada rótulo de exibição mapeia internamente para um nome de coluna. Embora o rótulo de exibição seja visto pelos usuários dentro do widget de importação, o nome da coluna correspondente será enviado ao destino como o nome do campo. Se o rótulo de exibição não for especificado, o nome da coluna será mostrado aos usuários por padrão. Isso ajuda você a exibir um rótulo amigável para os usuários enquanto envia um nome de coluna que seu aplicativo entende. Por exemplo, 'p_id' pode ser o nome da coluna e 'ID do produto' pode ser o rótulo de exibição.*
* **Adicionar dica de informação (Info Hints) - Opcional;**
* *São dicas de ferramentas de ajuda que serão exibidas quando os usuários passarem o mouse sobre o Nome da Coluna (ou clicarem nele) no importador. Eles são úteis para transmitir informações adicionais sobre a Coluna.*
* **Adicionar palavras-chaves correspondentes (Matching Keywords) - Opcional;**
* *Pode ser fornecido um conjunto de palavras-chave como opções alternativas de correspondência para ajudar os usuários a corresponderem os nomes das colunas automaticamente. Por exemplo, digamos que você tenha um nome de coluna 'First Name'. Se você acha que muitos de seus usuários podem ter planilhas com colunas como 'F_Name' ou simplesmente 'First', você pode adicionar duas palavras-chave correspondentes 'F_Name' e 'First'. O importador fará a correspondência automática das colunas com as palavras-chave especificadas para acelerar o mapeamento de colunas.*
* **Adicionar valor padrão (Default Value) - Opcional;**
* *Pode ser especificado um valor de preenchimento padrão para a coluna caso os dados de entrada estejam em branco.*
* **Adicionar tipo de coluna (Column Type) - Obrigatório;**
* *Essa opção ajuda você a especificar o tipo de dados dos dados recebidos e configurar as regras de validação relevantes. Você pode selecionar o tipo de coluna na lista suspensa e definir as condições de como os dados devem ser formatados. Se os dados recebidos não corresponderem ao tipo de coluna (e suas regras de validação), o usuário verá uma mensagem de erro relevante identificando qual é o problema e como corrigi-lo. Isso garante que os dados estejam limpos e prontos para uso antes de serem enviados ao seu aplicativo.Os valores disponíveis são: texto, número, e-mail, data, booleano, regex, ip, url, cartão_de_crédito, número_telefone, lista, lista_dependente, lista_dinâmica e lista_dinâmica_dependente.*
* **Adicionar comprimento mínimo e máximo (Min Length / Max Length) - Opcional;**
* *Quantidade mínima e máxima do campo.*
* **Adicionar obrigatoriedade (Required) - Se obrigatório marcar o check-box**;
* *Indica se uma coluna é obrigatória.*
#

2. **Destination**

Para configuração do destino, seguir os passos abaixo:
* **Send Data To** (para onde serão enviados os dados): API/Webhook
* **API/Webhook URL To Post Data** (para onde irão os dados):
* Será sempre POST;
* Será um endereço padrão para todos os tenants;
* A URL de destino pública deve seguir a tabela abaixo

| Ambiente | URL Publica |
| -------- | -------- |
| Homologação (HML3)|http://csvbox-gateway.satellite.homolog3.totvscrm.app|
|Homologação Gold (HMLGOLD)|http://csvbox-gateway.satellite.homgold.totvscrm.app|
|Produção (APP3) |http://csvbox-gateway.satellite.totvscrm.app|

* Haverá um botão abaixo do API/Webhook URL To Post Data, "*Add Custon Headers*" Ao clicar nele, será realizada a inserção de algumas informações:
* **Authorization** (Autorização):
* Bearer + token tenant (exemplo: Bearer MjFhYjUxZmYtYjY0ZS00ZmU2LWEwNGEtOTE2NTM5NWIyYmQ5LS1CcnVuYSBDaGFybm92c2tpLS1icnVuYS5yYWZhZWxhQHRvdHZzLmNvbS5ici0tdGVuYW50XXXXxxxx)
* **IMPORTANTE:** O token é correspondente ao usuário logado, com isso, se o token otido é de um usuário que não possui acesso, o processo de importação não ocorrerá.
* Esse token pode ser obtido temporariamente (haverá uma evolução para que esse token sea obtido de maneira diferente) dentro do CRM do cliente no módulo Markeplace -> DataHub

* **Integration-Action** (Ação da integração):
* Sempre será "*create*""
* **Integration-Service** (Serviço):
* Inserir o serviços que será usado, exemplo, product, customer e etc;
* **Integration-Resource** (API que ta sendo usada)
* As informações de APIs podem ser consultadas na [documentação das APIs de integração](https://gitlab.wssim.com.br/docs/api/-/tree/master/integration)
* **Integration-Version** (Versão da API):
* As informações de APIs podem ser consultadas na [documentação das APIs de integração](https://gitlab.wssim.com.br/docs/api/-/tree/master/integration)
* Exemplo

* **Post Data Format** (Formato de dados de postagem):
* Será sempre "*JSON*"
* **Rows To Post Per Chunk** (Linhas para postar por bloco):
* Sempre será "*1*"
* **Webhook URL for import complete event (optional)** (URL do webhook para evento completo de importação (opcional))
* Não necessita inserção dessa informação
* **Send a copy of data to client?** (Enviar uma cópia dos dados para o cliente?)
* Sempre "*não*"
* Exemplo

#
3. **Display**:

Essa tela só será utilizada caso queira fazer alguma personalização na tela do importador, ela não interfere no funcionamento da aplicação

#
4. **Options**:

Nessa tela, pode-se mudar a linguagem da ferramenta, bem como configurar para que não sejam aceitos dados inválidos e etc.

#
4. **Code**:

Nesta aba que efetivamente será utilizada para importação dos dados no TOTVS CRM. Pode-se acessar a tela de importação tanto pelo botão "*Test Importer*" quanto pela URL que está no final da tela.

* Selecionando para abrir a tela de importação, ela se apresentará da seguinte maneira:

* Com isso, o arquivo que será importado poderá ser arrastado para o centro da tela, ou clicando na imagem do centro da tela e uma nova tela com as informações do CSV aparecerá.

* Nesta nova tela, será selecionada a linha que corresponde a linha do cabeçalho.
* Após selecionar a linha do cabeçalho clicar em "*next*";
* Nesta tela, será feito o mapeamento das colunas do csv com a configuração de colunas que foi feita anteriormente no csvbox;
* Após o mapeamento clicar em "*next*";
* Nesta tela, será possível fazer a conferência das informações, bem como, remover alguma linha, ou até mesmo adicionar uma nova linha.
* Importante: Caso houver alguma célula com uma informação inconsistente o campo terá um destaque em vermelho, conforme imagem abaixo.
* Após a conferência clicar em "*next*";

Caso o seu arquivo não seja importado corretamente, aparecerá a tela abaixo:
#
## Aba "*Imports*"
Para consultar o log do problema que ocorreu, deve-se acessar a aba "*Imports*" localizado na parte superior da tela e clicar no item que apresentou erro na coluna "*Rows*", conforme imagem:

Após clicar, será apresentado na tela o erro que ocorreu ao importar o csv:

Caso o seu arquivo seja importado corretamente, aparecerá a tela abaixo

Após este processo, pode-se acessar o CRM para verificar a importação: