Basis Sgo Jira

Integração com o SGO

A ideia mais cara de trazer para este assunto é que o SGO "é um Jira, então vale a documentação do Jira". Vale pouca coisa dela, e por três motivos que se acumulam.

É Jira Server 6.3.13. REST v2, Basic Auth, sem ADF, sem /rest/api/3, sem /rest/api/3/search/jql, sem token de API. Tudo o que a documentação do Atlassian Cloud diz sobre autenticação, sobre formato de descrição e sobre os endpoints novos de busca é sobre outro produto. O que responde é /rest/api/2/… com Authorization: Basic.

Boa parte do que uma integração da Basis toca não é Jira. Os campos de tabela — Histórico Profissional, vagas — são grids do plugin idalko iGrid, que tem árvore REST própria (/rest/idalko-igrid/1.0/…) e formato próprio. Há campos nFeed que não têm allowedValues, há scripted-field calculado que não aceita escrita, e há post-function reescrevendo o que você mandou depois que o POST respondeu 201.

E existe um SGO só. Não há instância de homologação. Desenvolvimento, staging e produção apontam para https://sgo.basis.com.br, para os mesmos projetos e para a mesma fila do RH. Toda escrita que sai de qualquer ambiente é registro de verdade sobre gente de verdade — e é por isso que a §9 existe e não é opcional.

Quando usar

Ative esta skill quando o assunto for a conversa com o SGO: montar payload de ocorrência, resolver id de customfield e de opção, escrever no grid, subir anexo, buscar por JQL, receber webhook, decidir se um erro se retenta, ou configurar a credencial numa aplicação nova.

O que ela não cobre. Como o app Spring é montado em volta disso — módulos, propriedades, Flyway — é basis-spring-app; o equivalente em Python é basis-python-app; o texto de uma nota de incidente em wiki markup do Jira é basis-relatorio-incidente. A fronteira é útil: aqui o objeto é o sistema do outro lado da rede, não o seu.

Os três hábitos que resolvem

1. Pergunte ao SGO antes de supor. createmeta diz quais campos existem, de que tipo, com que opções e quais são obrigatórios hoje. editmeta diz quais a tela de edição aceita, que não são os mesmos. mypermissions diz o que a sua credencial pode. As três respostas mudam sem aviso, porque quem mexe é o RH na administração do Jira.
2. Trate 200 como opinião. O Jira responde 200 com corpo de erro, e responde 400 tanto para regra de negócio dele quanto para defeito seu. Quem decide é o corpo.
3. Escreva como se cada chamada pudesse ser a segunda. Rede corta no meio de saga de três passos. Sem guarda de idempotência, retomar é duplicar — e desduplicar ocorrência na fila do RH é trabalho de gente.

0. Os identificadores, e de onde eles vêm

Nada disso se deduz, e nada disso se chumba no código de regra:

As duas últimas linhas são as que mais custam quando erram, e são as únicas que nunca podem morar em constante: as opções são editadas pelo RH sem release nenhum do seu lado.

O gridId ser o id do customfield foi inferência do judge-admin antes de ser fato: o spike de 2026-08-19 confirmou chamando. Anote como confirmado, não como óbvio.

1. O cliente

Java, Spring: interface @HttpExchange + RestClient, um bean só, sem SDK.

@Bean
SgoClient sgoClient(SgoProperties props) {
    // HTTP/1.1 explícito: o cliente do JDK negocia HTTP/2 por padrão, e um Jira 6.3.13 é de
    // antes do HTTP/2 -- a negociação não compra nada e custa uma tentativa de upgrade por
    // conexão. Fixá-la também tira do caminho uma classe de falha de protocolo.
    var http = HttpClient.newBuilder().version(HttpClient.Version.HTTP_1_1).build();
    var factory = new JdkClientHttpRequestFactory(http);
    factory.setReadTimeout(props.readTimeout());          // 90s é o ponto de partida usado

    var builder = RestClient.builder()
            .baseUrl(props.baseUrl())
            .requestFactory(factory)
            // Exigido pelo Jira no envio de anexo; inócuo nas demais chamadas, então é default.
            .defaultHeader("X-Atlassian-Token", "no-check");

    if (props.temCredencial()) {
        var codificada = Base64.getEncoder().encodeToString(
                (props.username() + ":" + props.password()).getBytes(StandardCharsets.UTF_8));
        builder.defaultHeader(HttpHeaders.AUTHORIZATION, "Basic " + codificada);
    } else {
        // Diga isto no arranque. Ver §2: sem credencial, várias chamadas respondem 200 e mentem.
        log.warn("SgoClient sem credencial: só leitura anônima funciona");
    }
    ...
}

Python: ks-jira (libs/ks-jira do kaizenstat) devolve um JIRA autenticado a partir de KS_SGO_USER/KS_SGO_PASSWORD, e devolve None quando falta credencial em vez de estourar — quem chama precisa tratar isso, e o padrão é adiar o trabalho, não segui-lo em silêncio.

O que a biblioteca jira não expõe (notifyUsers, endpoints do iGrid) sai por jira_client._session, que é a sessão requests autenticada dela. É privado e é o caminho aceito na casa; ver references/cliente-python.md.

Detalhe de configuração: no Spring, o prefixo application.sgo.* já ganha sobreposição por APPLICATION_SGO_* via relaxed binding — não escreva ${VAR} no yaml para isso.

2. Sem credencial, o SGO responde — e responde errado

Este é o achado que mais engana, e está medido:

A linha do meio é a perigosa. Uma verificação de duplicidade que pergunta ao SGO sem credencial recebe "está livre" com a convicção de um 200, e o usuário só descobre a duplicidade na recusa do envio. Se a sua consulta depende de permissão, cheque temCredencial() antes de perguntar, e registre no arranque se a verificação está ativa ou desligada — uma senha rotacionada vira uma verificação que parou de verificar, e nada na tela muda.

3. O catálogo: id de opção nunca no código

O SGO grava id numérico (54646), não rótulo (Access/Libreoffice Base). A tradução rótulo→id é de um módulo só, alimentado pelo createmeta em runtime.

GET /rest/api/2/issue/createmeta
      ?projectIds=<projeto>&issuetypeIds=<tipo>&expand=projects.issuetypes.fields

Quatro coisas que só se descobrem lendo essa resposta de verdade — todas em references/campos-e-payload.md:

• As cascatas vêm inteiras e aninhadas: cada pai traz children com id e rótulo.
• required por campo é a autoridade sobre obrigatoriedade — mais confiável que procurar "Obrigatório" no HTML da tela.
• Não existe disabled. Opção que o RH desabilitou continua no createmeta, e nenhum endpoint da API expõe esse estado. Um formulário construído a partir dele oferece opções desativadas junto com as ativas, e a única saída é uma lista de exclusão em configuração — dívida assumida, com teste que fixa a lista para a próxima divergência aparecer.
• Rótulo tem lixo de digitação, inclusive espaço não-quebrável (U+00A0) no meio. Daí a regra: persista o id da opção, nunca o rótulo. Rascunho salvo com rótulo normalizado pela tela não volta a casar com a origem, e a tradução falha em silêncio num campo obrigatório.

E o catálogo envelhece: entre duas capturas do mesmo createmeta em três dias já mudaram contagem de opções, obrigatoriedade de treze campos e a lista de filhas de uma cascata. Versione a fixture com a data da captura no nome e deixe o teste cobrar as contagens daquela captura: o teste vermelho é o aviso de que o RH mexeu.

4. A forma do valor no payload

O tipo do campo no Jira decide a forma, e errar a forma é 400 na cara — ou, pior, campo gravado vazio.

Campo nulo não entra no payload. A obrigatoriedade já foi cobrada na submissão, com a lista que veio do próprio Jira; repetir a cobrança na montagem cria uma segunda verdade que diverge da primeira na próxima mudança do RH.

5. As três formas de data, no mesmo sistema

As duas primeiras convivem no mesmo PUT; a primeira e a terceira convivem no mesmo envio. Trocá-las de lugar é 400 — e o 400 é o desfecho bom.

O ruim é o fuso. O servidor renderiza os milissegundos do grid no fuso dele. Meia-noite calculada em UTC aparece como 21h do dia anterior: a data anda um dia para trás, em silêncio, sem erro em lugar nenhum, num campo que alguém vai usar para contar tempo. Por isso o fuso é parâmetro de configuração (America/Sao_Paulo, confirmado pelo offset do serverInfo) e nunca ZoneId.systemDefault(): a máquina onde a sua aplicação roda não tem nada a ver com o fuso do Jira.

6. TableGrid (plugin iGrid)

GET  /rest/idalko-igrid/1.0/grid/{gridId}/issue/{issueId}
POST /rest/idalko-igrid/1.0/grid/{gridId}/issue/{issueId}
     {"rows": [{"<coluna>": "<valor>", …}]}

O issueId é o id numérico da ocorrência, não a chave PROJ-123. As colunas se chamam pelo nome da configuração do grid (gd.columns=empresa,funcao,cargo,entrada,saida,tempoMeses), e coluna definida mas fora de gd.columns não é coluna ativa: não entra no payload.

Duas assimetrias que custam tempo:

• A resposta de leitura vem ora em values, ora em rows, conforme a versão do plugin. Leia os dois.
• O que se escreve é escalar; o que volta é objeto. Você manda {"perfil": "Desenvolvedor"} e relê {"perfil": {"value": "Desenvolvedor"}}. Código que roundtripa precisa saber disso.

Vazio na leitura tem de ser distinguível de falha: devolver [] num erro de rede faz uma queda do Jira parecer "ocorrência sem linhas", e a rotina termina como sucesso silencioso.

7. Anexos

POST /rest/api/2/issue/{chave}/attachments, multipart, campo file, um arquivo por chamada, com X-Atlassian-Token: no-check.

• 200 com array vazio existe e significa que nada chegou. Dar isso por enviado conclui a saga com a ocorrência sem os arquivos, e ninguém descobre até alguém abrir a ocorrência.
• O nome do arquivo atravessa um cabeçalho de multipart. Ele é entrada de usuário: higienize antes, ou um caractere de controle quebra o parser do Jira. Nome com acento em servidor dessa idade é o ponto em que a codificação costuma discordar — vale conferência manual.
• O Jira 6 não devolve hash de anexo. Se você precisa provar integridade, confira o SHA-256 antes de subir, contra o hash registrado no recebimento. Depois não dá.
• Para saber o que já está lá sem trazer a ocorrência inteira de volta pela rede: GET /rest/api/2/issue/{chave}?fields=attachment. Numa ocorrência que guarda dado pessoal, isso não é economia de banda, é §11.

8. Sucesso não é 200

A classificação é pelo corpo, nunca pelo código HTTP sozinho:

401 como transitório é deliberado e contraintuitivo — está aqui porque a alternativa perde dado. E permanente e alertar são eixos diferentes: um 401 é transitório e merece alerta; um 400 com errorMessages é permanente e não merece nenhum.

9. Escrever num SGO que todos os ambientes compartilham

Não existe SGO de homologação. Duas aplicações da Basis chegaram à mesma necessidade por caminhos diferentes, e as duas soluções valem:

A chave que desliga a escrita — checada em runtime, nunca por @ConditionalOnProperty. A condição do Spring é avaliada uma vez só e, em imagem nativa, essa vez é o build: o process-aot roda sem perfil e sem variável de ambiente, o matchIfMissing vale, o bean entra congelado na imagem e a chave deixa de ter efeito em runtime. Medido em 2026-08-21 numa imagem nativa: com a chave em false, o agendador rodou assim mesmo — e na JVM não rodava. Uma proteção que some conforme o formato do artefato é pior que proteção nenhuma, porque ninguém desconfia dela. O bean sempre sobe; quem decide é o método.

O ensaio que grava tudo menos no Jira. No lado Python, a rotina persiste o que faria com status suppressed — corpo, chave de deduplicação, tudo revisável em tabela, e inerte por construção: nenhuma rotina de entrega o seleciona. Publicar o que foi ensaiado é um ato deliberado com log próprio, não um UPDATE à mão. Duas marcas distintas nos logs ([DRY RUN] e [JIRA DRY RUN]) porque os dois modos deixam estados muito diferentes para trás.

E, quando é inevitável escrever de verdade:

• Combine antes com quem é dono da fila, e avise no fim.
• Marque de forma inconfundível ([TESTE — IGNORAR]) num campo que a post-function não reescreva — se você marcar o summary e uma post-function o substituir, a ocorrência de teste fica indistinguível de uma real. Aconteceu: uma ficou três dias na fila do RH assim.
• Procure a marca em qualquer posição do campo ao decidir se pode editar, não só no começo.
• Prefira reusar uma ocorrência de teste a criar outra: a fila não ganha linha nova.
• Ponha a trava no código, não no procedimento: leia o campo antes de escrever e recuse-se a editar ocorrência sem a marca. Um PUT na ocorrência errada mexe no cadastro de uma pessoa real, e esse erro não tem desfazer.
• Se um profile hospeda mais de um roteiro, nenhum é o padrão. Exija o argumento; sem argumento reconhecido, não faça nada e diga o que digitar.

10. Retomar sem duplicar

Criar a ocorrência, escrever o grid e subir os anexos são chamadas que falham de forma independente. Sem estado por etapa, retomar é recomeçar, e recomeçar depois da primeira é criar a segunda ocorrência.

A guarda certa depende da etapa, e não é a mesma em todas:

A comparação de anexos é contagem por nome e tamanho, não conjunto: dois arquivos de mesmo nome e mesmo tamanho dariam os dois por presentes depois de subir o primeiro.

Do lado Python o mesmo problema tem outra forma — outbox: grave a intenção antes de tentar, reivindique a linha (sending, tentativa contada, commitada) antes da chamada, e registre o desfecho depois. Uma queda no meio deixa reivindicação visível, retentada após carência. Pode duplicar um envio, e isso é aceito: at-most-once não existe sobre HTTP. A chave de deduplicação é identidade de negócio, não hash do corpo.

Duas escritas no Jira não compartilham transação. Se um comentário precisa da chave de uma ocorrência criada por outra ação, isso é dependência declarada em dado, não duas chamadas na mesma respiração.

E teto de tentativas: parar de tentar não é descartar. Descartar diz ao usuário que o pedido dele foi recusado quando ele está na fila. Pare, alerte, e deixe alguém mandar tentar de novo — "está tentando sozinho" e "parou e espera alguém" pedem ações opostas de quem olha o painel.

11. O dado que passa por aqui é pessoal

Ocorrência de RH tem CPF, RG, endereço e telefone dentro. Isso não é observação genérica de LGPD; é uma lista de coisas que já quase deram errado:

• Nenhum log imprime corpo de requisição. Um log.debug("payload: {}", …) escrito com pressa vaza o cadastro inteiro para onde muito mais gente lê do que o banco.
• Busca com dado pessoal vai por POST, nunca GET. A JQL num GET põe o CPF na URL — log de acesso do Jira, histórico do navegador, qualquer proxy no caminho.
• Não registre a mensagem da exceção de uma busca: um 400 por JQL malformada devolve a JQL no corpo, e a JQL tem o CPF dentro. Este é o caminho que ninguém pensa em conferir.
• Ao classificar errors por campo, nomeie os campos, nunca os valores recusados.
• maxResults: 0 quando a pergunta é "existe?": trazer a ocorrência traz dado de outra pessoa.
• Mascarar não é anonimizar. Devolver j***@gmail.com para quem digitou um CPF confirma a inicial e o provedor de alguém a quem essa pessoa pode não ter acesso. Use como destino, não renderize.
• A credencial fica em arquivo fora do versionado (no Spring, ./config/, com /config/ no .gitignore) — e confira com git check-ignore antes do primeiro commit, não depois.
• Confira o que a conta de serviço pode: GET /rest/api/2/mypermissions?issueKey=…. Uma conta que só precisa criar ocorrência e anexar arquivo não precisa de ADMINISTER nem de DELETE_ISSUE, e credencial de aplicação exposta na internet é onde isso importa.

12. Assinatura — sintoma e causa

O que engana

• "O createmeta é a verdade sobre o que dá para gravar." É a verdade sobre a tela de criação. A tela de edição é outra lista, e só o editmeta responde por ela.
• "Se createmeta respondeu, a credencial está boa." Ele responde anônimo. §2.
• "O 400 é do usuário." Metade é sua. Só o corpo separa.
• "Retentar é inofensivo." Depois que a ocorrência existe, retentar do zero é destrutivo.
• "Grid é campo." Tem endpoint próprio, plugin próprio, formato de data próprio e forma de leitura diferente da de escrita.
• "notifyUsers=false resolve o e-mail." É privilégio de administrador no Jira Server. O lado Python usa esse parâmetro em produção nos PUT de correção — trate como caminho conhecido, e confirme na sua conta antes de contar com ele. Sem ele, toda edição notifica quem observa a ocorrência: um fluxo de atualização manda e-mail a cada retomada.
• "Staging escreve em staging." Não existe staging. §9.

Checklist

Antes da primeira escrita de uma aplicação nova

• project-id, issue-type-id e grid-id em configuração, não em constante
• Credencial fora do versionado, e git check-ignore conferido
• mypermissions lido: a conta pode o que precisa, e não muito mais
• Catálogo lido do createmeta em runtime; nenhum id de opção no código
• Fixture do createmeta versionada com a data no nome, e teste cobrando as contagens
• A chave que desliga a escrita é checada em runtime, e testada no artefato que vai rodar
• Nenhum log imprime payload, JQL nem mensagem de exceção de busca

Antes de rodar contra o SGO de verdade

• Combinado com quem é dono da fila
• Marca de teste num campo que a post-function não reescreve
• Ocorrência de teste reusada, não criada
• O roteiro exige argumento explícito; sem ele, não faz nada

Ao revisar uma integração existente

• 200 é conferido pelo corpo antes de contar como sucesso
• Cada etapa tem guarda de idempotência, e a guarda certa para aquela etapa
• Esgotar tentativas alerta e não descarta
• Datas: os três formatos no lugar certo, e o fuso vindo de configuração

References

• references/campos-e-payload.md — createmeta na prática: cascatas, obrigatoriedade, opções desabilitadas, rótulos com lixo, a tabela tipo→forma, os três formatos de data e por que o PostgREST do SGO não substitui uma carga própria.
• references/tablegrid-igrid.md — o plugin iGrid: formato da configuração do grid, leitura vs escrita, values/rows, e as guardas de idempotência.
• references/cliente-java.md — a interface @HttpExchange anotada, o RestClient, @ConfigurationProperties, e a saga com estado por etapa.
• references/cliente-python.md — ks-jira, o que a biblioteca jira cobre, quando descer para _session, webhooks do Jira e o outbox transacional.
• references/falhas-e-retry.md — a classificação linha a linha, backoff, o que alertar, e o que "parar sem descartar" quer dizer no estado.