Arquitetura de uma Solução de Automação: Integrando C++ com um Web Service (USD)

Nos artigos anteriores, narramos a jornada de transformação de um processo manual em uma plataforma de automação de alta performance. Cobrimos o impacto no negócio, a arquitetura da flexibilidade e os segredos da otimização. Agora, no capítulo final desta série, vamos abrir o capô e mostrar o motor: como, tecnicamente, uma aplicação desktop feita em C++Builder se comunicou com um web service de Service Desk (USD) para automatizar a gestão de incidentes.
Este é um guia prático para desenvolvedores e arquitetos sobre como construir uma ponte robusta entre dois sistemas distintos para criar uma solução de automação coesa e eficiente.

Passo 1: A Conexão — Estabelecendo a Sessão

Tudo começa com a capacidade de "conversar". O primeiro desafio foi permitir que nossa aplicação C++ se comunicasse com o web service do USD, que utiliza o protocolo SOAP. Felizmente, o C++Builder oferece ferramentas que simplificam enormemente esse processo. Utilizando o WSDL (Web Service Definition Language) fornecido pelo USD, a IDE gerou automaticamente as classes e headers necessários, como o USD_R11_WebService.h, que abstraem a complexidade da comunicação SOAP.

O fluxo de autenticação é direto e seguro:

• Uma tela de login é apresentada ao usuário para que ele insira suas credenciais do USD.
• Com os dados em mãos, chamamos a função login() do serviço web, passando o usuário e a senha.
• Se a autenticação for bem-sucedida, o serviço retorna um Session ID (SID), um token numérico que valida nossa identidade para todas as chamadas futuras.

Esse sid é a chave para tudo que vem a seguir. Sem ele, o web service recusaria todas as nossas requisições.

Passo 2: A Extração e o Parsing — Buscando os Dados Relevantes

Uma vez autenticados, precisamos buscar os incidentes. A função principal aqui é a doSelect() do web service. Ela funciona como uma query SQL, mas para o Service Desk. A chave para usá-la eficientemente é construir uma whereClause precisa.
Em nosso código, a whereClause é montada dinamicamente para buscar apenas o que nos interessa:

Snippet de Código 1:

// Exemplo da construção da whereClause em automato.cpp
whereClause = "(group = U'"+grpusdcad+"') and open_date > "+ str;

Analisando a cláusula:

• group = U'"+grpusdcad+"': Filtramos os incidentes que pertencem a um grupo específico, garantindo que estamos buscando apenas os chamados que desejamos.
• open_date > "+ str: Para não buscar todo o histórico, filtramos apenas os incidentes abertos após uma determinada data (str contém um timestamp Unix), trazendo somente o trabalho recente. É um detalhe importante: aqui, a API do USD era flexível o suficiente para entender o timestamp Unix diretamente. Em muitos sistemas, seria necessário converter essa variável str para um formato de data e hora específico (como 'YYYY-MM-DD HH:MM:SS') antes de enviá-la na consulta, para garantir que a comparação de datas seja sempre precisa e livre de ambiguidades

A resposta do doSelect é um extenso documento XML, que armazenamos temporariamente em um componente tipo lista. Para extrair a informação útil desse XML, criamos uma função auxiliar de parsing. Ela funciona de maneira simples e eficaz: recebe o nome de um campo (como "ref_num") e busca no XML o valor contido entre as tags <AttrName>ref_num</AttrName> e <AttrValue>...</AttrValue>.
Repetindo esse processo para cada campo (summary, description, etc.), extraímos os dados de cada incidente e os utilizamos para popular as linhas da nosso grid principal.

Passo 3: A Validação Cruzada — A Rede de Segurança

Essa é a etapa que adiciona a "inteligência" ao processo. Como os dados inseridos nos chamados pelos usuários são propensos a erros, não podíamos confiar cegamente neles.

O fluxo de validação é o seguinte:

• A aplicação se conecta a um banco de dados replicada, não na base de produção. Usar uma base replicada é uma decisão de arquitetura crucial para não impactar a performance do banco de dados de produção com nossas consultas de validação.
• Para cada linha do grid, a aplicação pega os dados extraídos do USD (CPF, conta, coop) e executa uma ou mais queries no banco replicado para confirmar se eles fazem sentido.
• Por exemplo, em uma validação X, o sistema verifica se a conta do associado ainda está ativa na tabela correspondente. Se a conta já estiver encerrada, o ajuste não faz sentido.
• O resultado da validação – seja sucesso ou uma mensagem de erro clara – é escrito diretamente na coluna "Mensagem" do Grid1.

Isso dá ao analista um feedback imediato e contextualizado, permitindo que ele tome uma decisão informada sobre quais incidentes estão realmente prontos para serem executados.

Passo 4: A Execução em Lote e o Feedback — Fechando o Ciclo

Com os incidentes validados e selecionados pelo usuário, o botão "Executar" inicia a automação final. O processo itera sobre as linhas marcadas como "Sim" no Grid e, para cada uma, executa a lógica de negócio apropriada, que por sua vez gera o script SQL necessário.
Mas o ciclo só se fecha de verdade quando informamos ao sistema de origem (o USD) que o trabalho foi feito. Para isso, utilizamos a função que chama o método updateObject() do web service. A chamada é estruturada da seguinte forma:

Snippet de Código 2:

// Lógica conceitual da chamada updateObject em C++
service->updateObject(sid,          // Nosso Session ID de login
                      objectHandle, // O "persistent_id" do incidente
                      attrVals,     // Um array com ["status", "WIP"]
                      attributes);

Ao executar essa chamada, o status do incidente é alterado diretamente no USD (por exemplo, de "Aberto" para "Em Atendimento"), sinalizando para toda a organização que aquele chamado já está sendo tratado pela automação. Isso garante a consistência entre os sistemas e fornece um feedback claro sobre o progresso do trabalho.

Conclusão

Dissecamos um projeto que nasceu de uma grande dor operacional e evoluiu para uma plataforma de automação robusta. Vimos a estratégia de negócio, a arquitetura da flexibilidade, a engenharia da performance e, por fim, os detalhes técnicos da integração.
A arquitetura de quatro estágios — Conectar, Extrair, Validar e Executar/Retroalimentar — provou ser um modelo resiliente e poderoso. Ao desacoplar cada etapa, construímos um sistema onde cada parte faz o que faz de melhor, resultando em uma solução que não é apenas rápida e flexível, mas também confiável e inteligente.
A maior lição que fica é que, por trás de cada ganho de produtividade, existe um design bem pensado. A tecnologia é o meio, mas a arquitetura orientada a resolver o problema real, com foco no usuário e na resiliência, é o que realmente transforma um bom código em uma solução de impacto duradouro.