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. Para saber mais sobre as Named Queries seguir os seguintes passos:

• Clique aqui para acessar a documentação da TOTVS Plataforma Carol. 
• Clicar na lupa no lado direito superior ao lados das pastas 

Image Added

• Digite a palavra named e clique na primeira opção "Named Queries" conforme abaixo

Image Added

• Após selecionar a opção você será direcionado para a página da documentação.

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 a documentação da Plataforma Carol conforme a seguir:

1. Clique aqui para acessar a documentação da TOTVS Plataforma Carol. 
2. Clique na Aba "Documentação"
3. No Menu a esquerda procure pela opção "Processos Gerais", depois "Autenticação e Login"
4. Na tela ao centro da opção "Autenticação e Login" irá demonstrar a documentação para obter mais detalhes.

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

...

{
  "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:
    • Clique aqui para acessar a documentação da TOTVS Plataforma Carol. 
    • Clique na Aba "Documentação"
    • No Menu a esquerda procure pela opção "Processos Gerais", depois "Autenticação e Login"
    • Na tela ao centro da opção "Autenticação e Login" irá demonstrar a documentação para obter mais detalhes.
  • Consumindo Dados TOTVS Carol: aquiconsulta a documentação "Named Query" na documentação da Plataforma Carol sugerida no item 01.
  • docs.carol.ai
• Consulte o Swagger dentro do seu ambiente:
  
  
  
  
  

...