Sumário

Versionamento    3

1.    Objetivo    4

2.    Dependências    4

3.    Preparação do Ambiente e Backup    4

Download de Release, Backup e Licenciamento    4

Limpeza de Instalação Anterior    5

4.    Os Módulos do S-Works    7

5.    Instalando Módulos Web Applications    8

Alteração no Nome do Módulo WCF Service para Web Api    9

Web App e Web Api em Ambientes Clusterizados    11

6.    Módulos de Serviços Executáveis    13

Instalando os módulos como Windows Services    13

Configurando os módulos de Windows Services    15

Módulo S-Works – Agent    16

Módulo Orquestrador (Producer/Consumer)    17

Orquestrador com Processamento Local    17

Orquestrador com Processamento Distribuído (Producer/Consumer)    18

Instalando o RabbitMQ    18

Instalando/Configurando o Módulo Producer    20

Instalando/Configurando o Módulo Consumer/Worker    22

Módulo Ações em Lote    23

Ações em Lote com Processamento Local    23

Instalando/Configurando o Módulo Ações em Lote Producer    24

Instalando/Configurando o Módulo Ações em Lote Consumer    25

Módulo Distribuidor de Atividades (Activity Dispatcher)    26

Configuração Pós Instalação do Distribuidor de Atividades (Activity Dispatcher)    27

Módulo Auxiliares (Sentinela/Expurgo/Expiração Atividades Manuais)    28

Módulo Service Discovery    28

Instalação do Módulo Service Discovery    29

Configuração do ’Target File’ do Módulo Service Discovery    29

Diagrama de Comunicação do Service Discovery    30

7.    Arquivos de Configuração    32

Configuração da String de Conexão    33

Configurações de Logs    33

Logs em Ambientes Clusterizados    34

Configuração de Log no Orquestrador (Consumer/Worker)    34

Configurações de Monitoramento e Observability    34

Configurações do Prometheus    36

Configuração do Appender para Graylog    37

8.    O Instalador do S-Works    39

Anexo I - Checklist Pós Deploy    41

Objetivo    41

Módulo Web App    41

Módulo Web Api    41

Módulo Distribuidor de Atividades (Activity Dispatcher)    42

Módulo Orquestrador (Producer)    43

Módulo Orquestrador (Worker)    43

Módulo Orquestrador – Processamento Local    44

Orientações Gerais    44

Ambientes com Integração Externa (Função)    45

Versionamento

Versão

Data

Comentários

1.0

23/09/2020

Versão inicial do documento.

Atualização  do  manual  para  conter  etapas  de  instalação

2.0

20/01/2021

manual do sistema e seus módulos, assim como configuração

dos mesmos.

2.1

21/01/2021

Revisão, inclusão de informações nos módulos e adicionando

ANEXO I.

2.2

13/04/2021

Adicionando módulo “Service Discovery” e detalhamento de

configurações de observability.

2.3

20/05/2021

Substituição da ferramenta MSMQ pelo RabbitMQ.

2.4

20/08/2021

Adicionando  nova  forma  de  instalação  dos  módulos,

desacoplados do ChassSVC.

2.5

26/08/2021

Adicionando informações sobre módulo Agent.

2.6

28/01/2022

Adicionando módulos Ações em Lote (Producer e Consumer)

1. Objetivo

Este documento tem como objetivo detalhar o processo de instalação e atualização do S-Works na versão 2.2 ou superior, em ambiente de homologação ou produção. Inicialmente, vamos tratar a instalação e configuração manual do sistema, e ao final do documento trataremos a utilização do instalador como forma de atualização

2. Dependências

A versão 2.0 do S-Works representa a migração do sistema do NET Framework 4.7.2 para o NET Core, portanto, é necessário realizar o download e instalação das seguintes dependências nos servidores de aplicação:

1. Case esteja instalado versões entre 2.0 e 2.3, instale o .NET Core Runtime Hosting

Bundle 3.1 mais recente: https://dotnet.microsoft.com/en-us/download/dotnet/3.1

2. Para versão 2.4+, instale o .NET Core Runtime Hosting Bundle 5.0 mais recente: https://dotnet.microsoft.com/en-us/download/dotnet/5.0

3. Em caso de ambientes clusterizados, certifique-se que os demais servidores utilizados nos módulos também tenham o runtime .NET Core 3.1 ou 5.0 mais recente instalado.

3. Preparação do Ambiente e Backup

Download de Release, Backup e Licenciamento

1. Caso a instalação esteja sendo feita em ambiente de produção, verifique se existe backup do banco de dados atualizado.

3. Caso o último backup do banco de dados seja muito antigo, e existam “migrations” na versão sendo instalada, considere abortar a instalação.
4. Realize o download do pacote de instalação do S-Works para dentro do servidor.

4. As releases geradas para o S-Works geralmente se encontra na pasta “Releases” dentro de cada pasta de versão atual do sistema, no servidor de build, por exemplo: \\172.16.1.62\Build\SWorks\VersaoAtual\S-Works_v2.0\Releases

2. Faça Backup da pasta da aplicação atual, principalmente para preservarmos a pasta chamada LicenseKeys, que contém as chaves de licenciamento do cliente.
3. Essa pasta precisa estar localizada no diretório do ChassiSVC contendo o serviço do orquestrador (OrquestradorSVC) ou o serviço de enfileiramento de processos (Producer/MQDispatcher).

1. Caso seja uma nova instalação, solicite à infraestrutura a geração de uma nova chave de licenciamento para o ambiente/cliente.

Limpeza de Instalação Anterior

Por se tratar de uma instalação em um novo framework .NET, é necessário realizar a limpeza e desinstalação dos módulos de versões anteriores à versão 2.0 que estejam instaladas.

1. Limpe todas as pastas dos módulos do sistema do ambiente a ser atualizado, ou seja, as pastas SWorks.WebApp, SWorks.SVC, SWorks.WCFService devem estar vazias.

2. Atenção para as ConnectionStrings que vão estar nos web.config, copiar as credenciais para aplicar nos novos arquivos de configuração dos módulos do SWorks.

3. Atenção também para os caminhos de “Logs” nos arquivos “log.config”.

Preserve estes caminhos para manter a localização existente.

4. Renomeie a antiga pasta (Sworks.WCFService) para (Sworks.WebApi) ficando assim:

5. Desinstale os Windows Services atuais (ChassiSVC). Podem ser desinstalados mais facilmente usando "sc delete <NomeService>".

4. Os Módulos do S-Works

A partir da versão 2.3, cada módulo do S-Works agora é um executável independente. Os módulos em azul escuro são módulos Web, instaláveis no IIS, e os demais, em azul claro, são módulos que devem (quando necessário) ser instalados como Windows Service.

Web App

•Módulo que contém a aplicação web.

Web Api

•Módulo que contém a API REST para integrações.

Orquestrador Producer

•Módulo responsável por enfileirar processos na fila.

Orquestrador Consumer/Worker

•Módulo responsável por consumir e processar a fila de processos.

Orquestrador

•Módulo responsável por realizar o processamento de processos em memória.

Activity Dispatcher/Distribuidor de Atividades

•Módulo responsável por distribuir atividades manuais para o módulo Web App.

Ações em Lote

•Módulo responsável por processar as ações em lote criadas no Web App.

Ações em Lote Producer / Consumer

•Módulos de processamento distribuído de ações em lote.

Service Discovery

•Módulo responsável por receber e manter registros dos módulos em execução.

Expurgo de Dados

•Módulo responsável por processar o expurgo de dados no sistema.

Sentinela

•Módulo responsável por monitorar inconsistências na execução de processos.

Expiração de Atividades Manuais

•Módulo responsável por desassociar atividades manuais por tempo de atribuição.

Integração Externa

•Módulo responsável por processar a fila de integrações externas (Função).

Integração Externa Web Api

•Módulo responsável por distribuir itens da fila de integração externa para processamento.

5. Instalando Módulos Web Applications

Os módulos Web App, Web Api e Integração Externa Web Api são módulos Web, ou seja, instalados através do IIS, ou Kestrel (em caso de instalação em Linux, não coberta por esse manual).

As aplicações web em .NET Core já possuem um servidor interno chamado “Kestrel”, e,

portanto, o IIS funcionará apenas como proxy para receber as requisições e direcioná-las para a aplicação.

1. Acesse o IIS e configure/modifique o ApplicationPool, acessando nas configurações básicas a opção "Versão do .NET CLR" e selecione "Sem código gerenciado" ou "No Managed Code".

2. Se for a primeira instalação, copiar os arquivos manualmente do pacote de instalação para as suas respectivas pastas dos módulos do ambiente que está sendo atualizado.

Aplicações Web em NET Core exigem a configuração de um application pool para cada aplicação, portanto, não é possível compartilhar um mesmo application pool para duas ou mais aplicações.

Alteração no Nome do Módulo WCF Service para Web Api

Até a versão 1.42 do sistema, o módulo de integração era chamado “Sworks.WCFService” pelo fato de conter um serviço WCF respondendo em protoloco SOAP.

Esse protocolo não é mais suportado na versão 2.0 ou superior, contendo apenas a API REST para comunicação via HTTP.

Devido a isso, devemos renomear a aplicação instalada no IIS para “Sworks.WebApi”.

1. Acesse o IIS e remova a antiga aplicação SWorks.WCFService:

Crie uma nova pasta chamada “SWorks.WebApi” no diretório da aplicação e atualize o IIS para que a pasta seja exibida:

2. Clique com o botao direito sobre a pasta e selecione a opção “Convert to Application” e depois confirme a alteração clicando em OK.

3. Conforme dito anteriormente, aplicação web em NET Core não podem compartilhar um mesmo application pool, portanto vamos criar um novo application pool para o módulo “WebApi”.

4. Clique com o botão direito sobre “Application Pools” e depois em “Add

Application Pool.

5. Coloque o nome “SWorks.WebApi” para o novo application pool, e selecione

“No    Managed    Code”    na    opção    “.NET    CLR    version”.

6. Clique com o botão direito sobre a aplicação “SWorks.WebApi”, depois em “Manage Application” e “Advanced Settings”.

7. Altere  o  application  pool  vinculado  para  o  criado  anteriormente.

Web App e Web Api em Ambientes Clusterizados

Os módulos Web App e Web Api podem ser implantados de forma clusterizada, ou seja, atrás de um balanceador de carga para fins de escalabilidade das aplicações.

Quando implantados de forma clusterizada, faz-se necessária a configuração de um diretório compartilhado para armazenamento das chaves de proteção de dados.

Anteriormente, aplicações Net Framework utilizavam uma chave chamada

“MachineKey”, configurada pelo IIS, como objeto para criptografia de

dados, como cookies de sessão por ex.. Devido à portabilidade do NET

Core, um novo mecanismo de proteção de dados foi implementado.

Utilizamos o mecanismo via file system para armazenar tais chaves.

Para configurar o caminho para armazenamento das chaves de proteção de dados, siga as instruções abaixo:

1. Abra o arquivo “appsettings.json” e procure pela configuração “KeyPath” dentro de “DataProtectionProvider”.

2. Essa propriedade indica o caminho onde as chaves utilizadas para proteção de dados da aplicação serão mantidas.

3. Em um servidor 24/7, por exemplo o AlwaysOn, crie e compartilhe uma pasta para cada módulo, por exemplo, “C:\Sworks\Sworks.WebApp.Keys” e “C:\Sworks\Sworks.WebApi.Keys”.

4. Certifique-se que o usuário do application pool das aplicações possui acesso de leitura e escrita nesses caminhos compartilhados.

5. Feito isso, configure o valor da propriedade “KeyPath” com o caminho da pasta compartilhada, conforme exemplo abaixo:

6. Repare que as barras invertidas precisam ser “escapadas”, portanto, são dobradas no JSON.

7. Após o término da instalação, e início da aplicação, verifique-se que o sistema criou um arquivo XML com prefixo “keys” nas pastas indicadas.

8. O sistema irá gerar o arquivo de forma automática se ele não existir, assim como fará a rotação de chaves a cada 90 dias.

6. Módulos de Serviços Executáveis

A partir da versão 2.3, alguns módulos do S-Works que eram embutidos em outros módulos (por exemplo, o módulo Sentinela era acoplado ao módulo Orquestrador), e os módulos que executavam sob a aplicação “ChassiSVC”, foram todos desacoplados, se tornando executáveis independentes.

Todos os módulos executáveis, que são Windows Services, se encontram na pasta “SWorks.SVC” do pacote de instalação.

Instalando os módulos como Windows Services

Todos estes módulos devem ser instalados na forma de Windows Service, utilizando a aplicação “sc” para criar/remover os serviços.

Abaixo seguem orientações genéricas de como instalar um módulo na forma de Windows Service, e mais abaixo serão detalhadas as configurações de cada módulo:

1. Inicie o prompt de comando como administrador, e digite o seguinte comando:

3. sc create <NOME_DO_MODULO> binPath="<CAMINHO_COMPLETO_MODULO.exe>"
4. Abaixo   um   exemplo   de   comando   para   instalação   do   módulo

“SWorks.Orquestrador”:

Após execução com sucesso da instalação, abra o menu de serviços executando o comando “services.msc”, clique com o botão direito sobre o serviço instalado e selecione a opção de propriedades.

1. Na primeira aba, em "Startup type" altere para "Automatic (Delayed Start)".

1. Na segunda aba "Log On", utilize as credenciais de Administrator local ou Administrator do Domain

1. -Na aba "Recovery", selecione "Restart the Service" nas 3 opções; First failure, Second failure e Subsequent failure.

Configurando os módulos de Windows Services

Anteriormente, as configurações da maioria dos módulos de Windows Services se encontravam num arquivo chamado “ChassiSVC.exe.config”. A partir da versão 2.3, com a separação dos módulos em executáveis independentes, cada módulo possui seu respectivo arquivo de configuração e de logs.

Cada módulo possui um par de arquivos de configuração, no seguinte padrão:

1. <Módulo.exe>.appsettings.json: arquivo de configuração do módulo, que conterá informações sobre configuração, string de conexão e configurações de coleta de métricas.

2. <Módulo.exe>.log.config: arquivo de configuração do log4net.

O antigo arquivo de configuração “ChassiSVC.exe.config” possuía uma tag de “services”, indicando quais módulos seriam executados naquela instância de serviço. Essas configurações agora existem dentro do arquivo

JSON de configuração, dentro da propriedade “ServiceConfigurations”,

contendo propriedades homônimas do antigo XML.

Módulo S-Works – Agent

Em alguns clientes que detém de infraestrutura mais limitada, criar um Windows Service para cada módulo do sistema pode gerar um overhead de memória que impacta a quantidade de recursos exigidos para executar os módulos.

Dessa forma, para manter a possibilidade de executar múltiplos módulos dentro de um mesmo executável, mas mantendo a correta compilação de dependências de projetos e referências (que não era possível usando o recurso ChassiSVC), criamos um módulo de gerenciamento de execução chamado “SWorks.Agent”.

Este módulo, que se encontra na pasta “SWorks.SVC”, é também um Windows Service e pode conter em suas configurações múltiplos módulos a serem executados, conforme print das suas configurações abaixo:

1. SentinelaEnabled: determina se o módulo sentinela será executado.

3. AtividadeManualExpiradaEnabled: determina se o módulo de expiração de atividades manuais será executado.
4. ExpurgoEnabled: determina se o módulo de expurgo será executado.

4. ServiceConfigurations[]: lista de configurações de serviços a serem executados pelo Agent.

Módulo Orquestrador (Producer/Consumer)

O módulo “Orquestrador”, responsável pela execução de processos no sistema, após a versão 2.3, foi dividido em 3 módulos executáveis:

1. SWorks.Orquestrador: módulo de processamento local do orquestrador, realizando enfileiramento e processamento multi-thread dos processos em memória e em instância única, sem distribuição de trabalho.

2. SWorks.Producer: módulo responsável pelo enfileiramento de processos no mecanismo de fila RabbitMQ.

3. SWorks.Consumer: também conhecido como “Worker”, este módulo é responsável por realizar o desenfileiramento dos processos da fila RabbitMQ, realizando o processamento multi-thread na instância local.

Orquestrador com Processamento Local

Método utilizado para ambientes de homologação ou clientes de baixa demanda (até aproximadamente 5 mil processos/mês).

Para utilizar essa forma de processamento, basta seguir a instrução de instalação de Windows Service para o executável do módulo, chamado “SWorks.Orquestrador.exe”. Conforme dito anteriormente, as configurações dos módulos agora se encontra no arquivo JSON “<MODULO”>.appsettings.json”. Segue abaixo um exemplo de configuração a ser realizado neste arquivo:

1. MaxCount: quantidade de threads de execução paralela de processos. O valor recomendado aqui é o resultado da quantidade de núcleos lógicos da instância multiplicado por 4. Números muito maiores do que isso podem acarretar em perda de performance no processamento.

Orquestrador com Processamento Distribuído (Producer/Consumer)

Método utilizado para clientes com grandes volumes de processamento, podendo ser configurado em ambiente auto escalável, ou máquinas ligadas 24/7.

Para a instalação do módulo Producer, é necessário instalar o serviço de enfileiramento do RabbitMQ, detalhado abaixo.

Instalando o RabbitMQ

Para instalar o módulo Producer é necessário a instalação do RabbitMQ:

1. Em um servidor “AlwaysOn” (servidor 24/7), acesse o site do RabbitMQ e faça o

download da ferramenta: https://www.rabbitmq.com/install-windows.html#installer

1. O RabbitMQ necessita que a linguagem Erlang esteja instalada na máquina. Caso o instalador do RabbitMQ identifique a falta dela, será solicitado a instalação, bem como o link para realizar o download.

2. Após instalação, será possivel identificar o RabbitMQ como serviço, já em execução:

3. Agora deve-se instalar um plugin chamado RabbitMQ Message Deduplication Plugin, realizando o download da release mais recente no seguinte endereço: https://github.com/noxdafox/rabbitmq-message-deduplication

1. Realize o download dos dois arquivos sinalizados na imagem, são eles: elixir-{version}.ez e rabbitmq-message-deduplication-{version}.ez

4. Mova os dois arquivos baixados para a pasta de plugins do RabbitMQ, que

normalmente    está    no    caminho:

“C:\Program    Files\RabbitMQ    Server\rabbitmq_server-{version}\plugins”

5. Abra o cmd como administrador e navegue até o diretório \sbin que situa-se dentro da pasta raiz de instalação do RabbitMQ, por exemplo:

“C:\Program Files\RabbitMQ Server\rabbitmq_server-3.8.16\sbin”

6. Execute  o  seguinte  comando  para  habilitar  o  plugin  adicionado:

“rabbitmq-plugins enable rabbitmq_message_deduplication”

7. Execute o seguinte comando no mesmo diretório para habilitar o plugin de

gerenciamentoviainterfacedoRabbitMQ:

“rabbitmq-plugins enable rabbitmq_management”

8. Após executar os comandos, reinicie o serviço do RabbitMQ e os plugins já estarão em uso e a configuração do RabbitMQ estará finalizada. Por padrão, é possivel acessar o painel de gerenciamento pelo seguinte endereço: http://localhost:15672

Insira “guest” para o usuário e a senha.

Instalando/Configurando o Módulo Producer

Após instalação e configuração do RabbitMQ, siga as orientações abaixo para configurar o com o módulo Producer:

1. No mesmo servidor “AlwaysOn” onde o RabbitMQ foi instaladado, crie um pasta chamada “Sworks.Producer” com o conteúdo da pasta “SWorks.SVC” contida no pacote de instalação.

2. Abra o arquivo “SWorks.Producer.appsettings.json” e realize a configuração do serviço através da propriedade “ServiceConfigurations” conforme abaixo:

1. User/Password: usuário e senha de acesso ao RabbitMQ. Por padrão, é definido a palavra “guest” para o usuário e senha do serviço. Contudo, é recomendável o acesso ao painel administrativo (http://localhost:15672) para definir um usuário

de    acesso    exclusivo.

2. Host: endereço da maquina onde o RabbitMQ está instalado. No caso do Producer, localhost.
3. Port: porta do serviço RabbitMQ, por padrão 5672.

3. QueueName: nome da fila do RabbitMQ. Esta fila será criada automaticamente.

1. MaxCount: indica a quantidade de itens a serem enfileirados no RabbitMQ. Esse valor pode ser aumentado caso a quantidade de workers disponíveis seja alta, visando aumentar a vazão de processamento.

2. WaitSecondsOnEnqueue: tempo, em segundos, a ser aguardado para cada turno de enfileiramento. Reduza esse tempo para enfileirar processos mais rapidamente sob o custo de maior consumo de CPU.

Instalando/Configurando o Módulo Consumer/Worker

O módulo Consumer/Worker também deve ser instalado na forma de Windows Service. Abaixo seguem as configurações necessárias para que esse módulo seja capaz de processar os itens da fila do RabbitMQ:

1. Em um servidor a ser utilizado exclusivamente como “Worker”, seja para construção de uma imagem em ambiente com autoscale ou em uma máquina ligada em horário integral, crie uma pasta chamada “SWorks.Worker” com o mesmo conteúdo da pasta “Sworks.SVC” presente no pacote de instalação.

2. Abra o arquivo “SWorks.Consumer.appsettings.json” e realize a configuração do serviço através da propriedade “ServiceConfigurations” conforme abaixo:

1. User/Password: usuário e senha definidos no painel de gerenciamento do

RabbitMQ. Por padrão, a palavra “guest” para o user/password.

2. Host: endereço da maquina onde o RabbitMQ está instalado.

3. Port: porta do serviço RabbitMQ, por padrão 5672.

4. QueueName: nome da fila do RabbitMQ. Esta fila será criada automaticamente.

5. MaxCount: quantidade de threads de execução paralela de processos. O valor recomendado aqui é o resultado da quantidade de núcleos lógicos da instância

multiplicado por 4. Números muito maiores do que isso podem acarretar em perda de performance no processamento.

Módulo Ações em Lote

15. módulo “Ações em Lote”, responsável pelo processamento de solicitações em lote, como aprovação/reprovação de processos ou resubmissão de processos, pode ser instalada com processamento centralizado ou distribuído.

1. SWorks.AcoesLote: módulo de processamento local, realizando enfileiramento e processamento multi-thread dos processos em memória e em instância única, sem distribuição de trabalho.

3. SWorks.AcoesLote.Producer: módulo responsável pelo enfileiramento de solicitações em lote no mecanismo de fila RabbitMQ.
4. SWorks.AcoesLote.Consumer: módulo que realiza o processamento das solicitações em lote, e suas tarefas, enfileiradas na fila do RabbitMQ.

Ações em Lote com Processamento Local

O módulo de “Ações em Lote” deve ser instalado num servidor “AlwaysOn”, na forma de

Windows Service, como exemplificado anteriormente.

Siga os seguintes passos para configurar o módulo:

1. Se desejar, crie uma pasta chamada “SWorks.AcoesLote” com conteúdo da pasta “SWorks.SVC” do pacote de instalação, caso contrário, realize a instalação do módulo a partir da própria pasta “SWorks.SVC”.

2. Abra o arquivo “SWorks.AcoesLote.appsettings.json” e realize a configuração do serviço através da propriedade “ServiceConfigurations” conforme abaixo:

1. MaxCount: representa a quantidade de threads para execução paralela da ação em lote.

Após instalação e configuração do RabbitMQ, siga as orientações abaixo para configurar o com o módulo Producer:

1. No mesmo servidor “AlwaysOn” onde o RabbitMQ foi instaladado, crie um pasta chamada “Sworks.AcoesLote.Producer” com o conteúdo da pasta “SWorks.SVC” contida no pacote de instalação.

2. Abra o arquivo “SWorks.AcoesLote.Producer.appsettings.json” e realize a configuração do serviço através da propriedade “ServiceConfigurations”

conforme    abaixo:

1. User/Password: usuário e senha de acesso ao RabbitMQ. Por padrão, é definido a palavra “guest” para o usuário e senha do serviço. Contudo, é recomendável o

acesso ao painel administrativo (http://localhost:15672) para definir um usuário

de    acesso    exclusivo.

1. Host: endereço da maquina onde o RabbitMQ está instalado. No caso do Producer, localhost.

2. Port: porta do serviço RabbitMQ, por padrão 5672.

3. QueueName: nome da fila do RabbitMQ. Esta fila será criada automaticamente.

4. MaxCount: indica a quantidade de itens a serem enfileirados no RabbitMQ. Esse valor pode ser aumentado caso a quantidade de workers disponíveis seja alta, visando aumentar a vazão de processamento.

1. WaitSecondsOnEnqueue: tempo, em segundos, a ser aguardado para cada turno de enfileiramento. Reduza esse tempo para enfileirar solicitações em lote mais rapidamente sob o custo de maior consumo de CPU.

Existem duas variáveis de configuração que determinam o comportamento do enfileiramento das solicitações de ações em lote e a cadência de processamento por solicitação:

1. QUANTIDADE_ACAOLOTE_TAREFAS_FILA (padrão 50): uma solicitação em lote pode gerar múltiplas tarefas, por exemplo, ao solicitar a aprovação de 100 processos, 100 tarefas são criadas para serem processadas de forma distribuída. Essa configuração determina quantas tarefas da solicitação em lote devem ser enfileiradas a cada turno de processamento da solicitação.

2. TEMPO_REAGENDAR_ACOES_LOTE_SEGUNDOS (padrão 60): determina o tempo de espera entre os turnos de processamento da solicitação em lote.

Caso seja notada baixa performance no processamento em distribuído das solicitações em lote, realize as devidas configurações nestas variáveis, e nos arquivos de configuração Producer/Consumer, para atingir a cadência desejada.

Instalando/Configurando o Módulo Ações em Lote Consumer

O módulo Consumer/Worker também deve ser instalado na forma de Windows Service. Abaixo seguem as configurações necessárias para que esse módulo seja capaz de processar os itens da fila do RabbitMQ:

1. Em um servidor a ser utilizado exclusivamente como “Worker”, seja para construção de uma imagem em ambiente com autoscale ou em uma máquina ligada em horário integral, crie uma pasta chamada

“SWorks.AcoesLote.Cosnumer” com o mesmo conteúdo da pasta “Sworks.SVC” presente no pacote de instalação.

2. Abra o arquivo “SWorks.AcoesLote.Consumer.appsettings.json” e realize a configuração do serviço através da propriedade “ServiceConfigurations” conforme abaixo:

1. User/Password: usuário e senha definidos no painel de gerenciamento do

RabbitMQ. Por padrão, a palavra “guest” para o user/password.

2. Host: endereço da maquina onde o RabbitMQ está instalado.

3. Port: porta do serviço RabbitMQ, por padrão 5672.

4. QueueName: nome da fila do RabbitMQ. Esta fila será criada automaticamente.

5. MaxCount: quantidade de threads de execução paralela de solicitações. O valor recomendado aqui é o resultado da quantidade de núcleos lógicos da instância multiplicado por 4. Números muito maiores do que isso podem acarretar em perda de performance no processamento.

Módulo Distribuidor de Atividades (Activity Dispatcher)

O módulo de distribuição de atividades, também conhecido como Activity Dispatcher, é responsável por distribuir atividades manuais solicitadas pelos usuários operadores através do módulo Web App.

1. Este módulo deve ser instalado na instância “AlwaysOn”, ou outra instância que se mantenha ligada 24/7.

2. Anteriormente, esse módulo era instalado sob o gerenciador de serviços

“ChassiSVC”, porém agora pode ser instalado como um Windows Service comum, utilizando a aplicação “sc” conforme mostrado anteriormente.

1. Após instalação, abra o arquivo “appsettings.json”, localizado na pasta raiz da aplicação, e configure o IP privado do servidor na tag “Url”, nas configurações do

Kestrel, conforme abaixo:

2. Verifique se a porta configurada está disponível. Caso não esteja, altere a porta manualmente.

3. Aoinicializar,omóduloiráatualizaraconfiguração

“URL_WS_DISTRIBUICAO_ATIVIDADES” automaticamente.

Certifique-se que a URL do Activity Dispatcher possui uma “/” no final. A falta dessa barra final pode acarretar erro de conexão entre o módulo Web App e o Activity Dispatcher.

Configuração Pós Instalação do Distribuidor de Atividades (Activity Dispatcher)

O sistema possui duas formas de controlar a distribuição de atividades manuais, a padrão, que usa consulta direta em banco de dados, e a recomendada usando o “Activity Dispatcher”.

Para ativar a distribuição de atividades usando o módulo “Activity Dispatcher”:

1. Acesse o menu de configurações em Administração -> Configurações.

2. Crie/modifiqueachavedeconfiguraçãodenome

“ARQUITETURA_BUSCA_ATIVIDADES_MANUAIS”

1. Atribua o valor “1” (sem aspas) para ativar a distribuição utilizando o módulo “Activity Dispatcher”.

b. O valor “2” indica que será utilizado busca direta usando banco de dados.

Módulo Auxiliares (Sentinela/Expurgo/Expiração Atividades Manuais)

Os módulos Sentinela, Expurgo e Expiração de Atividades Manuais eram anteriormente módulos internos no sistema, sendo executados de forma acoplada em outros módulos. A partir da versão 2.3 estes módulos são executáveis independentes e, portanto, precisam ser instalados na forma de Windows Services.

Cada módulo possui um executável próprio na pasta “SWorks.SVC” presente no pacote, e devem ser instalados uma máquina “AlwaysOn”, havendo apenas uma instância do módulo por ambiente instalada.

Para cada um dos executáveis, execute os seguintes passos para instalação:

1. Utilizando um prompt de comando como administrador, instale o módulo o comando “sc create” apontando para o respectivo executável do módulo, como por exemplo, “SWorks.Sentinela.exe”.

2. Esses módulos não necessitam de configurações específicas para seu funcionamento, apenas as tradicionais configurações de “string de conexão” e demais configurações de log.

Módulo Service Discovery

O módulo “Service Discovery” é uma aplicação web, que deve ser instalada na forma de

Windows Service, responsável por manter um registro de todos os módulos do sistema em execução.

A interação entre os demais módulos do S-Works e o Service Discovery ocorre da seguinte forma:

3. Cada módulo do S-Works, durante a inicialização, se auto registra através do serviço de Service Discovery.
4. O Service Discovery valida as informações do módulo, e armazena seus dados num arquivo de dados interno.
5. Periodicamente, o Service Discovery irá “pingar” o serviço através de uma URL de health-check disponibilizada pelo módulo registrado.

4. Caso um módulo não responda por 3 vezes seguidas, seu registro é apagado do arquivo de dados interno.

O diagrama abaixo demonstra essa interação entre os módulos do sistema e o módulo “Service Discovery”:

Instalação do Módulo Service Discovery

Este módulo deverá ser instalado num servidor “AlwaysOn” que seja acessível por todas as instâncias do cluster do S-Works.

1. Para instalar o módulo como Windows Service, abra o CMD como Administrador e digite o seguinte comando: sc create SWorks_ServiceDiscovery binPath="<CAMINHO_COMPLETO\SWorks.ServiceDiscovery.exe>"

Configuração do ’Target File’ do Módulo Service Discovery

O módulo Service Discovery também mantém um arquivo chamado “Target File”, utilizado pelo Prometheus para obter os endpoints para realizar a leitura das métricas publicadas por cada módulo.

O seguinte trecho de configuração do arquivo appsettings.json diz respeito sobre essa funcionalidade.

1. TargetFilePath: indica o caminho do arquivo onde as informações dos targets serão gravadas. O caminho informado deve ser acessível, em modo de leitura, pelo usuário de execução do Prometheus.

2. GlobalLabels: JSON que representa configurações globais que serão inseridas em qualquer métrica lida pelo Prometheus. Recomenda-se utilizar as duas métricas

“ambiente” e “cliente”, caso a instalação do Prometheus seja compartilhada.

Diagrama de Comunicação do Service Discovery

O diagrama a seguir mostra o ciclo de comunicação entre o Service Discovery e os demais módulos do sistema.

7. Arquivos de Configuração

Devido à alteração de framework, algumas configurações dos módulos, que costumavam ficar nos arquivos “web.config” para aplicações web, e no arquivo “ChassiSVC.exe.config”, agora estão localizadas em outros arquivos:

Arquivo

Módulos

Descrição

Arquivo

de

configuração,

em

formato

JSON,

presente

nas

Web App, Web Api,

aplicações web. Responsável por

appsettings.json

Distribuidor

de

conter  a  string  de  conexão  e

Atividades

configurações

que

antigamente

ficavam na tag “AppSettings” do

antigo “web.config”

Arquivo de configuração dos logs

Web App, Web Api,

do  sistema,

utilizando

log4net.

log.config

Distribuidor

de

Utilize para filtrar os níveis de logs

Atividades

registros, e tipos de saída, por ex.:

arquivo, Graylog.

Mesmo

propósito

do

arquivo

“appsettings.json”. Alguns desses

<MODULO>.appsettings.json

Módulos

módulos

possui

a

propriedade

executáveis

“ServiceConfiguration”,

indicando

a

configuração

do

serviço a ser executado.

<MODULO>.log.config

Módulos

Mesmo

propósito

do

arquivo

executáveis

“log.config”.

Configuração da String de Conexão

1. As configurações do WebApp e WebApi agora ficam num arquivo chamado "appsettings.json".

2. Altere a connectionString nesse arquivo com as credenciais obtidas do antigo

web.config. Essa é a tag de conexão usada no arquivo appSettings.json:

"DefaultConnection": "Server=localhost;Database=Sworks_banco;Integrated

Security=false;User    ID=sworks_teste;Password=senha@senha"

1. Verifique se os módulos WebApp e WebApi contém um arquivo web.config dentro da suas respectivas pastas, Caso não tenham, podemos pegar do ambiente de QA (172.16.0.39), O arquivo apenas contém informação para o IIS sobre qual módulo executar para processar a aplicação.

Configurações de Logs

O arquivo responsável pelas configurações de log são:

1. Log.config: para módulos que são web applications.

2. <MODULO>.log.config: para os módulos que são executáveis instalados na forma de Windows Services.

Logs em Ambientes Clusterizados

Em ambientes clusterizados, onde os módulos estão em múltiplos servidores, é recomendado que se crie uma pasta compartilhada no servidor “AlwaysOn”, ou em qualquer servidor que fique ligado 24/7, com liberação de leitura/escrita para os usuários dos módulos, e em seguida alterar as configurações do “Appender” de nome “RollingLogFileAppender”.

Configuração de Log no Orquestrador (Consumer/Worker)

O módulo Orquestrador (Consumer/Worker) possui uma particularidade na configuração do log, que permite que cada linha de log exiba o código do processo em uma coluna específica, facilitando a aferição de problemas no processamento pela equipe de técnica.

1. Abra o arquivo de configuração de logs “SWorks.Orquestrador.log.config”, ou o arquivo “SWorks.Consumer.log.config”, dependendo da forma com que o orquestrador foi instalado (processamento local ou distribuído).

2. Em cada appender configurado, procure pela tag “conversionPattern”.

3. Atribua o seguite valor no campo “value”:

<layout type="log4net.Layout.PatternLayout">

<conversionPattern value="%date [%thread] %-5level %logger - [Processo|%property{processo}] - %message%newline" />

</layout>

4. Uma propriedade customizada chamada “processo” irá ser adicionada em cada linha de log registrado.

Configurações de Monitoramento e Observability

A partir da versão 2.1, todos os módulos do S-Works possuem configurações que dizem respeito à habilitação e configuração da coleta de métricas do sistema.

A instrumentação dos módulos é realizada usando a biblioteca AppMetrics, e suas configurações são realizadas através do arquivo appsettings.json de cada módulo instalado.

O seguinte trecho de configuração estará presente em todos os arquivos de templates de configuração, podendo ser reaproveitados e alterados para aplicação correta nos arquivos originais.

1. MetricOptions: JSON que indica configurações globais.

3. GlobalTags: tags a serem aplicadas em todas as métricas coletas pelo módulo configurado
4. Enabled: indica se a coleta de métricas está habilitada. Em módulos que não são aplicações Web, desabilitar essa tag também evita com que o módulo inicialize um endpoint para leitura de métricas, economizando recursos de CPU e memória.

4. ReportingEnabled: indica quando o reporte de métricas está habilitado ou não.

Manter “false”.

5. MetricsWebTrackingOptions: configuração exclusiva para aplicações web, como o módulo WebApp e WebApi. Habilitar essas métricas faz com que o AppMetrics gere métricas usando um middleware no pipeline de comunicação do MVC, trazendo com detalhes mais informações sobre tempos de resposta, tamanho de requisições, e outros. Clique aqui para mais detalhes.

6. MetricsEndpointEnabled: ativa ou desativa endpoints de métricas (“/metrics”).

7. MetricsTextEndpointEnabled: ativa ou desativa endpoints de métricas com saída textual.

1. EnvironmentInfoEndpointEnable: ativa ou desativa o endpoint que fornece informações sobre o ambiente (“/env”).

Configurações do Prometheus

A instrumentação do S-Works prepara métricas para serem extraídas no formato de leitura da ferramenta Prometheus. Este manual não abordará a instalação e configuração desta ferramenta, porém se faz necessária a informação de leitura dos endpoints de métricas.

Conforme falado anteriormente, o módulo Service Discovery é responsável por manter um arquivo, chamado de “Targets File”, que contém as informações de coleta de métricas a serem lidas pelo Prometheus durante a operação de scrape (leitura das métricas). Para informar ao Prometheus a localização desse arquivo:

1. Acesse a pasta de instalação do Prometheus e abra o arquivo “prometheus.yml”

2. Na propriedade “scrape_configs”, adicione a seguinte linha:

1. Essa configuração dirá ao Prometheus que obtenha os endpoints de métricas utilizando o arquivo gerenciado pelo Service Discovery.

Isso se

Devido à dinamicidade de instâncias em execução do S-Works, quando implantado de forma clusterizada e utilizando recursos de auto-scaling, a configuração de endpoints de scrape precisa ser constantemente atualizada pelo Service Discovery. Dessa forma, o Prometheus sempre estará coletando as métricas das instâncias/módulos em execução.

Configuração do Appender para Graylog

A partir da versão 1.42, o S-Works possui compatibilidade padrão para envio de registros de log para uma instalação de Graylog existente. Para isso, siga as instruções abaixo:

1. Abra o arquivo de log do módulo desejadado.

2. Adicione o seguinte “appender”

<appender name="GelfHttpAppender" type="Gelf4net.Appender.GelfHttpAppender, Gelf4Net.HttpAppender">

<url value="http://localhost:12201/gelf" />

<layout type="Gelf4net.Layout.GelfLayout, Gelf4Net.HttpAppender">

<param name="AdditionalFields" value="Ambiente:Dev,Cliente:Simply,Modulo:TestConsole,Level:%level" />

<!--<param name="Facility" value="RandomPhrases" />--> <param name="IncludeLocationInformation" value="false" /> <param name="SendTimeStampAsString" value="false"/>

<!-- Sets the full_message and short_message to the specified pattern-

->

<param name="ConversionPattern" value="%date [%thread] %-5level %logger - [Processo|%property{processo}] - %message%newline" />

</layout>

</appender>

3. No campo “url”, coloque o endereço do servidor onde o “input stream” para o protocolo “GELF” foi configurado no seu Graylog. Consulte a documentação do Graylog ou o Wiki do S-Works para realiziar essa configuração no Graylog caso não exista.

4. Configure os campos adicionais a serem registrados na tag “AdditionalFields”.

5. Essas tags permitem com que tais campos sejam utilizados como filtros de pesquisa.

6. O exemplo acima contém, no padrão de conversão (conversion pattern) as iniformações do processo em “[Processo|%property{processo}], porém essa iniformação só é exigida para a configuração do appender do módulo Orquestrador(Worker).

7. Respeite padrões para nomenclatura dos campos “Ambiente” e “Modulo” para facilitar a pesquisa.

8. Na tag root, adicione o “Appender” configurado, ficando da seguinte forma:

<root>

<level value="DEBUG" />

<appender-ref ref="RollingLogFileAppender" />

<appender-ref ref="GelfHttpAppender" /> </root>

Ao final da instalação, certifique-se que os logs estão sendo corretamente enviados para o Graylog.

Importante: Caso exista um appender chamado “AdoNetAppender” nas configurações, remova-o. Este appender salva informações de log em banco de dados, porém será descontinuado em breve.

As pastas dos módulos, no pacote de release, contém arquivos com sufixo ".template" contendo exemplo de configuração. Esses arquivos podem ser clonados, removendo o sufixo, para serem usados como referência de configuração.

8. O Instalador do S-Works

No pacote de release está contido o instalador do S-Works (SWorks.Instalador.exe), porém seu papel ainda é voltado para atualização do sistema, fazendo a interrupção dos applications pools e Windows Services devidos, e realizando a substituição dos arquivos das pastas de destino.

Só utilize o instalador caso todos os módulos já estejam pré-instalados e configurados, ou para realizar a geração do script de migration na primeira etapa do instalador.

Execute o instalador como usuário administrador e siga as instruções na tela para criação do script de migração do banco de dados, se houver, configuração das pastas onde os módulos devem ser extraídos.

A partir da versão 2.3, devido à separação de cada módulo em executáveis independentes, a etapa do instalador que indica quais módulos devem ser instalados sofreu uma alteração para permitir que múltiplos módulos sejam instalados de forma mais intuitiva.

Etapa de configuração dos módulos instaláveis.

Para adicionar um novo módulo:

1. Preencha os campos “Tipo do Módulo”, “Nome do Pool/Serviços” e “Caminho de Instalação”

2. Clique no botão “Adicionar/Salvar”.

3. O módulo a ser atualizado aparecerá na listagem de módulos inferior.

Para editar um módulo:

1. Selecione o módulo na listagem. Os valores serão preenchidos nos campos de dados.

2. Altere os valores desejados, e clique novamente no botão salvar.

3. Os dados atualizados deverão substituir os valores antigos presentes na listagem.

Para remover um módulo da listagem:

1. Selecione-o na listagem. Os valores serão preenchidos nos campos de dados.

2. Clique no botão “Remover”.

3. O módulo deverá ser removido da listagem.

As demais etapas do instalador não sofreram alterações.

Anexo I - Checklist Pós Deploy

Objetivo

Este documento tem o intuito de orientá-lo na análise da consistência do sistema S-Works pós instalação/atualização. Segue abaixo os passos necessários de verificação.

Módulo Web App

1. Verifique a abertura do site. Ex:

Figura 1 - Validar se a versão apresentada bate com a versão instalada.

2. Realize login com o usuário.

3. Acesse algumas telas principais, por ex.: monitorar processos, detalhes de processo, edição de workflow.

Módulo Web Api

1. Acesse a página principal da WebApi. Atente-se para a URL de acesso. Ex:

2. Solicite ao cliente que invoque sua integração com o sistema.

3. Verifique a criação de processos, dados de entrada, documentos.

4. Verifique inicialização do processo, ou seja, passagem de status NOVO para

PENDENTE

Módulo Distribuidor de Atividades (Activity Dispatcher)

1. Verifique a inicialização correta do dispatcher, identificando no log os tempos sincronização/obtenção das atividades manuais no cache de distribuição. Ex:

Figura 3 - Arquivo de log do ActivityDispatcher

2. Como usuário no site, teste a distribuição de atividade manual.

Módulo Orquestrador (Producer)

1. Verifique a licença validada no log através do registro "Produto licenciado". Ex:

Figura 4 - Registro de log do Orquestrador Producer mostrando licença válida.

2. Verifique a presença no log de registros enfileirados (a não ser que não existam processos na fila, daí retornará 0).

Módulo Orquestrador (Worker)

1. Verifique a presença no log de obtenção de registros para processamento. Ex:

Figura 5 - Registro de log do Orquestrador Worker mostrando processos sendo recebidos.

2. Verifique na tela de diagnóstico na aplicação WebApp, se os processos estão sendo processados (processos verdinhos).

3. Acesse um dos processos processados após a implantação e verificar se contém erro no histórico de tarefas executadas.

Módulo Orquestrador – Processamento Local

Geralmente em ambientes menores, em vez de termos a dupla Producer+Worker, temos instalado apenas o Orquestrador que é responsável tanto por buscar os processos a serem processados, quanto de fato processar. Para isso então:

1. Verifique no log licença validada e obtenção de registros para processamento.

Figura 6 - Registro de log do Orquestrador mostrando licença válida.

Ex:

Orientações Gerais

As seguintes orientações podem ser utilizadas em todos os módulos do sistema.

1. Verifique a presença de erros nos logs após a implantação.

2. Antes de iniciar as aplicações, limpe os arquivos de logs para facilitar o rastreio de erros após a implantação.

Ambientes com Integração Externa (Função)

Alguns ambientes possuem um mecanismo de integração externa, nesses casos possuímos 2 módulos avulsos implantados no ambiente de produção que são responsáveis por processar a integração de propostas no sistema.

1. SWorks.Funcao.WS: web service hospedado no IIS da máquina AlwaysOn, e sua verificação deve ser através da navegação para uma página do site. Ao acessar a URL, a seguinte página é exibida:

2. Para realizar os devidos testes, deve-se entrar num endereço de busca de

Figura 7 - Página inicial do módulo Funcao.WS

proposta:

Figura 8 - Resultado de GET na URL de integração com Funcao.WS.

3. SWorks.IntegracaoExterna: é um módulo executável independente a ser instalado na forma de Windows Service (similar aos workers), implantados em um "AutoScaling Group".

1. Após implantação, solicite integração de propostas pelo cliente.

2. Verifique, a partir da tela de "Integração Função" no WebApp, se as propostas são integradas corretamente. Ex: