# Documentação Técnica das Automações do SEROB ## História A SCNE antigamente usava o Excel para o armazenamento, triagem e execução de processos. No entanto, sofria problemas de sincronização na hora de executar macros em cima dos dados, que precisavam ser executadas manualmente e causavam atrasos de até 2 horas. Para resolver o problema, foi adotada a suíte do Google como substituto. A planilha foi recriada do zero baseada na versão em Excel. Para manter a familiaridade dos usuários com a ferrramenta, a aparência original foi em grande parte mantida, com pequenas melhorias no posicionamento das colunas. A nova planilha entrou em produção no final de maio de 2025. (introducao)= ## Introdução Este projeto contém todas as automações do Google Apps Script usadas no SEROB. O [Google Apps Script](https://developers.google.com/apps-script) é uma plataforma de JavaScript da Google feita para criar integrações e automações através de todas as aplicações do seu ecossistema, com ênfase em sua suíte office, como Google Docs e Google Sheets. O grande benefício em relação a macros do Excel é que, além de não serem programadas em Visual Basic, essas rotinas executam em nuvem. Não é necessário parar o trabalho para executá-las manualmente e nem ter que se lembrar de fazê-lo. A maioria delas executam após o expediente. O projeto utiliza o transpilador de [TypeScript](https://www.typescriptlang.org/) para produzir um único grande arquivo JavaScript e o [clasp](https://github.com/google/clasp) para transformá-lo em Apps Script e enviá-lo aos servidores da Google. Esse processo é automático e executa em cada commit no branch `master` do repositório via pipeline CD/CI (GitHub Actions). No entanto, você também pode ativá-lo manualmente da sua máquina local usando o script definido em `package.json` ou usando a [task](https://code.visualstudio.com/docs/debugtest/tasks) do VS Code, só tome cuidado para não dar _push_ em código defeituoso. :::{seealso} Consulte [a documentação do Google Apps Script](https://developers.google.com/apps-script/reference/) para descobrir como usá-lo. Use o código do repositório como exemplo. Em particular, [Sheet](https://developers.google.com/apps-script/reference/spreadsheet/sheet?hl=en) e [Range](https://developers.google.com/apps-script/reference/spreadsheet/range?hl=en) são muito úteis. Para adicionar a esta documentação, veja [a documentação do Sphinx](https://www.sphinx-doc.org/en/master/) e principalmente a do [myst-parser](https://myst-parser.readthedocs.io/en/latest/), que é o que nos permite escrevê-la em Markdown. ::: (problemas)= ## Problemas - O Google Apps Script tem muitas [limitações no serviço](https://developers.google.com/apps-script/guides/services/quotas), a mais relevante para nós sendo a de um máximo de _6 minutos_ de tempo de execução de um script, o que significa que é preciso escrever código rápido e eficiente; - A interação do Google Apps Script com a planilha é _muito_ lenta, tanto leitura quanto escritura. Nunca opere célula por célula e caso tenha que filtrar um grande conjunto de dados, use a [API do GraphViz](automacoesserob/sql.md); - Além de lenta, a interação também pode falhar por diversos motivos que fogem do controle do programador. Às vezes serviços falham por nenhum motivo. É recomendado evitar escrever macros que sejam executadas muito frequentemente, como 10 vezes por dia, especialmente pra processos onde confiabilidade é crucial. - De vez em quando, o Google exige reautenticar para continuar executando o código de maneira automática. Para consertar, escolha uma função inóqua do código e execute manualmente usando a interface gráfica, quando ele pedir autenticação, autorize tudo. Você deve estar usando a conta `manutencaoscne@gmail.com` para isso. ### APIs e conversão ao GCP Vincular um projeto do Apps Script a um Google Cloud Project (GCP) é irreversível. A única maneira de desfazer essa conexão é criando um novo projeto do Apps Script do zero e vinculando-o à sua planilha. Essa integração, embora ofereça recursos avançados como acesso a APIs internas, costuma ser excessiva e exige muita manutenção para o uso no SEROB. Além disso, as funcionalidades avançadas impõem as seguintes limitações: - **Publicação Limitada**: Para usar o Apps Script com o GCP, é obrigatório publicar a aplicação como um "teste" (é necessário um plano do Google Workspace para publicar um projeto como "interno"), o que impõe um limite de 100 usuários ao longo da vida útil do aplicativo. - **Manutenção Constante de Tokens**: Os tokens de acesso OAuth2 expiram toda semana. Isso significa que você precisa entrar no painel do GCP, gerar novas credenciais e distribuí-las aos seus usuários toda semana. Mesmo que esse processo seja automatizado, a manutenção continua sendo tediosa e de benefício questionável para a maioria das necessidades. **TL;DR**: É só bagunça e dor de cabeça, não migre pro GCP. Use o projeto padrão que vem com o Apps Script (igual na foto) e não mexa. ![gcp-convert.png](_static/gcp-convert.png) ## Rotinas ### Chaves Em novembro de 2025, a abordagem de "Chaveiro" foi removida em favor do setor "CHAVES", trocando a abordagem para "Manutenção Reativa". No entanto, é necessário ainda ser possível receber um processo como chaveiro. Para resolver isso, o formulário continuará colocando "Chaveiro" na abordagem. Uma rotina na função de `housekeeping` irá realizar a substituição automaticamente. ## Navegação :::{toctree} :maxdepth: 2 :glob: email.md sql.md consts.md actions.md :::