Módulo de Scripting

O Módulo de Scripting integra motores Octave e Python, permitindo aos utilizadores escrever e executar cálculos usando qualquer uma das linguagens no Requirements & Systems Portal. O módulo foi concebido para realizar cálculos complexos que não são possíveis através do ValiEngine padrão.

Se os utilizadores pretenderem manipular quaisquer outros objetos para além de Valis numéricos, terão de utilizar a API Python do Requirements & Systems Portal. Alguns exemplos de casos de utilização incluem:

• Criar um valor e adicioná-lo em massa a vários Blocks

• Efetuar edições em massa em identificadores de requisitos

• Executar simulações com Python

• Converter unidades de valores de potência para kW.

• Executar um comportamento de fluxo de trabalho personalizado com base em acionadores automatizados

Fluxo do Módulo de Scripting

Para utilizar o módulo, o utilizador cria um novo script, adiciona entradas/saídas, escreve código em .m ou .py e executa o código para obter o resultado pretendido.

Fluxo de trabalho do Módulo de Scripting.

Criar um Novo Script

Para criar um novo script, clique na opção "+ Script" (1) dentro dos módulos de scripting.

Irá surgir uma caixa de diálogo, permitindo-lhe introduzir o nome do script, selecionar o motor (Octave ou Python) e dispor de opções adicionais para o utilizador usar/reutilizar a partir dos modelos.

Opção Criar Novo Script

Depois de criado um novo script, os utilizadores podem também criar ficheiros adicionais de Texto, JSON e YAML para os seus scripts. Para adicionar um novo ficheiro, clique na opção “+Add file” (1), adicione um nome e selecione um tipo de ficheiro na caixa de diálogo. Isto adiciona um ficheiro ao script.

Para utilizar qualquer um dos ficheiros extra criados, os utilizadores têm de incluir as duas linhas de código seguintes no topo do ficheiro main.py:

import site
site.addsitedir('script_code/')

Após estas duas linhas, quaisquer ficheiros extra podem ser chamados utilizando a instrução padrão import.

Gestão de segredos:

Para não expor a utilização de credenciais necessárias ao usar scripts que se ligam quer à nossa API quer à de outras ferramentas, é possível definir variáveis secretas pessoais que podem ser chamadas durante a execução do script, sem risco de as expor a outros utilizadores na implementação, ao armazená-las em ficheiros de script.

Como e onde adicioná-los

Os segredos podem ser definidos no painel Settings, em User Secrets. Estes segredos podem ser reutilizados no script para iniciar sessão no Requirements & Systems Portal. Aqui está um pequeno vídeo para demonstrar como pode criar segredos de utilizador.

Como o nome indica, estes segredos são únicos para cada utilizador e apenas acessíveis por quem os definiu.

Como utilizar Segredos num script

Ao importar o nome do segredo a partir do módulo “.settings”, os utilizadores podem usar segredos para autenticação dentro dos scripts.

from .settings import USERNAME, PASSWORD  #case sensitive, use the same word used in the user secrets.

LOGIN_DATA = {
    'domain': 'API_URL',
    'username': USERNAME,
    'password': PASSWORD
}

Durante a execução, os scripts irão obter o valor destas variáveis a partir dos segredos definidos nas definições de utilizador de quem aciona o script, e dependem das permissões desse utilizador. Os scripts não devem conter quaisquer funções de saída destas variáveis, para não expor segredos de utilizador.

Os scripts de uso geral configurados para serem acionados por automações podem ser configurados com autenticação por um utilizador de nível Admin, que pode remover permissões de leitura a todos os outros utilizadores, mantendo assim o script oculto.

Sistema de fila

Com o sistema de fila, os utilizadores podem ter a certeza de que os seus scripts serão sempre executados, especialmente se automações predefinidas acionarem regularmente scripts de fluxo de trabalho personalizados. Para isso, aceda à secção “Runs”. Pode consultar todas as execuções de todos os scripts ou as execuções de um script específico.

Todas as execuções de scripts passarão agora a ser guardadas na implementação e podem ser consultadas por script ou para todos os scripts selecionando a opção “All scripting” no topo da árvore do Script Module.

Pode parar um script em execução clicando no botão “Stop” no menu pendente Actions.

Ação Stop para um script.

Gestão de Permissões

Os scripts têm as suas próprias permissões, que podem ser geridas diretamente no Módulo de Scripting ou no Project Module, em “Permissions”.

Executar scripts a partir de um dashboard

Os utilizadores também podem criar dashboards de interação personalizados com a utilização de botões “Run Script”. Estes são semelhantes aos botões Request anteriormente disponíveis, usados para acionar chamadas REST, mas podem ser configurados para executar um ou vários scripts com o premir de um botão.

Ao utilizar a API Python nos scripts chamados, podem ser configurados dashboards de interação personalizados nos quais elementos como caixas de texto padrão podem ser usados como campos de entrada e saída para um script, que depois também pode, direta e indiretamente, afetar outros elementos apresentados.

Para isso, vá ao Project Module e depois a “Dashboards”. Em seguida, entre no seu dashboard personalizado e clique no ícone Plus no canto inferior direito. Depois selecione a opção “Run script” no menu pendente “Actions”.

Isto cria um botão a partir do qual pode executar scripts que atualizam blocos específicos do seu dashboard.

Um caso de utilização interessante é aquele em que execuções de teste aprovadas e falhadas são contadas e apresentadas num bloco de texto no mesmo dashboard.

Script & Automações

As automações predefinidas podem acionar scripts. Por exemplo, um cálculo complexo pode ser configurado para ser executado automaticamente se as suas entradas definidas forem alteradas. Além disso, ao utilizar a API Python do Requirements & Systems Portal, também é possível programar comportamentos complexos à medida para criar fluxos de trabalho personalizados.

As automações não só acionam scripts, como também transmitem a informação sobre que objetos as acionaram, para que os scripts possam atuar diretamente sobre esses objetos. A informação do objeto fica disponível na variável de dicionário “kwargs”, sob a chave ‘triggered_objects', como no exemplo seguinte:

object_data = kwargs['triggered_objects'][0]

As automações também executam scripts se forem acionadas por utilizadores que não tenham permissões para visualizar esses scripts, permitindo assim a personalização de fluxos de trabalho e cálculos por utilizadores admin, ao mesmo tempo que limitam o acesso ao código subjacente, como modelos matemáticos e físicos proprietários.

Podem ser encontrados exemplos de scripts de fluxo de trabalho na pasta templates do repositório público valifn.

Imagens valifn personalizadas

Os utilizadores on-prem têm a funcionalidade adicional de personalizar a sua instância valifn para executar qualquer pacote Python que pretendam, desde que o hardware do servidor o suporte. Os utilizadores on-prem também terão a capacidade de gerir que imagem valifn deve ser usada no momento da execução do script.

Como mostrado, esta opção está disponível como um campo de texto nas General Settings de cada script individual.

Como criar uma imagem personalizada

Podem ser encontradas mais instruções sobre como configurar as suas próprias imagens valifn nas páginas de documentação do repositório público:

• Usage · valispace/valifn-octave Wiki (github.com)

• Usage · valispace/valifn-python Wiki (github.com)

Exemplos de Scripts Python

Podem ser encontrados exemplos de scripts utilizáveis tanto no projeto de exemplo Valicopter 5000 de uma implementação (novas implementações) como no repositório público Github do ValiFn.

Estes exemplos podem ser acionados manualmente ou por automações (exclusivamente em alguns casos) e podem ser usados tal como estão ou modificados pelos utilizadores para executar qualquer tipo de comportamento personalizado.

Muitos destes exemplos foram criados como demonstrações das possibilidades do módulo de scripting e das automações para criar fluxos de trabalho automatizados personalizados. Os utilizadores são encorajados a personalizar qualquer script existente de acordo com as suas necessidades e a partilhar quaisquer scripts de uso geral e melhorias no repositório público do ValiFn.

Aviso de Suspeita em Filhos (Automação)

Justificação

Este script é acionado por uma automação que deve ser configurada para ser acionada por uma alteração a um requisito existente, uma vez que o script atua sobre as propriedades do requisito editado. A ação atualmente definida é colocar uma discussão em cada um dos seus filhos (caso existam) com uma mensagem personalizada relativa ao estado de alteração do requisito pai.

Personalização Sugerida

Outras ações possíveis poderiam ser criar uma tarefa ou adicionar o requisito editado a uma revisão.

Ações Atuais

• Verifica se o requisito que acionou a automação predefinida tem filhos

• Se tiver filhos, publica uma discussão em cada requisito filho indicando que o pai foi atualizado.

• A discussão inclui a identidade do utilizador que editou o requisito, acionando assim a automação.

Nova Tarefa (Automação)

Justificação

Ao criar um novo Block, um potencial cliente exigiu que as tarefas fossem criadas automaticamente e atribuídas a um utilizador específico. Neste exemplo, uma automação predefinida acionada pela criação de um novo Block irá criar uma nova tarefa e atribuir-lhe um utilizador. Foi idealizado adicionar o objeto acionador como entrada, mas esse desenvolvimento não foi finalizado.

Personalização Sugerida

Utilize o kwargs['triggered_objects'][0] para extrair a informação do objeto que acionou a automatização e adicioná-la ao campo de entrada da tarefa.

Ações Atuais

• Publica uma nova tarefa atribuída a um utilizador especificado.

Estatísticas de Requisitos

Justificação

Um exemplo simples de como pode ser criado um contador mais personalizado com mais valores estatísticos do que os fornecidos nos blocos predefinidos disponíveis nos documentos Dashboards e Analysis. Pode ser executado manualmente ou configurado para ser executado a partir de uma automatização sempre que um requisito é criado, modificado ou eliminado.

Personalizações Sugeridas

1. Pegue na informação extraída sobre os requisitos e derive estatísticas mais complexas a partir dela, comparando-a com valores anteriormente atualizados. Cada valor pode indicar quanto aumentou/diminuiu, expresso em percentagem.

2. Compare estatísticas de implementação executando individualmente o script em cada projeto e adicionando uma instância especial que recolhe estatísticas de todos os projetos, apresentando-as num dashboard.

3. Defina um aviso personalizado para os administradores do projeto caso as estatísticas mostrem uma queda súbita no número de requisitos, sinalizando uma possível alteração drástica no projeto.

Ações Atuais

• Compila estatísticas gerais de requisitos para um único projeto na implementação.

• Atualiza Valis pré-criados com os resultados.

Geração de Especificações

Justificação

Um script de exemplo que demonstra o poder da API Python para criar relatórios totalmente automatizados. Embora o script principal também esteja disponível na página de documentação das integrações, esta versão em particular foi adaptada para ser executada a partir do módulo de scripting da implementação.

Pode ser acionado por uma automatização ou manualmente.

Personalizações Sugeridas

1. Crie um relatório completo adaptando o processo atual de obtenção de requisitos para extrair Blocos e outros objetos a preencher no relatório

2. Adicione outros campos personalizáveis, que podem ser obtidos a partir de blocos de texto personalizados de dashboard, a partir dos quais também pode ser acionado.

3. Altere o ficheiro de saída final para PDF em vez de um ficheiro Word editável.

Ações Atuais

• Recebe um ficheiro Word como modelo, de uma determinada implementação, e devolve, como saída, ficheiros gerados, tantos quantas as especificações, colocados na Gestão de Ficheiros da implementação (consulte Exportação de especificações com base em modelo Microsoft Word para mais detalhes).

Dashboard de Testes

Justificação

Os contadores do dashboard ainda não acompanharam o módulo de Testes, e ainda não existem contadores automatizados para testes. Este script foi desenvolvido como prova de conceito para um contador personalizado que ainda não foi implementado. Foi inicialmente concebido para ser executado através de acionamento manual a partir de um botão Executar Script num Dashboard.

Personalizações Sugeridas

1. Expanda as estatísticas de Testes que são publicadas de volta nos Dashboards.

2. Se uma execução de teste for bem-sucedida, publique o resultado numa tarefa ligada e altere o seu estado para “Concluído”.

Ações Atuais

• Devolve uma cadeia de texto, colocada em blocos de texto predefinidos do Dashboard, com estatísticas calculadas de execução de testes.

• Pode receber entrada de uma automatização ou ser acionado manualmente.