Histórico da Página

01. VISÃO GERAL 

Este documento tem objetivo apresentar como é possível obter dados de usuários, marcações, funcionários e dispositivos do Clock in utilizando Named Queries.

02. AUTENTICAÇÃO

A Plataforma Carol disponibiliza duas formas de autenticação para uso de rotas privadas para Named Queries: OAuth2 e API Key. Mais detalhes acesse aqui.

03. PAGINAÇÃO

A Plataforma Carol disponibiliza a opção do page size / offset.

...

- curl -X POST 
   'https://api.carol.ai/api/v3/queries/named/<NOME_DA_NAMED_QUERY>
      ?pageSize=-1'
   -H 'X-Auth-Key: <KEY>'
   -H 'X-Auth-ConnectorId: <CON_ID>'

04. FILTROS

Por padrão, Named Queries retornam todos os dados dos Data Models (local onde os dados estão), mas é possível utilizar filtros para obter apenas os dados necessários. No caso abaixo os campos mdmpersonid e mdmname foram utilizados como filtro. Sempre lembrando que os campos do Data Model sempre estão dentro do objeto mdmGoldenFieldAndValues. A Plataforma Carol retorna outros campos que fazem parte da estrutura interna dela mas que não parecem fazer sentido para este caso.

...

- curl -X POST 
   'https://api.carol.ai/api/v3/queries/named/<NOME_DA_NAMED_QUERY>
      ?offset=0
      &pageSize=5
      &fields=mdmGoldenFieldAndValues.mdmpersonid,mdmGoldenFieldAndValues.mdmname'
   -H 'X-Auth-Key: <KEY>'
   -H 'X-Auth-ConnectorId: <CON_ID>'

05. NAMED QUERIES PARA CONSULTA

Para obter a lista completa de Named Queries disponíveis no ambiente, basta entrar em Explore e depois em Named Queries. A lista será apresentada. Nesta área é possível editar, excluir e incluir novas Named Queries. Sempre lembrando que elas vão retornar os registros dos Data Models.  Para saber mais sobre Named Queries acesse aqui. 

05.1. Consulta de Usuários 

- curl -X POST 
   'https://api.carol.ai/api/v3/queries/named/userList
      ?offset=0
      &pageSize=5
      &fields=mdmGoldenFieldAndValues'
   -H 'X-Auth-Key: <KEY>'
   -H 'X-Auth-ConnectorId: <CON_ID>'

- {
  "count": 5,
  "totalHits": 11,
  "took": 12,
  "hits": [
    {
      "mdmGoldenFieldAndValues": {
        "mdmshouldsendwelcomeemail": true,
        "mdmphonenumber": "1232321",
				//....
      }
    },
    {
      "mdmGoldenFieldAndValues": {
        // ...
      }
    },
  ],
  "aggs": {}
}

05.2. Consulta de Marcações

- curl -X POST 
   'https://api.carol.ai/api/v3/queries/named/clockinrecordsListByPeriod
      ?offset=0
      &pageSize=5
      &fields=mdmGoldenFieldAndValues'
   -H 'X-Auth-Key: <KEY>'
   -H 'X-Auth-ConnectorId: <CON_ID>'

Response similar a da consulta de usuários

05.3. Consulta de Funcionários 

- curl -X POST 
   'https://api.carol.ai/api/v3/queries/named/employeeList
      ?offset=0
      &pageSize=5
      &fields=mdmGoldenFieldAndValues'
   -H 'X-Auth-Key: <KEY>'
   -H 'X-Auth-ConnectorId: <CON_ID>'

Response similar a da consulta de usuários

05.4. Consulta de Dispositivo

- curl -X POST 
   'https://api.carol.ai/api/v3/queries/named/deviceList
      ?offset=0
      &pageSize=5
      &fields=mdmGoldenFieldAndValues'
   -H 'X-Auth-Key: <KEY>'
   -H 'X-Auth-ConnectorId: <CON_ID>'

Response similar a da consulta de usuários

05.5. Consulta de Filtros

Para verificar quais são os filtros das Named Queries, basta entrar na área citada anteriormente e executar uma Named Query para testes. Ao executar, a Carol apresentará quais são os filtros. Também é possível adicionar novos filtros. Segue abaixo exemplo de como enviar valores para os filtros via requisições HTTP POST.

...

- curl -X POST 
   'https://api.carol.ai/api/v3/queries/named/<NOME_DA_NAMED_QUERY>
      ?offset=0
      &pageSize=5
      &fields=mdmGoldenFieldAndValues'
   -H 'X-Auth-Key: <KEY>'
   -H 'X-Auth-ConnectorId: <CON_ID>'
   -d '{ "key1": "value1", "key2": "value2" }'

06. EXEMPLO DE USO PARA CONSULTA DE MARCAÇÕES DE PONTO:

Segue abaixo um exemplo prático de como testar e usar uma NAMED QUERY, além de dicas de uso.

06.1. Consultando e testando a NAMED QUERY que pretende usar:

1- Faça Login no seu Ambiente ({organização}.carol.ai/{ambiente});

...

3- No menu lateral esquerdo, também selecione a opção RT;

4- Digite o nome da  NamedQuery NamedQuery que pretende utilizar;

5- De duplo clique sobre o nome e ela será aberta para consulta na tela direita;

6, 7 e 8- No caso desta  NamedQuery NamedQuery (clockinrecordsListByPeriod), ela permite realizar filtros no Data Model CLOCK IN RECORDS usando os campos de código do dispositivo, período de data da marcação de ponto e a partir de qual número NSR;

9- Você pode testar a  NamedQuery NamedQuery pressionando o botão RUN.

1- Preencha os filtros desejados e execute a consulta.

...

Assim pode consultar/exportar os dados retornados da consulta:

06.2. Exemplo da montagem de uma requisição:

• Só passando a   NamedQuery, sem usar filtros

...

• Na documentação acima falamos do offset e pageSize , mas também temos outros query parameters possíveis:
  1. sortBy=mdmGoldenFieldAndValues.mdmeventdate - Conforme já mencionado na documentação acima, os campos do Data Model sempre estão dentro do objeto mdmGoldenFieldAndValues. Neste caso eu decidi organizar os registros pelo mdmeventdate (data da marcação de ponto);
     
     
  2. sortOrder=DESC - Defini que a ordenação será em ordem decrescente, neste caso, da marcação mais atual para mais antiga;
     
     
  3. fields=mdmGoldenFieldAndValues.eventdatestr%2CmdmGoldenFieldAndValues.mdmeventdate - Aqui no fields você pode definir quais campos retornam da na sua consulta, neste caso escolhi só o eventdatestr e o mdmeventdate.

...

{
  "count": 6,
  "totalHits": 6,
  "took": 9,
  "hits": [
    {
      "mdmGoldenFieldAndValues": {
        "eventdatestr": "2024-08-14T17:40:00.000-03:00",
        "mdmeventdate": "2024-08-14T20:40:00.000Z"
      }
    },
    {
      "mdmGoldenFieldAndValues": {
        "eventdatestr": "2024-08-14T17:42:00.000-03:00",
        "mdmeventdate": "2024-08-14T20:42:00.000Z"
      }
    },
    {
      "mdmGoldenFieldAndValues": {
        "eventdatestr": "2024-08-21T08:49:00.000-03:00",
        "mdmeventdate": "2024-08-21T11:49:00.000Z"
      }
    },
    {
      "mdmGoldenFieldAndValues": {
        "eventdatestr": "2024-08-21T08:55:00.000-03:00",
        "mdmeventdate": "2024-08-21T11:55:00.000Z"
      }
    },
    {
      "mdmGoldenFieldAndValues": {
        "eventdatestr": "2024-08-21T08:57:00.000-03:00",
        "mdmeventdate": "2024-08-21T11:57:00.000Z"
      }
    },
    {
      "mdmGoldenFieldAndValues": {
        "eventdatestr": "2024-08-21T12:15:00.000-03:00",
        "mdmeventdate": "2024-08-21T15:15:00.000Z"
      }
    }
  ],
  "aggs": {}
}

06.3. Para mais informações

• Acesse as documentações técnicas já mencionadas acima:
  • Autenticação: aqui.
  • Consumindo Dados TOTVS Carol: aqui.
  • docs.carol.ai
• Consulte o Swagger dentro do seu ambiente:
  
  
  
  
  

...