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 em uma única máquina local, 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 a porção de código Google Apps Script usadas em conjunto com a planilha. O Google Apps Script é uma plataforma 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. A linguagem é extremamente parecida com Javascript, o que permite o reuso do robusto ecossistema da linguagem no desenvolvimento. 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.

 GitHub -> Container (GH Actions) -> Typescript (este repositório) -> Arquivo Javascript -> clasp -> Servidores da Google

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

Esta seção serve como um alerta a qualquer programador posterior ao autor que seja encarregado de dar manutenção ao projeto de erros cometidos e projetos abortados durante o desenvolvimento da iteração atual do fluxo de trabalho do SCNE.

  • 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 aparente. É 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

É possível que um programador novo ao projeto queira tentar obter acesso às APIs do Google para poder criar aplicações e wrappers que possam auxiliar e integrar com a planilha e seus processos. Isso não é recomendado devido a experiências negativas obtidas durante tentativas anteriores.

Para obter acesso às APIs, é preciso ter um plano pago do Google Cloud, o acesso gratuito não atende os propósitos. Além disso, vincular um projeto do Apps Script a um Google Cloud Project (GCP) é irreversível. A única maneira de desfazer essa conexão é criar um novo projeto do Apps Script do zero e o revincular a 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, ou seja, remover um usuário não reduz a contagem.

  • Manutenção Constante de Tokens: No modo teste, 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 extremamente tediosa e propensa a erros, potencialmente causando interrupções aos serviços do SEROB.

TL;DR: É bagunçado e gera muita dor de cabeça para pouco benefício. Não migre para o GCP. Use o projeto padrão que vem com o Apps Script (igual na foto) e não mexa nele.

gcp-convert.png

WebApps via Apps Script

Já foram criadas aplicações web servindo HTML+CSS+JS com o Google Apps Script para criar um front-end amigável ao usuário que auxilie no preenchimento da planilha. No entanto, foi constatado que a integração com o Apps Script, ou seja, as funções “ponte” que ligam o Javascript do navegador do cliente ao Apps Script nos servidores da Google eram extremamente lentas na leitura e na escritura, causando problemas no preenchimento de vários processos por dia.

Isso, aliado às restrições impostas pela Google a o que pode ser feito nas porções estáticas do HTML e Javascript significam que não é um bom caminho a ser seguido. É possível que hajam usos melhores dessa funcionalidade, ou que os problemas de lentidão possam ser contornados de alguma outra maneira, então não é necessário descartar a ideia inteiramente.

Rotinas

Chaves

Atenção

Esta seção foi colocada aqui por praticidade. É importante encontrar um lugar mais apropriado para não deixar o índice enorme.

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.