Com o uso do Workiva Scripting e das APIs, você pode simplificar significativamente as operações e os fluxos de trabalho. Como em todos os projetos de script, seguindo as melhores práticas para o desenvolvimento de código e controle de versão, você terá um gerenciamento de projeto eficaz, continuidade e sucesso.
Abaixo você encontra algumas dicas e truques do Workiva Scripting para o desenvolvimento de projetos e fluxos de trabalho.
Workiva Scripting Editor
O Editor de Scripts do Workiva ajuda você a gerenciar códigos no Workiva, executar scripts, monitorar execuções em produção e solucionar problemas. Para desenvolvimento avançado, testes, verificação de código, depuração e controle de versão, utilize um ambiente de desenvolvimento dedicado.
Ambiente de desenvolvimento
Se você já tiver um ambiente de desenvolvimento empresarial e um sistema de controle de versão, recomendamos que o use para todo o desenvolvimento e testes de scripts.
Os principais componentes de um ambiente de desenvolvimento incluem um editor de código (exemplos populares incluem VSCode, PyCharm, Jupyter, etc.) e um sistema de controle de versão (exemplos populares incluem GitHub e GitLab). Para quem não é engenheiro ou prefere não trabalhar em uma interface de linha de comando, há ferramentas leves, como GitHub Desktop e SourceTree, que podem simplificar o trabalho em sistemas de controle de versão.
Se você não tiver um ambiente de desenvolvimento, considere a possibilidade de definir um. Enquanto isso, certifique-se de salvar como seus scripts (antes, durante e depois de quaisquer alterações/atualizações) e certifique-se de manter as versões de desenvolvimento/trabalho de seus scripts separadas das versões de produção para reduzir substituições acidentais.
Desenvolvimento de scripts
Durante o desenvolvimento e os testes de projetos de script, considere seguir as principais práticas de Python e de controle de versão:
Python
Siga PEP 8 - Guia de estilo para o código Python o máximo possível. A consistência do código é muito benéfica para a legibilidade, a capacidade de manutenção e a continuidade.
Para criar scripts Python robustos, confiáveis e dimensionáveis em nível de produção, certifique-se de que você se concentre nas áreas-chave, incluindo:
- Autenticação : Utilize uma autorização por API para solicitar tokens de acesso de curta duração para as APIs da Workiva. Conceda apenas os escopos necessários para a integração, proteja o ID e o segredo do cliente e nunca armazene credenciais nos registros de log. Para obter instruções, consulte Configuração da API do Workiva .
- Modularidade: Divida os scripts grandes em unidades menores, independentes e reutilizáveis (funções, classes, módulos/arquivos). Isso facilita a leitura, o teste, a depuração e a manutenção do script ao longo do tempo.
- Registros de log: Inclua registros de log úteis e estruturados para capturar eventos importantes, mudanças de status, avisos e erros. Nunca registre credenciais, tokens de acesso, entradas de tempo de execução ou outras informações confidenciais.
-
Tratamento de erros: Inclua lógica para o tratamento de erros a fim de tornar os scripts mais robustos, confiáveis e fáceis de usar, gerenciando graciosamente situações inesperadas em vez de travar.
Nota: Use o tratamento de erros para lidar com situações inesperadas. Não conte com isso para compensar ou mascarar as consequências no desempenho decorrentes de um projeto de script abaixo do ideal (por exemplo, se o seu script gerar um grande número de respostas
429: Too Many Requests , o projeto do seu script e o fluxo de trabalho devem ser refatorados para otimizar as chamadas de API; você não deve contar com o tratamento eficaz de um grande número de respostas 429 para que o script seja bem-sucedido). - Documentos: Explica o que o código faz e como usá-lo (tanto internamente, por meio de comentários e docstrings, quanto externamente, por meio de manuais do usuário (READMEs)), permitindo que outros desenvolvedores e você, no futuro, entendam e alterem o script de forma eficaz e eficiente.
- Controle de versão: Incorpore o controle de versão semântico em seus projetos de script para ajudar no controle de versão.
- Convenções de nomes: Use convenções de nomes claras para seus scripts (por exemplo:
customername_function_v1_3.py). - Teste e verifique a conformidade do código. Use os pacotes Python, como
ruffeflake8para realizar verificações de lint e formatação. Você também pode aproveitar as extensas ferramentas e extensões de complementos disponíveis para editores de código populares para obter manuais e assistência com formatação e linting de código. -
Assistência de código de IA: Há muitas ferramentas de código de IA gratuitas e pagas disponíveis que você pode utilizar para ajudar na depuração e na otimização.
Nota: Embora sejam úteis, os assistentes de código de IA não substituem o conhecimento e a experiência necessários para que você desenvolva scripts e automações avançados.
Controle de versão
- Tenha uma única fonte de verdade: Use seu sistema de controle de versão como repositório central e única fonte de verdade para seus projetos de script. Faça alterações com frequência para garantir que todo o trabalho de desenvolvimento e os testes mais recentes sejam capturados e armazenados de forma centralizada.
- Documente totalmente as alterações: Adicione o máximo possível de detalhes e informações de suporte em todos os commits e pull requests no seu sistema de controle de versão para documentar todas as alterações (quem fez a alteração, o que é a alteração, por que a alteração foi feita etc.).
Práticas recomendadas de fluxo de trabalho
Ao desenvolver, testar e implantar scripts, seguir as melhores práticas de fluxo de trabalho ajuda a maximizar o desempenho do script e a minimizar possíveis erros e problemas. Alguns dos principais pilares do fluxo de trabalho de desenvolvimento incluem:
- Realize o desenvolvimento inicial e os testes unitários em seu ambiente de desenvolvimento.
- Transfira o script para um espaço de trabalho de teste ou outra área controlada para a realização de testes de integração no Workiva. Utilize dados que não sejam de produção.
- Implemente o script no ambiente de produção somente após a conclusão dos testes.
Transferindo o código para a Workiva
Assim que o desenvolvimento e os testes forem concluídos, transfira o código para o Workiva. É possível atualizar as fontes manualmente no Editor de Scripts, mas recomendamos enfaticamente que você automatize a implantação a partir do seu sistema de controle de versão usando a API de Scripts da Workiva. A implantação automatizada economiza tempo, reduz erros manuais e ajuda a manter o Workiva sincronizado com sua fonte controlada por versões.
A implantação automatizada de código-fonte requer uma autorização de API com o escopo ` script:write `. Se a implantação também recuperar ou verificar fontes, será necessário o script ` script:read` . Envie X-Version: 2026-01-01 em todas as solicitações de API. Para obter instruções sobre a concessão, consulte Configuração da API do Workiva . Para conhecer as operações compatíveis, consulte o guia da API de scripts do : .
Executando e monitorando scripts
Os scripts podem ser acionados diretamente do Scripting Editor, das Cadeias, das APIs de script ou das Automações integradas. Independentemente de como os scripts são acionados, recomendamos que você use o Scripting Editor para monitorar execuções e solucionar problemas.
Registrando
O Editor de Scripts inclui uma seção intitulada “ ” (Logs) . Recomendamos enfaticamente que seus scripts utilizem um registro detalhado e estruturado para registrar operações importantes, mudanças de status, avisos e erros. Um bom registro de log é essencial para monitorar o desempenho, solucionar problemas e compreender o comportamento dos scripts.
O pacote padrão de registro de log do Python, , pode incluir informações úteis, como carimbos de data e hora, níveis de log e mensagens. Utilize níveis apropriados, como DEBUG , INFO , WARNING e ERROR , para controlar a quantidade de informações geradas. Não registre credenciais, tokens de acesso, entradas de tempo de execução ou outras informações confidenciais.
Muitos usuários avançados também incluem a função de enviar os logs para uma planilha Workiva designada no mesmo espaço de trabalho|workspace. Isso permite que você acesse os registros com mais facilidade, faça análises mais rápidas e consultas eficientes. Aqui você encontra um exemplo de saída de log para uma planilha da Workiva (as IDs da planilha e da folha foram ofuscadas):
Depuração e adição de novos recursos
Se ocorrer algum problema durante as operações do script, recomendamos que você execute a depuração e a atualização no ambiente de desenvolvimento, não no ambiente de produção. Depois que essas correções/atualizações forem concluídas, testadas e confirmadas no sistema de controle de versão, você poderá enviar com segurança o script atualizado de volta para a Workiva.
Esse mesmo fluxo de trabalho deve ser usado ao adicionar novos recursos a scripts existentes: realize todas as atualizações e testes em seu ambiente de desenvolvimento. Quando todas as atualizações de script estiverem concluídas, testadas com sucesso e confirmadas no sistema de controle de versão, você poderá enviar o script atualizado para a Workiva.