Sistema de Integracao ServiceNow <-> GLPI

Middleware Node.js para integrar chamados entre ServiceNow e GLPI, usando PostgreSQL como banco intermediario e acesso ao banco do GLPI.

Estado atual

1. Coleta de tickets SN por watermark.
2. Criacao/vinculo de tickets no GLPI (grava external_id no GLPI com o numero do ticket SN).
3. Sincronizacao de comentarios e tasks em duas direcoes.
4. Preenchimento do campo "Ticket Externo" no SN com o ID GLPI.
5. Motor de regras unico (processTicketLifecycleController) para status/fechamento/reabertura: status=5 (resolver SN), status=6 (encerrar definitivamente no SN), nota no GLPI quando o SN resolve/encerra por conta propria (com aviso e troca de fila no SN), reabertura automatica e regra de fora de escopo.

Fluxo do ciclo

Executado pelo main():

1. processErrorController
2. processTicketsController
3. processTicketLifecycleController (quando ENABLE_GLPI_CLOSE_CRON=true)
4. processCommentsController

Documentacao detalhada

1. Fluxo tecnico: docs/fluxo.md
2. Regras de negocio completas: docs/regrasdenegocio.md
3. Casos de uso: docs/casosdeuso.md
4. Manual do usuario (se eu fizer X, acontece Y): docs/manualusuario.md
5. Plano e checklist de rollout: docs/checklist.md

Variaveis de ambiente importantes

Feature flags

1. ENABLE_GLPI_CLOSE_CRON
   • true: liga o motor de regras de status/fechamento/reabertura (processTicketLifecycleController)
   • false: desliga o motor inteiro

ServiceNow

1. SERVICENOW_TABLE_INCIDENT_URL
2. SERVICENOW_TABLE_REQUEST_URL
3. SERVICENOW_TABLE_JOURNAL_URL
4. SERVICENOW_SC_ITEM_OPTION_URL
5. SERVICENOW_DEFAULT_USER
6. SERVICENOW_IGNORE_DEFAULT_USER_JOURNAL
7. SERVICENOW_EXTERNAL_TICKET_FIELD (default: u_external_ticket)

GLPI e banco intermediario

1. GLPI_DB_*
2. SNGLPI_DB_*
3. GLPI_OOS_SOLUTION_TYPE_ID

Desenvolvimento

1. Instalar dependencias:

npm install

2. Criar env:

copy .env.example .env.development

3. Executar:

npm run dev

Producao

Deploy manual na VM

git pull origin master
npm ci --omit=dev
pm2 start ecosystem.config.js --env production
pm2 save

Se o processo ja estiver rodando:

pm2 restart sn-glpi-sync-cron --update-env

Deploy via Gitea Actions

O workflow .gitea/workflows/deploy-production.yml roda no runner com rotulo vm-prod.

1. Configure a variavel do repositorio PROD_DEPLOY_PATH com o caminho da aplicacao na VM de producao. Se nao configurar, o workflow usa /opt/sn-glpi-sync-new.
2. Garanta que o arquivo .env.production exista nesse caminho na VM e contenha SERVICENOW_CAOA_TI_GROUP_ID preenchido.
3. Faça push na branch master ou execute o workflow manualmente em Actions.
4. Acompanhe pelo Gitea Actions ou na VM:

pm2 list
pm2 logs sn-glpi-sync-cron

Onde fica o .env.production

O .env.production nunca e versionado no git — o rsync do deploy exclui .env* de proposito, exatamente para nunca sobrescrever esse arquivo com o codigo. O proprio workflow ja materializa esse arquivo a cada deploy a partir do secret ENV_PRODUCTION (Settings > Actions > Secrets no Gitea), entao a fonte da verdade das credenciais de producao e esse secret, nao um arquivo mantido a mao na VM. Detalhes:

1. Ele existe dentro da propria pasta de deploy ($PROD_DEPLOY_PATH/.env.production, ex.: /opt/sn-glpi-sync-new/.env.production) — nao na raiz de nenhum usuario (nem dev, nem root). cron.js/src/app.js resolvem o caminho do env relativo a propria raiz do repo, entao e ali que ele precisa estar.
2. O workflow ja aplica chmod 600 nele apos escrever (dono = usuario que roda o PM2), evitando outro usuario local da VM lendo credencial de banco/API em texto puro.
3. Pra atualizar uma credencial/config de producao, edite o secret ENV_PRODUCTION no Gitea e rode o deploy de novo (push em master ou workflow_dispatch) — nao precisa mais SSH na VM pra editar arquivo a mao. Como o secret fica guardado no Gitea (fora da VM), tambem resolve o risco de perder a unica copia das credenciais se o disco da VM falhar.

Rollback manual

O deploy guarda a versao anterior em $PROD_DEPLOY_PATH.previous antes de sincronizar o codigo novo. Se o deploy subir uma versao com problema (o node --check so pega erro de sintaxe, nao de logica), o rollback e:

rsync -a --delete "$PROD_DEPLOY_PATH.previous"/ "$PROD_DEPLOY_PATH"/
cd "$PROD_DEPLOY_PATH" && pm2 restart ecosystem.config.js --update-env

Observacoes

1. O projeto ainda nao tem suite automatizada robusta.
2. O rollout recomendado e por fases com feature flags.
3. Nao remover schema legado antes de estabilizar o fluxo novo.
4. Consulte docs/checklist.md antes de cada deploy para validar pre e pos-subida.