Artia
Objetivo/Resumo
O conector Artia permite a interação com as APIs GraphQL do Artia de maneira eficiente, permitindo consultas e mutações de dados para gerenciamento de projetos através da plataforma Artia.
Funcionalidades principais
- Consultas e Mutations: Permite realizar queries e mutations nas APIs GraphQL fornecidas pelo Artia.
- Configuração de Template: Facilita a criação e manutenção de templates para montagem da query para consultas complexas.
- Integração com Artia: Acesso completo aos recursos de gerenciamento de projetos do Artia.
Autenticação
O Conector Fluid Artia GraphQL API utiliza autenticação baseada em Client ID e Client Secret para garantir a segurança das suas requisições. Para obter essas credenciais, você precisa:
- Acessar o painel administrativo do Artia
- Navegar até as configurações de API
- Gerar um novo Client ID e Client Secret para sua aplicação
- Configurar as credenciais no seu workspace da Fluid
Configuração do conector
Parâmetros de configuração
- Operação: O conector Artia expõe apenas a operação Query — é por meio dela que tanto consultas quanto mutações são enviadas, já que o protocolo GraphQL usa uma única chamada HTTP para os dois casos. Para executar uma mutação, basta escrever a sintaxe mutation{...} dentro do campo Template, representado pelo ícone de plug no conector.
- Template: Área onde você pode definir e editar o corpo da consulta ou mutação GraphQL (campo query do JSON), independentemente de qual operação GraphQL está sendo executada.
- Client ID: Identificador único da sua aplicação no Artia.
- Client Secret: Chave secreta para autenticação da aplicação.
Exemplo de Template para visualizar um projeto
Guia de utilização
Passo a passo para configuração
- Selecionar Operação: O conector Artia possui apenas a operação Query, utilizada tanto para consultas quanto para mutações nas APIs GraphQL do Artia.
- Definir Template: Utilize a aba Template para inserir a consulta ou mutação GraphQL desejada em formato json. Você pode utilizar variáveis e parâmetros para tornar a operação dinâmica.
- Configurar Autenticação: Adicione suas credenciais do Artia (Client ID e Client Secret) nas propriedades do conector.
Exemplo de configuração: Busca de tarefas por projeto
Neste exemplo, efetuaremos uma busca de tarefas de um projeto específico.
Primeiro, adiciono o conector Artia ao canvas. Para isso basta arrastá-lo:
Adiciono o tipo da operação (neste caso Query).
Agora, nas propriedades, também preciso adicionar Client ID e Client Secret, com as credenciais de autenticação do Artia:
Em seguida, navego até Template, agora adiciono a query que quero executar:
Exemplo de query para visualizar um projeto:
{
"query":"query{\n showProject(\n id: 0, \n accountId: 0 \n ) {\n id,\n name,\n status,\n description,\n projectNumber,\n customerName,\n priority,\n estimatedStart,\n estimatedEnd,\n actualStart,\n actualEnd,\n estimatedEffort,\n actualEffort,\n completedPercent,\n responsibleName,\n createdAt,\n updatedAt\n }\n}"
}
Casos de uso práticos
Além de consultas pontuais, o conector Artia costuma ser utilizado em fluxos de sincronização entre a Fluid e um sistema externo (como um ERP), garantindo que registros criados de um lado sejam refletidos e confirmados do outro. Os exemplos a seguir descrevem esse padrão de forma genérica.
Sincronização de projetos com um sistema externo
Um cenário comum é manter projetos sincronizados entre a Fluid e um sistema de gestão externo, evitando duplicidade de registros. O fluxo costuma seguir esta estrutura:
- Consultar no Artia (operação Query) os projetos já existentes.
- Usar um passo Condicional (IF) para verificar se o projeto recebido do sistema externo já existe no Artia.
- Caso não exista, usar um passo For para iterar sobre os projetos pendentes de criação.
- Montar dinamicamente a mutation GraphQL (passo de Template) com os dados de cada projeto.
- Executar essa mutation no conector Artia (operação Query) para criar o projeto.
- Validar o sucesso da operação com um passo Condicional (IF); em caso de falha, direcionar para um passo dedicado de tratamento de erro.
- Confirmar a criação do projeto de volta no sistema externo, chamando o conector correspondente.
- Verificar se essa confirmação foi bem-sucedida, com outro passo Condicional (IF) e um passo de tratamento de erro dedicado para falhas de confirmação.
Esse padrão de "criar e confirmar" é útil quando o sistema externo precisa registrar o ID do projeto gerado no Artia, mantendo rastreabilidade entre os dois sistemas.
Lançamentos no Artia com confirmação externa
Outro cenário recorrente é o envio de lançamentos (por exemplo, apontamentos de horas ou custos de projeto) para o Artia, também com confirmação de volta no sistema de origem. A lógica segue a mesma estrutura do exemplo anterior:
- Consultar os lançamentos existentes no Artia (Query).
- Verificar quais lançamentos ainda não foram criados (Condicional - IF).
- Iterar sobre os lançamentos pendentes (For).
- Montar a mutation com os dados de cada lançamento (Template).
- Criar o lançamento no Artia, executando a mutation no conector (operação Query).
- Verificar o sucesso da criação e, em caso de falha, acionar um passo de erro específico.
- Confirmar o lançamento no sistema de origem e verificar essa confirmação, com tratamento de erro dedicado para falhas de confirmação.
Trate os erros de criação e de confirmação separadamente: um registro pode ser criado com sucesso no Artia, mas falhar na confirmação do sistema externo — são cenários distintos que merecem tratamentos e alertas diferentes.
Melhores práticas
- Utilização de Variáveis: Utilize as respostas de outros passos para criar queries e mutations dinâmicas e poderosas.
- Verifique antes de criar: Em fluxos de sincronização, consulte o Artia (Query) antes de enviar uma mutation de criação, para evitar registros duplicados.
- Separe erros de criação e de confirmação: Quando o fluxo envolve confirmar a operação em outro sistema, trate essas duas falhas em passos distintos.
- Segurança das Credenciais: Mantenha seu Client ID e Client Secret seguros e nunca os exponha em código cliente.
- Retorne o que precisar: Para uma melhor performance, aproveite o poder do GraphQL e defina exatamente os campos que precisará na resposta.
- Tratamento de Erros: Implemente tratamento adequado de erros para cenários de autenticação e autorização.
- Rate Limiting: Respeite os limites de taxa da API do Artia para evitar bloqueios.
Limitações conhecidas
- As credenciais Client ID e Client Secret devem ser válidas e ter as permissões adequadas no Artia
- Algumas operações podem requerer permissões específicas do usuário ou aplicação
- Rate limiting pode ser aplicado dependendo do plano do Artia
Conclusão
O conector Artia simplifica a interação com os serviços GraphQL do Artia, permitindo a realização de consultas e mutações de forma eficiente e configurável. Com uma interface intuitiva, autenticação segura baseada em Client ID/Client Secret, a capacidade de definir templates personalizados e suporte a fluxos de sincronização com sistemas externos, este conector é uma ferramenta poderosa para integrações modernas com a plataforma Artia de gerenciamento de projetos.