hubxglpi/fluxoEntidade.md

Fluxo de Resolução e Criação de Entidades (GLPI)

Contexto

Quando um chamado de Implantação chega no Hub x GLPI, precisamos garantir que exista uma Entidade correta no GLPI para vincular o ticket.

Hoje, a resolução tenta encontrar a entidade pelo padrão de nome baseado em:

• codigoCliente
• codigoServico
• nomeCliente

Caso não encontre, entra a feature de criação automática via API (GLPI v2 + OAuth).

Regra importante: criação/alteração de entidades sempre via API, nunca via banco do GLPI.

---

Convenções de Nome

Entidade mãe (Cliente)

• Formato: {codigoCliente} - {nomeCliente}
• Exemplo: 12345 - ACME Telecom

Entidade filha (Serviço)

• Formato: {codigoCliente} - {codigoServico} - {nomeCliente}
• Exemplo: 12345 - 67890 - ACME Telecom

Observação: O {nomeCliente} é repetido na filha para manter legibilidade e facilitar busca manual no GLPI.

---

Busca de Entidades

Busca por Serviço (Entidade filha)

Procura por entidade que contenha:

• {codigoCliente} - {codigoServico} (prefixo/like)

Busca por Cliente (Entidade mãe)

Procura por entidade que contenha:

• {codigoCliente} - (prefixo/like)

---

Opção A — Criação hierárquica (Mãe + Filha quando necessário)

Objetivo

Garantir hierarquia consistente no GLPI:

• Cliente como entidade mãe
• Serviço como entidade filha

Fluxo (passo a passo)

1. Tentar encontrar entidade por Serviço

   • Busca: {codigoCliente} - {codigoServico}*
   • Se encontrou:
     • ✅ usar essa entidade (filha) e finalizar

2. Se não encontrou por Serviço: tentar encontrar entidade por Cliente

   • Busca: {codigoCliente} -*
   • Se encontrou:
     • ✅ criar entidade filha abaixo dessa mãe:
       • Nome: {codigoCliente} - {codigoServico} - {nomeCliente}
       • Parent: {codigoCliente} - {nomeCliente}
     • ✅ usar a entidade criada (filha) e finalizar

3. Se não encontrou nem por Serviço nem por Cliente

   • Criar entidade mãe:
     • Nome: {codigoCliente} - {nomeCliente}
     • Parent: raiz (definir entidade pai padrão, ex.: Root)
   • Criar entidade filha abaixo da mãe:
     • Nome: {codigoCliente} - {codigoServico} - {nomeCliente}
     • Parent: {codigoCliente} - {nomeCliente}
   • ✅ usar a entidade criada (filha) e finalizar

Resultado final (Opção A)

• Ticket sempre fica na entidade filha (serviço)
• Sempre tenta manter estrutura hierárquica consistente

---

Diagrama de Fluxo — Opção A (hierárquica: Mãe + Filha quando necessário)

flowchart TD
    A[Chamado de Implantação chega do Hub] --> B[Extrair dados<br/>codigoCliente<br/>codigoServico<br/>nomeCliente]

    B --> C{Existe entidade<br/>por Serviço?}
    C -->|Sim| D[Usar entidade de Serviço]
    D --> Z[Fim / Continua fluxo do ticket]

    C -->|Não| E{Existe entidade<br/>por Cliente?}

    E -->|Sim| F[Criar entidade de Serviço<br/>via API GLPI]
    F --> G[Parent = Entidade Cliente<br/>Nome = codigoCliente-codigoServico-nomeCliente]
    G --> Z

    E -->|Não| H[Criar entidade Cliente<br/>via API GLPI]
    H --> I[Parent = Contratos Ativos<br/>Nome = codigoCliente-nomeCliente]

    I --> J[Criar entidade de Serviço<br/>via API GLPI]
    J --> K[Parent = Entidade Cliente<br/>Nome = codigoCliente-codigoServico-nomeCliente]
    K --> Z

Opção B — Criação simplificada (sem forçar hierarquia)

Objetivo

Criar o mínimo possível e evitar duplicação de entidades.

Fluxo (passo a passo)

1. Tentar encontrar entidade por Serviço

   • Busca: {codigoCliente} - {codigoServico}*
   • Se encontrou:
     • ✅ usar essa entidade e finalizar

2. Se não encontrou por Serviço: tentar encontrar entidade por Cliente

   • Busca: {codigoCliente} -*
   • Se encontrou:
     • ✅ usar essa entidade mãe
     • ❌ não cria entidade filha
     • Finaliza

3. Se não encontrou nem por Serviço nem por Cliente

   • Criar uma entidade única (sem mãe):
     • Nome: {codigoCliente} - {codigoServico} - {nomeCliente}
     • Parent: raiz (ou padrão definido)
   • ✅ usar essa entidade e finalizar

Resultado final (Opção B)

• Ticket pode ficar:
  • na entidade de serviço (se existir)
  • ou na entidade de cliente (se existir)
  • ou numa entidade única criada
• Não garante hierarquia “mãe → filha”

---

Fluxo Opção B

flowchart TD
    A[Chamado de Implantação chega do Hub] --> B[Extrair dados<br/>codigoCliente<br/>codigoServico<br/>nomeCliente]

    B --> C{Existe entidade<br/>por Serviço?}
    C -->|Sim| D[Usar entidade de Serviço]
    D --> Z[Fim / Continua fluxo do ticket]

    C -->|Não| E{Existe entidade<br/>por Cliente?}

    E -->|Sim| F[Usar entidade de Cliente]
    F --> Z

    E -->|Não| G[Criar entidade Única<br/>via API GLPI]
    G --> H[Parent = Root<br/>Nome = codigoCliente-codigoServico-nomeCliente]
    H --> Z

Opção C — Híbrida (Implantação cria; demais apenas resolvem)

Objetivo

• Para Implantação: garantir estrutura correta criando entidades quando necessário (igual Opção A).
• Para demais tipos de chamado: não criar entidades, apenas resolver a melhor entidade existente; se não houver, usar fallback Contratos Ativos.

---

Fluxo (passo a passo)

1) Identificar tipo do chamado

• Se tipo == Implantação → executar Fluxo A (criação hierárquica).
• Se tipo != Implantação → executar Fluxo de Resolução sem criação.

---

Fluxo A (quando Implantação)

Segue exatamente a Opção A:

1. Buscar entidade por Serviço ({codigoCliente} - {codigoServico}%)
2. Se não achar, buscar por Cliente ({codigoCliente} -%)
3. Se achar Cliente, criar Serviço abaixo do Cliente
4. Se não achar nenhum, criar Cliente (embaixo de Contratos Ativos) e depois criar Serviço abaixo do Cliente
5. Retornar sempre a entidade de Serviço

---

Fluxo de Resolução (quando NÃO é Implantação)

1. Buscar entidade por Serviço ({codigoCliente} - {codigoServico}%)
   • Se achou: ✅ usar e finalizar
2. Se não achou, buscar entidade por Cliente ({codigoCliente} -%)
   • Se achou: ✅ usar e finalizar
3. Se não achou nenhum dos dois:
   • ✅ usar entidade Contratos Ativos (fallback)
   • ❌ não criar nada

---

Resultado final (Opção C)

• Implantação: sempre aponta para entidade de Serviço, criando Cliente/Serviço quando faltar.
• Demais chamados: nunca criam entidades; ficam na melhor existente (Serviço → Cliente → Contratos Ativos).

---

Diagrama de Fluxo — Opção C (Híbrida)

flowchart TD
    A[Chega chamado do Hub] --> B[Extrair dados<br/>codigoCliente<br/>codigoServico<br/>nomeCliente<br/>tipoChamado]

    B --> C{Tipo é<br/>Implantação?}

    %% ========== RAMO IMPLANTAÇÃO (OPÇÃO A) ==========
    C -->|Sim| IA{Existe entidade<br/>por Serviço?}
    IA -->|Sim| I1[Usar entidade de Serviço] --> Z[Fim / Continua fluxo do ticket]

    IA -->|Não| IB{Existe entidade<br/>por Cliente?}
    IB -->|Sim| I2[Criar entidade de Serviço<br/>via API GLPI<br/>Parent = Cliente] --> I3[Usar entidade criada] --> Z

    IB -->|Não| I4[Criar entidade Cliente<br/>via API GLPI<br/>Parent = Contratos Ativos] --> I5[Criar entidade de Serviço<br/>via API GLPI<br/>Parent = Cliente] --> I6[Usar entidade criada] --> Z

    %% ========== RAMO NÃO IMPLANTAÇÃO (RESOLVE ONLY) ==========
    C -->|Não| NA{Existe entidade<br/>por Serviço?}
    NA -->|Sim| N1[Usar entidade de Serviço] --> Z

    NA -->|Não| NB{Existe entidade<br/>por Cliente?}
    NB -->|Sim| N2[Usar entidade de Cliente] --> Z

    NB -->|Não| N3[Usar entidade fallback<br/>Contratos Ativos] --> Z