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 Workiva Scripting Editor foi criado para ajudar você a integrar o código de produção à Workiva, monitorar as execuções de produção e solucionar problemas iniciais quando surgirem problemas. Não é nem um editor de código abrangente, e não temos planos de transformá-lo em um.
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: Criar, gerenciar e regenerar de forma eficaz o token de portador apropriado garante que somente usuários ou sistemas autorizados possam acessar os recursos, os dados ou a funcionalidade do espaço de trabalho|workspace.
- 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.
- Registro em log: Inclua um registro detalhado para capturar eventos chave e mensagens de status, o que é vital para monitorar o desempenho e solucionar problemas.
-
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 dependa dele para compensar ou mascarar as consequências de desempenho de um design de script abaixo do ideal (por exemplo, se o seu script gerar um grande número de respostas 429/Too Many Requests, o design e o fluxo de trabalho do seu script devem ser refatorados para otimizar as chamadas de API, você não deve depender do tratamento eficaz de um grande número de 429s para o sucesso do script).
- 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:
- Realizar todo o desenvolvimento e os testes do script no ambiente de desenvolvimento , e não no ambiente de produção.
- Transfira o script para um espaço de trabalho|workspace onde você possa testar o script na Workiva.
IMPORTADO: Use dados de não-produção de para que você possa testar. - Somente implemente o script no espaço de trabalho|workspace de produção para uso operacional depois que ele tiver sido testado com sucesso.
Transferindo o código para a Workiva
Quando o desenvolvimento e os testes principais estiverem concluídos e tudo funcionar conforme o esperado, você poderá transferir seu código para a Workiva. Embora você possa enviar alterações manualmente para a Workiva a partir do Workiva Scripting Editor, é altamente recomendável que você automatize o envio do código do sistema de controle de versão para a Workiva usando as APIs de script. Esse é o processo recomendado, pois a automação economiza tempo e reduz erros.
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 Scripting Editor inclui uma seção "Logs"; recomendamos que seus scripts incorporem o registro detalhado para fornecer informações detalhadas e abrangentes sobre as operações do script. Essas informações geralmente são muito úteis para depuração, monitoramento e compreensão das operações do script. O pacote padrão Python logging é um exemplo de utilitário de registro que pode ser definido para fornecer informações úteis sobre as operações do script (por exemplo: carimbo de data/hora, nível de registro, mensagem etc.). Certifique-se de utilizar os vários níveis de registro (INFO, DEBUG, ERROR, etc.) e incluir mensagens de registro detalhadas e úteis.
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.