Os GroundRunners permitem que os comandos em cadeia interajam com sistemas locais ou fontes de dados remotas não acessíveis de outra forma pela Internet. Normalmente, eles são instalados em um servidor dedicado, como o que hospeda a fonte de dados conectada, por um profissional de TI ou alguém familiarizado com as configurações de rede da sua organização.
Antes de configurar um GroundRunner, recomendamos que você consulte a arquitetura de segurança do Chain Builder .
Requisitos
É necessário um sistema operacional compatível e, se o seu GroundRunner acessar recursos compartilhados, como um caminho UNC (Windows Universal Naming Convention), também será necessária uma conta de usuário com privilégios suficientes.
Se você estiver usando o GroundRunner, o JRE não será instalado com o GroundRunner durante a instalação inicial do GroundRunner.
Depois que a configuração for concluída e o GroundRunner estiver em execução, ele baixará automaticamente um JRE, conforme necessário, para executar comandos que dependem do Java. Não é necessária nenhuma instalação ou intervenção do administrador, e o JRE recuperado não afetará as instalações de JRE existentes, se elas existirem no host.
Como alternativa, se você tiver requisitos organizacionais que exijam o uso de um JRE específico, a variável de ambiente SHARED_LIBRARY_OVERRIDES poderá ser definida para apontar para a instalação do sistema. Nesse caso, o GroundRunner não fará o download automático do JRE padrão da Workiva e usará o JRE instalado no sistema provedor.
Os JREs fornecidos pela Workiva são licenciados sob a GPL v2 e são cobertos pela exceção de classpath .
Nota: Para usar certificados personalizados com o Java instalado, consulte Usando certificados personalizados com o GroundRunners.
Requisitos da função
Na plataforma Workiva
Na plataforma Workiva, você precisa de uma função que conceda acesso às configurações do Chain Builder e à capacidade de gerenciar Runners. Existem dois:
- Proprietário da cadeia: Essa é a principal função necessária. Os usuários com essa função podem acessar a seção "Downloads" no Chain Builder para recuperar os arquivos de instalação mais recentes do GroundRunner e gerenciar a guia "Runners" para ativar ou monitorar o serviço.
- Administrador de segurança da cadeia organizacional: Essa função de nível organizacional também tem autoridade para gerenciar conexões e corredores em vários espaços de trabalho.
No servidor
Como uma "atualização manual" envolve a interrupção de serviços e a substituição de arquivos executáveis na máquina física ou virtual onde o GroundRunner está instalado, o usuário deve ter privilégios administrativos no servidor host.
- Windows: Você deve ter a capacidade de executar o prompt de comando como administrador e acessar o Windows Service Manager (para parar e reiniciar o serviço GroundRunner).
- Linux/macOS: Você deve ter acesso sudo ou root para mover arquivos para o diretório de instalação e reiniciar o processo em segundo plano.
Faça o download do GroundRunner
Para fazer o download de um GroundRunner para instalação ou atualização manual, você deve procurar o GroundRunner do seu sistema operacional e clicar em Download no lado direito:
- Na barra lateral da página inicial da Workiva, clique em Cadeias.
- Na barra lateral do Construtor de Cadeias (essa é uma nova guia), clique em Conexões.
Como alternativa, você pode clicar no ícone do perfil do usuário no canto superior direito, selecionar Chains admin e, em seguida, Workplace Settings. - Clique em Downloads na barra de menu superior.
- Localize o GroundRunner para o seu sistema operacional e clique em Download para obtê-lo.
- Depois de fazer o download com sucesso para o seu computador, selecione as instruções apropriadas do conjunto abaixo e siga-as para instalar o GroundRunner.
Instale o GroundRunner
O Microsoft Installer (MSI) requer o .NET 3.5 ou superior.
Se não for possível atender a esse requisito, você terá que instalar o GroundRunner usando a interface de linha de comando.
Para instalar o GroundRunner:
- Descompacte o arquivo GroundRunner.zip em uma nova pasta e abra-a. Se você estiver na América do Norte, digite h.app.wdesk.com/s/chains-reaper.
- Execute GroundRunner.msi para abrir o assistente de configuração do GroundRunner.
- Clique em “Próximo”.
- Revise e aceite os termos do contrato de licença e clique em Next.
- Em Destination Folder (Pasta de destino), digite o caminho onde o GroundRunner será instalado (por exemplo:
C:\Program Files\GroundRunner\) e clique em Next.
- No token da empresa da plataforma , digite o token da empresa .
- Em Platform auth host:
- Para a APAC, digite
h.apac.wdesk.com/s/chains-reaper. - Para o Canadá, digite
h.ca.wdesk.com/s/chains-reaper. - Para EMEA, digite
h.eu.wdesk.com/s/chains-reaper. - Para os Estados Unidos, a América Central e a América do Sul, digite
h.app.wdesk.com/s/chains-reaper.
- Para a APAC, digite
- Se estiver usando um servidor proxy, digite seu URL e porta em Proxy host.
(Por exemplo,http://yourproxy:3000.)
Para ignorar o servidor proxy, insira uma lista de hosts separados por vírgula em No proxy host. - Clique em Next, Install e Finish.
- Depois de instalado, clique com o botão direito do mouse no GroundRunner no Windows Service Manager e selecione Start.
Seu GroundRunner foi instalado e está pronto para ser ativado.
Para instalar por meio da interface de linha de comando, você deve fazer o download da instalação do GroundRunner em seu próprio diretório nos arquivos de programa (por exemplo, c:\Program Files (x86)\wdata). Em seguida, você pode descompactar o arquivo de instalação e extraí-lo para a raiz desse diretório.
Em seguida, você pode instalar o GroundRunner:
- Na janela de comando do Windows, digite
e aceite todos os padrões.c:\Program Files (x86)\wdata\installer.exe install- Selecione "windows" para o sistema de inicialização.
Você precisa especificar que o GroundRunner deve operar como um serviço do Windows para que ele seja compatível com as atualizações automáticas. O GroundRunners só deve ser executado como um serviço, exceto para fins de teste.
- Para o caminho, crie uma pasta Files dentro do novo diretório
(por exemplo,C:\Program Files (x86)\Wdata\Files). - Para o nome do host de autorização (AUTH_HOST):
- Para a APAC, digite
h.apac.wdesk.com/s/chains-reaper. - Para o Canadá, digite
h.ca.wdesk.com/s/chains-reaper. - Para EMEA, digite
h.eu.wdesk.com/s/chains-reaper. - Para os Estados Unidos, a América Central e a América do Sul, digite
h.app.wdesk.com/s/chains-reaper.
- Para a APAC, digite
- Digite seu token de empresa .
- Selecione "windows" para o sistema de inicialização.
- Exclua todos os arquivos do diretório, exceto o diretório executável do GroundRunner.
- Selecione se você deseja executar o GroundRunner como um serviço ou como um processo em primeiro plano.
- Se você estiver executando como um serviço, execute uma das seguintes ações:
- Na caixa de diálogo de comando, digite
sc start GroundRunner. - No Windows Service Manager, inicie o serviço GroundRunner.
- Na caixa de diálogo de comando, digite
- Se estiver sendo executado como um processo em primeiro plano, na caixa de diálogo de comando, digite:
cd c:\Program Files (x86)\wdata GroundRunner.exe
- Se você estiver executando como um serviço, execute uma das seguintes ações:
Seu GroundRunner agora está instalado e pronto para ser ativado.
Etapa 1. Instalar o GroundRunner
-
Faça o download do arquivo de instalação do GroundRunner em seu próprio diretório,
, por exemplo:/home/nome_do_usuário/wdata/.Observação: "/home/user_name/wdata" é fornecido como exemplo. Siga a política de sua organização para locais de instalação de serviços.
- Em uma caixa de diálogo de comando, descompacte o arquivo de instalação usando:
unzip GroundRunner.zip - Insira os detalhes do GroundRunner.
- Digite
./installer install - Para o nome do host de autorização (AUTH_HOST):
- Para a APAC, digite
h.apac.wdesk.com/s/chains-reaper. - Para o Canadá, digite
h.ca.wdesk.com/s/chains-reaper. - Para EMEA, digite
h.eu.wdesk.com/s/chains-reaper. - Para os Estados Unidos, a América Central e a América do Sul, digite
h.app.wdesk.com/s/chains-reaper.
- Para a APAC, digite
- Digite seu token de empresa .
- Digite
- Exclua todos os arquivos do diretório, exceto a pasta que foi criada durante o processo de instalação.
Etapa 2. Configure o GroundRunner como um serviço systemd (Linux)
Para garantir que as atualizações automáticas do GroundRunner funcionem e para uma boa higiene do GroundRunner, o GroundRunner precisa ser instalado como um serviço systemd habilitado e reiniciável. Consulte a documentação do seu sistema operacional e a política da organização para saber como executar o GroundRunner como um serviço systemd.
Para configurações básicas, temos os seguintes requisitos de arquivo de unidade do systemd para que as atualizações automáticas funcionem corretamente:
- Certifique-se de que o executável
ExecStartaponte para o binárioGroundRunnerMonitore NÃO para o binário
GroundRunner. - Defina
Restart=always. - Não defina
StartLimitBurstouStartLimitIntervalSec, pois isso pode impedir que o GroundRunner reinicie devido a erros transitórios. Se quiser que o GroundRunner não entre em um loop de reinicialização rápida, você pode configurarRestartSec. - Digite
systemctl enablepara ativar a unidade de serviço do Systemd GroundRunner para que o GroundRunner sobreviva a uma reinicialização.
A Workiva não oferece suporte oficial à execução de um GroundRunner como um processo em primeiro plano. Isso pode ser útil para testar uma configuração, mas, depois que um GroundRunner for configurado, ele deverá ser definido como um processo em segundo plano de longa duração.
Operação do GroundRunners no macOS (somente teste)
A Workiva oferece suporte ao GroundRunners no macOS apenas para fins de teste. Embora os GroundRunners do macOS sejam capazes de executar os mesmos comandos que as versões do Linux e do Windows, a Workiva não oferece suporte oficial ao launchd como um gerenciador de serviços válido. Isso se deve ao fato de a Apple ter descontinuado o suporte ao software de servidor macOS em 2022. Os laptops e computadores de mesa da Apple não são adequados para a execução do GroundRunners.
Ativar o GroundRunner
Depois de instalar o GroundRunner, você deve ativá-lo no Chain Builder.
- Na barra lateral do Construtor de Cadeias, clique em Conexões.
- Clique em Runners na parte superior e, em seguida, clique em Pending Registration.
- Digite um nome curto e descritivo para o corredor.
Por exemplo, "<datasource>-GroundRunner".
- Clique em Ativar.
Atualização manual de um GroundRunner
Embora isso raramente seja necessário, você pode precisar atualizar manualmente um GroundRunner.
Consulte a página de suporte da Workiva GroundRunner Manual update para obter instruções sobre como fazer isso.
Desinstalar um GroundRunner
Se você não precisar mais de um GroundRunner, poderá desinstalá-lo.
- Interromper o serviço do GroundRunner
- Se ele estiver sendo executado como um serviço, use o Windows Service Manager ou digite
sc stop GroundRunnerem uma janela de comando. - Se ele estiver sendo executado como um processo em primeiro plano, pressione Ctrl+C.
- Se ele estiver sendo executado como um serviço, use o Windows Service Manager ou digite
- Na caixa de diálogo de comando, como administrador, digite
installer.exe uninstall. - Exclua o diretório executável
GroundRunner.
Na caixa de diálogo de comando, interrompa o serviço GroundRunner e exclua seu diretório executável (por exemplo, /home/<username>/wdata/Contents).
Instalando um JRE personalizado
Se necessário, você pode instalar seu próprio JRE para dar suporte a um GroundRunner. A versão Java desse JRE deve corresponder à necessária para o Groundrunner. Com exceção dos GroundRunners Oracle Essbase e Oracle Hyperion Financial Management (HFM), todos os GroundRunners usam a mesma versão do JRE. Para obter informações sobre como instalar um JRE personalizado, consulte Desativar as bibliotecas compartilhadas da Workiva.
Definições de configuração do GroundRunner e domínios de saída
Para permitir a comunicação com a fonte de dados, talvez você precise abrir as portas do firewall no servidor em que o GroundRunner está instalado. Para alterar as definições de configuração de alguns GroundRunners, você pode editar o arquivo GroundRunner.config no diretório em que os binários estão instalados.
| Configuração | Configurações |
|---|---|
| Porto |
0 a 65535. Por padrão, os GroundRunners usam a porta 8821 para se comunicarem uns com os outros. No entanto, uma porta é necessária somente se os GroundRunners em servidores diferentes compartilharem saídas de comando dentro da sua rede. |
| COMPANY_TOKEN | Deixe como padrão, a menos que o GroundRunner esteja configurado para um locatário diferente. |
| LOG_LEVEL | Informações ou debug |
| PROTOCOLO | Deixar como padrão. |
| HTTP_PROXY_URL |
Se você estiver usando um servidor proxy, digite o URL e a porta (se necessário). Observação: Os GroundRunners podem usar servidores proxy, mas não aqueles autenticados por meio do New Technology LAN Manager (NTLM). Em vez disso, permita o endereço IP do servidor. |
| LONG_POLL | Se você estiver usando um servidor proxy, defina como true para instruir o executor a usar o long-polling para recuperar comandos. Para garantir o desempenho, use o rastreamento longo somente se os soquetes da Web não forem compatíveis com o seu servidor proxy ou firewall. |
| NO_PROXY | Para ignorar o servidor proxy, forneça uma lista separada por vírgulas de hosts a serem acessados diretamente. Para incluir vários hosts com base em um padrão comum, use o curinga *. |
| GROUNDRUNNER_CERT |
Necessário se você estiver usando mais de um GroundRunner e quiser enviar informações criptografadas para o segundo GroundRunner. Isso deve ser usado em conjunto com PORT. Você também deve especificar o campo PROTOCOL como HTTPS ao ativar o executor. |
| GROUNDRUNNER_CERT_KEY | Necessário se você estiver usando mais de um GroundRunner e quiser receber informações criptografadas de um segundo GroundRunner. Também deve ser usado em conjunto com PORT. |
| DESATIVAR_WEBSOCKETS | Os websockets são necessários para executar as transformações. Quando desativado, todos os comandos que usam transformações serão totalmente ignorados. |
Observação: Seu certificado autoassinado deve ter um Nome Alternativo de Assunto (SAN). Caso contrário, quando o GroundRunner tentar fazer o download de arquivos, ele mostrará uma mensagem de erro fazendo referência à SAN ausente.
Se a sua rede deve permitir domínios de saída, isso se aplica aos GroundRunners:
| Domínio | Finalidade |
|---|---|
|
|
Os principais subdomínios dos serviços comuns da Workiva, incluindo o Wdata. |
*.wdesk.com |
O domínio principal da plataforma de produção da Workiva. |
*.*.wdesk.com |
Os subdomínios dos componentes de suporte na plataforma Workiva. |
Segurança
Os GroundRunners nunca coletam ou agregam dados; eles retêm dados somente durante a transmissão. Um certificado de validação estendida (EV) sempre criptografa e protege o tráfego entre um GroundRunner e sua fonte de dados por meio da DigiCert®.
Observação: Para proteger os dados no local, os CloudRunners podem compartilhar a saída com os GroundRunners, mas os GroundRunners não podem compartilhar saídas de arquivos com o CloudRunner.
Solução de problemas de erros do GroundRunner
Se você receber esses erros quando uma cadeia for executada, verifique os GroundRunners do comando.
Dica: Para facilitar a solução de problemas, você pode criar uma cadeia para fazer o download automático de um arquivo de registro do GroundRunner para uma tabela.
| Mensagem de erro | Causa | Resolução |
|---|---|---|
| Falha ao se comunicar com o agente - este comando não foi executado |
O comando não pôde se comunicar com seu GroundRunner. Se isso acontecer, o GroundRunner não foi iniciado ou ocorreu uma interrupção de rede entre o GroundRunner e o Chain Builder. |
Verificar
|
| Não foi possível fazer o download dos recursos associados ao comando. Entre em contato com o Suporte se o erro persistir. |
Os executores associados a esses comandos da cadeia não podem se comunicar uns com os outros. Isso geralmente ocorre quando os comandos usam executores diferentes e o CloudRunner está tentando usar uma saída de arquivo de um comando baseado no GroundRunner. |
Use o mesmo executor com todos os comandos da cadeia. Se os comandos da cadeia exigirem vários executores, verifique se nenhum comando com GroundRunners passa as saídas de arquivo para comandos que usam o CloudRunner. |
Erro ao iniciar o comando: exec: \"\\[connector].exe\": o arquivo não existe" commandExecutorId=[ID] |
Um aplicativo de malware ou antivírus identificou incorretamente o conector e interceptou sua comunicação com o GroundRunner. | Exclua o diretório de instalação do GroundRunner das verificações do aplicativo. |
| Erros de certificado | Como usar certificados autoassinados |
Em muitos casos, será conveniente usar certificados autoassinados para criptografar a comunicação do GroundRunner. Se você estiver usando um certificado autoassinado, certifique-se de que o Common Name do certificado corresponda ao URL no qual o servidor pode ser acessado. Por exemplo, se o seu GroundRunner estiver escutando na porta 8821 e você puder acessar o servidor da sua rede |
| Falha intermitente na cadeia com erro: "Connection reset by peer" |
Quando vários executores são instalados na mesma máquina, cada um deve ter um GUID exclusivo. Se o mesmo GUID for usado, os executores poderão se sobrepor e entrar em um loop de atualização, causando falhas ocasionais na cadeia. |
Recomendamos que você faça uma reinstalação completa do GroundRunner. |
| Os comandos são ignorados no GroundRunner, mas são bem-sucedidos no CloudRunner | Os websockets são necessários para executar as transformações. Quando os websockets estiverem desativados, todas as transformações serão totalmente ignoradas. | Abra seu arquivo de configuração e definaDISABLE_WEBSOCKETS=false. |
Erro ao ler do soquete. Tentando novamente/repetir a conexão: read tcp <IP>:<Port>-><IP>:<Port>: wsarecv: Uma tentativa de conexão falhou porque a parte conectada não respondeu adequadamente após um tempo, ou a conexão estabelecida falhou porque o host conectado não respondeu. |
Problema de firewall interno ou de rede | Peça à sua equipe interna de TI ou de rede para revisar os logs e a configuração a fim de resolver o erro. |
read <IP>:<Port>-><IP>:<Port>: wsarecv: Uma conexão existente foi fechada à força pelo host remoto |
Problema de firewall interno ou de rede | Peça à sua equipe interna de TI ou de rede para revisar os logs e a configuração a fim de resolver o erro. |