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.
Introdução
Este projeto contém todas as automações do Google Apps Script usadas no SEROB. O Google 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 para produzir um único grande arquivo JavaScript e o 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 do VS Code, só tome cuidado para não dar push em código defeituoso.
Ver também
Consulte a documentação do Google Apps Script para descobrir como usá-lo. Use o código do repositório como exemplo. Em particular, Sheet e Range são muito úteis.
Para adicionar a esta documentação, veja a documentação do Sphinx e principalmente a do myst-parser, que é o que nos permite escrevê-la em Markdown.
Problemas
O Google Apps Script tem muitas limitações no serviço, 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;
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.compara 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.
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.