Introdução ao Workiva Scripting

O Workiva Scripting oferece um ambiente flexível e seguro para a execução de código Python na plataforma Workiva. Ao escrever scripts personalizados que executam automaticamente processos repetíveis, você pode criar eficiências em escala em vários relatórios, arquivos e espaços de trabalho. E à medida que mais tarefas passam a contar com o auxílio da IA, o Scripting oferece a essas tarefas uma base confiável e regulamentada sobre a qual se apoiar — combinando flexibilidade com o controle necessário para transformar a automação em resultados repetíveis nos quais você pode confiar.

A criação de scripts está incluída no Customize Workiva. Para usar o Scripting, seu espaço de trabalho deve ter a opção “Personalizar o Workiva/Scripting” ativada, e os usuários precisarão das funções de Scripting apropriadas e das permissões de arquivo necessárias.

Funções e permissões

As funções são uma configuração de todo o sistema na Workiva, o que significa que elas estabelecem um nível padrão de acesso para cada script em um espaço de trabalho. Há três funções do Workiva Scripting que podem ser atribuídas pelo administrador do espaço de trabalho.

Função	Nível de acesso
Script Runner	Pode executar scripts.
Visualizador de scripts	Permite que você visualize scripts.
Editor de scripts	Você pode visualizar, criar e editar scripts.

Para obter mais informações, consulte a página de suporte do sobre funções e permissões de script .

Como usar o Workiva Scripting

Uma vez ativado no seu espaço de trabalho, os scripts aparecerão na tela inicial junto com as outras planilhas, documentos e apresentações do seu site. Você pode criar um novo script ou selecionar um já existente na lista de arquivos.

O editor de scripts é onde você criará, editará e executará os scripts do seu site.

A coleção inclui:

Uma tela central na qual você comporá o script
Uma seção de saída na parte inferior, na qual você visualizará os resultados da execução do script
Uma barra de menu na parte superior, onde você salvará ou executará o script
Um painel de propriedades à direita para que você gerencie as propriedades do script e execute o histórico
Um painel de fontes no lado esquerdo

Uma vez criados, os scripts podem ser executados manual, programaticamente, por meio de cadeias ou de dentro de um Workiva File.

Para executar um script manualmente:

Clique em Run Script na barra de menu na parte superior da tela.
Clique em + Add Variable.
Digite os nomes e os valores das variáveis de ambiente a serem passadas como parâmetros.
Clique em Run Script.

Para executar um script programaticamente, use uma autorização de API com:

script: execute para iniciar o script.
script: acesse para consultar o status de execução, os registros ou a saída.

Envie uma solicitação HTTP POST para POST /scripts/{scriptId}/execution com o cabeçalho X-Version: 2026-01-01 . O corpo da solicitação é obrigatório. Defina as entradas de tempo de execução como propriedades JSON com valores de tipo string ou envie um objeto JSON vazio ( {} ) caso o script não exija entradas.

O endpoint retorna 202 Accepted com um operationLocation . Verifique essa URL até que a operação atinja o status “concluída” ( ), “concluída” ( ), “falha” ( ), “falha” ( ) ou “cancelada” ( ) ( ). O recursoUrl da operação identifica a execução do script resultante.

Os registros do script incluem a saída padrão, o erro padrão e os detalhes da execução.

Para obter mais informações, consulte a página “ ” do Workiva Developers e a visão geral da API de script .

Para executar um script por meio de cadeias:

Você precisará usar o conector Workiva Scripting. Antes de fazer isso, o administrador de segurança da organização deve habilitar o conector na tela Configurations (Configurações).

Consulte os artigos abaixo para saber mais:

Para executar um script dentro de um arquivo do Workiva, você precisará seguir as etapas abaixo:

No painel Automações de um documento, planilha ou apresentação, crie uma nova automação e escolha Execução manual como acionador.
Adicione uma ação Execute script, selecione o script que você deseja executar e, como opção, defina quais usuários ou funções estão autorizados a executá-lo.

Observação: Apenas os usuários especificados poderão visualizar e executar a automação contida no arquivo.

Saiba mais sobre Executar scripts com automações.

Criar um script de prática

Antes de criar scripts ativos em seu site, recomendamos que você crie um script de prática no editor de scripts. Isso ajudará você a se familiarizar com o processo antes de lidar com dados em tempo real.

Siga estas etapas para criar um script simples que calcula o valor do dinheiro no tempo:

Em Home, clique em + Create => Script.
No lado direito, digite um nome e uma breve descrição para o script.
Vá para o editor de script no meio da tela e exclua qualquer código existente. Você deve ter uma tela em branco.

Você pode colar este código no editor:

"import os, sys # https://www.investopedia.com/terms/t/timevalueofmoney.asp # Fórmula do valor do dinheiro ao longo do tempo # FV = PV x [1 + (i / n)]^(n x t) # Suponha que uma quantia de $10.000 seja investida por um ano a juros de 10%, compostos anualmente. # O valor futuro desse dinheiro é: # FV = $10.000 x [1 + (10% / 1)] ^ (1 x 1) = $11.000 períodos_de_capitalização = {"anual" : 1, "mensal" : 12, "trimestral" : 4, "diário" : 365} se 'INVESTIMENTO' não estiver em os.environ: print("Não é possível executar o script.") Investment is missing.") sys.exit() if 'INTEREST_RATE' not in os.environ: print("Não é possível executar o script. A taxa de juros está faltando.") sys.exit() if 'COMPOUNDING_PERIOD' not in os.environ: print("Não é possível executar o script. O período de capitalização está faltando.") sys.exit() if 'YEARS' not in os.environ: print("Não é possível executar o script. O número de anos está faltando.") sys.exit() compounding_period = os.getenv('COMPOUNDING_PERIOD') if compounding_period not in compounding_periods.keys(): print("Não é possível executar o script.", compounding_period," não é um período válido") sys.exit() investment = int(os.getenv('INVESTMENT')) interest_rate = float(os.getenv('INTEREST_RATE')) years = int(os.getenv('YEARS')) n = compounding_periods[compounding_period] FV = investment * pow((1 + ((interest_rate/100) / n)),n * years) print("Assume-se que uma soma de",investment, "é investida por",years, "ano(s) a",\ interest_rate,"% de juros compostos em",compounding_period, "base. ") print("O valor futuro desse dinheiro é:") print(FV)

Clique em Run Script no canto superior esquerdo.
Clique em +Add Variable e digite os parâmetros que você deseja usar.
Clique em Run Script para concluir.

Os resultados do script agora podem ser visualizados no painel Output, na parte inferior da tela.

Como obter suporte com o Workiva Scripting

Você pode entrar em contato com Workiva Support para tirar dúvidas sobre o Workiva Scripting. O Suporte da Workiva pode ajudar com o comportamento da plataforma de scripts, mas não pode escrever nem depurar código Python personalizado.

Você também pode explorar a seção “ ” sobre scripts do Workiva na Central de Suporte para saber mais — incluindo noções básicas sobre scripts, criação e gerenciamento de scripts, exemplos, solução de problemas e melhores práticas.

Esses recursos ajudarão você a começar a usar o Workiva Scripting. Para obter mais ajuda, acesse a Comunidade de APIs da Workiva em ou a Comunidade de Scripts da Workiva em .

Perguntas frequentes

Como os scripts são comumente usados?

O Workiva Scripting pode automatizar muitas tarefas repetitivas e demoradas que, de outra forma, seriam realizadas manualmente. Alguns casos de uso comuns incluem supressão de linha zero, layouts de relatórios e a aplicação de formatação personalizada a vários documentos.

De maneira mais ampla, os scripts podem ser adaptados às necessidades específicas da sua empresa — permitindo que você personalize e dimensione os fluxos de trabalho de acordo com a forma como sua organização opera, com uma execução controlada na qual você pode confiar. O código é seu; o que você faz com ele depende muito do desenvolvedor do script, da configuração do espaço de trabalho e do número atual de processos manuais em sua empresa. E à medida que mais tarefas passam a contar com o auxílio da IA, o Scripting oferece a essas tarefas uma base confiável e repetível sobre a qual agir.

Existem limites para a criação de scripts?

Sim, a Workiva impõe uma série de limites tanto para o Workiva Scripting quanto para a API de script.

Saiba mais sobre os limites de script do Workiva no .

Como aciono scripts de cadeias?

Para isso, você precisa do conector Workiva Scripting.

Consulte os artigos abaixo para saber mais:

O Workiva Scripting está em conformidade com o FedRAMP?

Sim. Os scripts são executados em uma infraestrutura gerenciada pela Workiva e em conformidade com o FedRAMP, com as mesmas permissões de plataforma e controles de governança que o restante do conteúdo da Workiva.

Como posso proteger o acesso aos scripts?

Há várias maneiras de você proteger seu código contra o acesso de usuários não autorizados:

Crie um espaço de trabalho ou uma organização dedicada para usuários autorizados: Criar um espaço de trabalho, ou mesmo uma organização inteira, somente para usuários autorizados é a opção mais segura. Por exemplo, os parceiros podem criar um espaço de trabalho para o Workiva Scripting em sua organização e fazer com que os clientes executem scripts de sua própria organização.
Use as funções : As funções de script do Workiva — Editor de Scripts, Visualizador de Scripts e Executor de Scripts — são organizadas em níveis, de modo que os usuários possam acessar apenas os scripts necessários para seu trabalho. A função “Script Runner” permite que os usuários executem scripts sem precisar visualizar o código.
Permissões de uso: Os arquivos de script podem ser restritos no nível do arquivo para que somente usuários específicos possam editar ou visualizar o código.

Saiba mais sobre as funções e permissões de script do Workiva no site .

Você tem uma lista de IPs permitidos para a criação de scripts?

Sim, os IPs permitidos para o programa de script estão incluídos aqui.

Você tem uma biblioteca de scripts disponível?

Sim. Reunimos vários scripts de amostra para você usar. Você também pode criar o seu próprio script usando os artigos com instruções na seção “ : Criar e gerenciar scripts” do Centro de Suporte.

Como faço para gerenciar versões de scripts?

No momento, a Workiva armazena apenas a versão mais recente de um script.

Você pode criar cópias dos seus arquivos de script no Workiva e organizá-las em pastas, mas recomendamos o uso de um sistema de controle de versão separado — especialmente se você tiver um sistema de controle de versão corporativo; consulte Workiva Scripting: Melhores práticas do processo de desenvolvimento .

Como sincronizar o código da Workiva com um sistema de controle de versão corporativo (por exemplo, GitHub)?

A API de script da Workiva do oferece pontos de conexão de gerenciamento de código-fonte para recuperar e atualizar arquivos-fonte de scripts. Para recuperar fontes, é necessário o script :read ; para criar, atualizar, enviar ou sincronizar fontes, é necessário o script :write . O Workiva não sincroniza automaticamente os scripts com sistemas externos de controle de versão, como o GitHub, o GitLab ou o SVN.

Para obter instruções sobre como criar ou atualizar uma autorização de API, consulte Configuração da API da Workiva .

Como faço para acessar as credenciais dos sistemas Workiva e não Workiva a partir de um script?

Há duas maneiras de acessar as credenciais dos sistemas Workiva e não Workiva:

Enviar credenciais como entradas de tempo de execução (preferencial)
Codifique as credenciais no código

Por que os valores das entradas de tempo de execução do script não são exibidos na saída do log durante a execução?

Essa é uma precaução de segurança. Como os parâmetros de entrada podem conter dados confidenciais, nós os removemos dos logs voltados para o usuário.

Como posso armazenar dados temporários durante a execução de scripts?

Os scripts do Workiva podem usar a função `Open` do Python ( ) para ler e gravar arquivos temporariamente na pasta /tmp . Outros caminhos são restritos.

Toda vez que um script é executado, um contêiner é criado na infraestrutura de nuvem da Workiva. Esse contêiner tem o Linux instalado, e todos os caminhos estão restritos, exceto , /tmp e (que está vazio). Os dados podem ser gravados e lidos temporariamente nesse caminho. Quando a execução termina, o contêiner é descartado.

Posso definir variáveis globais para usar em vários scripts, à la Chains?

No momento, não. No entanto, se o seu script for executado como parte de um fluxo de trabalho do Chains, você pode usar variáveis do Chains e passar seus valores para o script como entradas em tempo de execução.

Posso enviar arquivos como parâmetros?

Os binários podem ser enviados como parâmetros, desde que não excedam 128 KB e sejam codificados como texto (ou seja, binary to text encoding).

Posso acessar o ID da organização, o ID do espaço de trabalho e a região nos meus scripts?

Sim, o ID da organização, o ID do espaço de trabalho e a região (EUA, APAC, CA, UE) estão disponíveis para o seu script por meio de variáveis de ambiente. Por exemplo, os.getenv("WORKIVA_ORGANIZATION_ID").

Variável	Descrição
WORKIVA_ORGANIZATION_ID	O ID exclusivo da organização Workiva na qual o script está hospedado.
WORKIVA_ACCOUNT_ID	O ID exclusivo do espaço de trabalho do Workiva onde o script está hospedado.
DOMÍNIO DO CLUSTER DA WORKIVA	A região da Workiva (EUA, APAC, Canadá ou UE) do ambiente de produção onde o script está hospedado.
WORKIVA_SCRIPTING_SCRIPT_ID	O ID exclusivo do script de Scripting que está sendo executado.
WORKIVA_SCRIPTING_RUN_ID	O ID exclusivo da execução atual do script.
WORKIVA_SCRIPTING_MEMORY_LIMIT	A quantidade máxima de RAM disponível para o script durante uma única execução.
WORKIVA_SCRIPTING_DISK_LIMIT	O espaço máximo em disco que o script pode utilizar no diretório `/tmp durante uma única execução.`

Posso usar o código de um script da Workiva em outro script da Workiva?

Não é possível importar ou chamar diretamente um script do Workiva a partir de outro. No caso de um pequeno trecho de código reutilizável, você pode copiá-lo e colá-lo em cada script que precisar dele.

Para códigos que você reutiliza em vários scripts, uma abordagem melhor é agrupá-los como uma dependência compartilhada. Você pode criar um pacote em dependencies.zip que inclua suas bibliotecas compartilhadas — e até mesmo o código cliente gerado a partir da especificação da API pública da Workiva — e, em seguida, enviar esse mesmo pacote para cada script que precisar dele. Isso permite que você mantenha o código comum em um único lugar e o reutilize em vários scripts, em vez de copiá-lo para cada um deles.

Para obter instruções sobre como criar e enviar dependências, consulte Bibliotecas de scripts e dependências compatíveis .

Centro de suporte da Workiva