Fontes de dados de execuções

Dentre todas as fontes de dados existentes, a ferramenta de Scripts conta com quatro delas destinadas às execuções dos artefatos, sejam eles de relatórios ou scripts. Essas fontes estão disponíveis no explorador de fonte de dados, dentro do grupo Fontes de dados da Plataforma para Dados de Execuções.

Cada uma das fontes possui sua função específica, sendo:

• execucoes.busca: busca todas as execuções passando alguns filtros;
• execuções.movimentacoes: retorna as movimentaçẽos de uma execução dado um protocolo de execução;
• execucoes.propriedades: retorna as propriedades de uma execução dado um protocolo de execução;
• parametros.busca: busca as execuções a partir dos dados de seus parâmetros.

Consulta execuções

É uma fonte que consulta as execuções de scripts e relatórios, permitindo visualizar algumas propriedades, como: dados do agendamento, usuário, status, mensagens de inconsistência, endereço dos arquivos gerados e no caso de relatórios, endereços dos arquivos assinados digitalmente.

A fonte disponibiliza uma série de campos para visualização, ordenação e filtros, que estão dispostas nas abas de mesmo nome.

Exemplificando: execução de integração com outro sistema, onde seja necessário enviar os relatórios assinados digitalmente dentro de um período. Essa fonte lhe fornecerá os endereços dos relatórios e demais funcionalidades do script que lhe proverão o restante.

No exemplo abaixo é exibido um script utilizando a fonte mencionada:

Consulta de propriedades de execução

Essa é uma fonte de dados que retorna as propriedades de uma execução, como o formato de exportação do arquivo gerado. Nessa consulta é obrigatório informar o código do protocolo, sendo esse o único filtro disponível.

Exemplificando: determinar o formato de exportação de um determinado arquivo ou se o mesmo foi enviado por e-mail.

No código abaixo é demonstrado um exemplo de uso:

Consulta de movimentações de execução

Essa fonte é semelhante a fonte de consulta de propriedades de execução, porém exibe informações relacionadas aos passos de execução do artefato, bem como métricas de tempo de execução em cada um.

Exemplificando: determinar o tempo que uma execução levou para ocorrer, desde o momento que foi requisitado até ser finalizado.

No código abaixo é demonstrado um exemplo de uso:

Consulta de execuções por parâmetros

Essa fonte é semelhante à fonte de consulta de execuções, porém o retorno das execuções se dará a partir dos parâmetros usados para execução da mesma.

A fonte disponibiliza uma série de campos para visualização, ordenação e filtros, que estão dispostas nas abas de mesmo nome.

Exemplificando: determinar as execuções onde fora fornecido um valor para um parâmetro e o valor seja igual ao desejado.

No código abaixo é demonstrado um exemplo de uso:

API de Gerenciamento de Acessos, Bloqueios e Permissões de Usuários

Esta documentação detalha uma API e fontes de dados projetada para automatizar o gerenciamento de acessos de usuários. Elas possibilitam que sistemas, como o de Folha de Pagamento, possam desativar e gerenciar programaticamente os acessos de um servidor em todos os sistemas licenciados, especialmente em um cenário
de rescisão de contrato.

As funcionalidades permitem:

1. Listar todos os acessos de um usuário em uma entidade.
2. Bloquear (com data de término ou indefinidamente) e desbloquear o acesso de um usuário.
3. Gerenciar permissões granulares, alterando o acesso a funcionalidades específicas (via PageMappings) e a grupos de permissão, sem a necessidade de bloquear o usuário por completo.

Estes recursos estão disponíveis tanto via Endpoints de API (para integrações sistema-a-sistema) quanto via Fontes de Dados no Gerenciador de Scripts.

Para entender a API, imagine o seguinte fluxo de trabalho automatizado quando um funcionário é desligado da organização:

1. Identificação: O sistema de RH identifica o userId do funcionário a ser desligado.
2. Listagem de Acessos: O sistema consome a API para listar todos os accessId associados àquele userId na entidade.
3. Remoção de Permissões (Opcional): Para cada accessId, o sistema pode remover o acesso a grupos específicos ou revogar permissões de módulos sensíveis (como o "Minha Folha").
4. Bloqueio Total: Como passo final, o sistema realiza uma chamada para bloquear permanentemente o userId, garantindo que ele não possa mais acessar nenhum sistema da entidade.

Autenticação e autorização

Os endpoints GET exigem token com scope: aplicacoes.plataforma.betha.cloud/auth/dados/acessos.leitura

Os outros endpoints exigem token com scope: aplicacoes.plataforma.betha.cloud/auth/dados/acessos.escrita

Ambos os casos também aceitam escopo de suite.services porém o uso é restrito para o catálogo de dados e não deve ser utilizado para integrações diretas.

A solicitação para criação dos seguintes tokens deve ser solicitado a equipe de plataforma.

Também é necessário que o UserAccess utilizado seja de um admin no sistema Folha (systemId 33) da entidade a ser gerenciada, todos os endpoints a seguir tem escopo estrito a essa entidade.

Hosts

URL Teste: https://plataforma-autorizacoes-dados.test.betha.cloud/autorizacoes/v0.1/dados/api URL Produção: https://plataforma-autorizacoes-dados.betha.cloud/autorizacoes/v0.1/dados/api

Definição dos endpoints da fonte para bloqueio de acessos por usuário

Erros Gerais

Erros Gerais (aplicados a todos os endpoints)

Código HTTP	Mensagem	Cenário
403	"O acesso utilizado deve ser dos sistema {allowedSystems} para utilizar essa fonte"	Sistema não está na whitelist para funcionalidade de RH (HumanResourcesFilter)
403	(sem mensagem específica)	Usuário não é administrador ou é usuário técnico sem permissão (ManagementRequestFilter)

Formato dos erros

  {
    "message": "O usuário 123456 não foi encontrado."
  }

Endpoint para criação de bloqueio de um acesso

POST /management/access/blocks/block

Exemplo do body esperado na request:

{
    "userId": "joel.filho",
  "systemId": 33,
    "finalDate": "2025-06-30"
}

Dicionário dados:

Nome	Tipo	Observações
userId	String
finalDate	String	Data final do bloqueio no formato yyyy-MM-dd em GMT-3, o envio é opcional, caso não enviado o bloqueio é definido como tempo indeterminado
systemId	Integer

Resposta esperada em caso de sucesso:

Status code: 20O OK

Dicionário Erros

Código HTTP	Mensagem	Cenário
400	"O usuário {userId} não foi encontrado."	Usuário informado não existe no sistema
400	"O usuário {userId} não possui acesso para o sistema {systemId} na entidade {entity} e no banco {database}"	Usuário não tem acesso ao sistema/contexto especificado

Endpoint para buscar bloqueios dos acessos de um usuário

GET /management/access/blocks/{{userId}}/system/{{systemId}}

Exemplo de resposta esperada em caso de sucesso:

Status code: 200 OK

{
    "userId": "joel.filho",
  "entityId": 1,
    "databaseId": 1,
    "systemId": 1,
    "finalDate": "2025-06-30",
    "initialDate": "2025-06-01"
}

Dicionário dados:

Nome	Tipo	Observações
userId	String
finalDate	String	Data final do bloqueio no formato yyyy-MM-dd em GMT-3, o envio é opcional, caso não enviado o bloqueio é definido como tempo indeterminado
initialDate	String	Data inicial do bloqueio no formato yyyy-MM-dd em GMT-3
entityId	Integer
databaseId	Integer
systemId	Integer

Dicionário Erros

Código HTTP	Mensagem	Cenário
404	"O usuário {userId} não foi encontrado."	Usuário informado não existe
404	"O sistema {systemId} não foi encontrado."	Sistema informado não existe
404	"Bloqueio para o usuário {userId} não encontrado."	Não existe bloqueio para o usuário/sistema

Endpoint para atualizar os bloqueios

PATCH /management/access/blocks/{{userId}}/system/{{systemId}}

Exemplo do body esperado na request:

{
    "finalDate": "2025-06-30",
}

Dicionário dados:

Nome	Tipo	Observações
finalDate	String	Data final do bloqueio no formato yyyy-MM-dd em GMT-3, o envio é opcional, caso não enviado o bloqueio é definido como tempo indeterminado

Dicionário Erros

Código HTTP	Mensagem	Cenário
404	"O usuário {userId} não foi encontrado."	Usuário informado não existe
404	"Bloqueio para o usuário {userId} não encontrado."	Não existe bloqueio para atualizar
400	"O usuário {userId} não possui acesso para o sistema {systemId} na entidade {entity} e no banco {database}"	Usuário não tem acesso ao sistema/contexto

Endpoint para desbloquear um usuário

POST /management/access/blocks/unblock

Exemplo do body esperado na request:

{
    "userId": "joel.filho",
  "systemId": 33,
}

Exemplo de resposta esperada em caso de sucesso:

Status code: 20O OK

Dicionário Erros

Código HTTP	Mensagem	Cenário
400	"O usuário {userId} não foi encontrado."	Usuário informado não existe
400	"Bloqueio para o usuário {userId} não encontrado."	Não existe bloqueio para o usuário especificado
400	"O usuário {userId} não possui acesso para o sistema {systemId} na entidade {entity} e no banco {database}"	Usuário não tem acesso ao sistema/contexto

Definição dos endpoints da fonte para listagem de acessos na entidade atual

Endpoint para listagem de acessos na entidade atual

GET /management/access/of-context

Definição dos endpoints da fonte para possibilitar atualizar as permissões de um usuário

Autenticação, autorização e hosts

São as mesmas dos outros endpoints acima

Endpoint para listar acessos de um usuário

GET /acessos

Parâmetros de query:

Nome	Tipo	Obrigatório	Descrição
offset	Int	Não	Índice inicial da paginação.
sort	String	Não	Campo e ordenação, ex: user asc
limit	Int	Não	Quantidade máxima de registros por página.
filter	String	Sim	Filtro para campos, utilize: user = "usuario"
fields	String	Não	Lista de campos que devem ser retornados, separados por vírgula. Ex: id

Exemplo de resposta esperada em caso de sucesso:

Status code: 200 OK

{
  "content": [
    {
      "id": "68234ed379a39cbb7795ced4",
      "user": "teste",
      "userName": "ADRIANA SCHNEIDER DE LIMA"
    }
  ],
  "offset": 0,
  "limit": 100,
  "total": 1,
  "hasNext": false
}

Dicionário de dados:

Nome	Tipo	Observações
id	String	Identificador único do acesso
user	String	Login do usuário
userName	String	Nome completo do usuário
offset	Int	Índice atual de início da lista (para paginação)
limit	Int	Quantidade de registros retornados
total	Int	Total de registros encontrados
hasNext	Bool	Indica se há mais registros além dos retornados na página atual

Dicionário de erros:

Status code	Mensagem	Motivo
400		Requisição mal formatada
500		Erro interno ao processar a requisição

Endpoint para adicionar acesso a um grupo

PUT /acessos/:accessId/groups/:groupId

Parâmetros de path:

Nome	Tipo	Obrigatório	Descrição
accessId	String	Sim	Identificador do acesso
groupId	String	Sim	Identificador do grupo a ser vinculado

Exemplo de requisição:

URL:

PUT /acessos/68234ed379a39cbb7795ced4/groups/6824cd822d70b9000113563e

Body: (nenhum corpo é enviado)

Exemplo de resposta esperada em caso de sucesso:

Status code: 200 OK

// Sem corpo de resposta

Dicionário de erros:

Status code	Mensagem	Motivo
400		Requisição mal formatada ou dados inválidos
404		Acesso ou grupo não encontrado
500		Erro interno ao processar a requisição

Endpoint para remover acesso a um grupo

DELETE /acessos/:accessId/groups/:groupId

Parâmetros de path:

Nome	Tipo	Obrigatório	Descrição
accessId	String	Sim	Identificador do acesso
groupId	String	Sim	Identificador do grupo a ser vinculado

Exemplo de requisição:

URL:

DELETE /acessos/68234ed379a39cbb7795ced4/groups/6824cd822d70b9000113563e

Body: (nenhum corpo é enviado)

Exemplo de resposta esperada em caso de sucesso:

Status code: 200 OK

// Sem corpo de resposta

Dicionário de erros:

Status code	Mensagem	Motivo
400		Requisição mal formatada ou dados inválidos
404		Acesso ou grupo não encontrado
500		Erro interno ao processar a requisição

Endpoint para listar as permissões de um acesso

GET /permissoes

Parâmetros de query:

Nome	Tipo	Obrigatório	Descrição
accessId	String	Sim	Identificador do acesso

Exemplo de requisição:

URL:

GET /permissoes?accessId=68234ed379a39cbb7795ced4

Exemplo de resposta esperada em caso de sucesso:

Status code: 200 OK

[
  {
    "id": "AgenciaBancariaPage",
    "revokedOperations": []
  },
  {
    "id": "ProfissionaisPage",
    "revokedOperations": []
  },
  {
    "id": "OcorrenciaDisciplinarPage",
    "revokedOperations": [
      "atualizar",
      "remover",
      "salvar"
    ]
  },
  {
    "id": "AvisoPrevioPage",
    "revokedOperations": [
      "cancelar",
      "atualizar"
    ]
  }
  // demais páginas omitidas para brevidade
]

Dicionário de dados:

Nome	Tipo	Descrição
id	String	Identificador da página ou funcionalidade
revokedOperations	String[]	Lista de operações revogadas para esse acesso na respectiva funcionalidade

Dicionário de erros:

Status code	Mensagem	Motivo
400		accessId ausente ou malformado
404		Acesso não encontrado
500		Erro interno ao processar a requisição

Endpoint para atualizar as permissões de um acesso

PUT /permissoes/\:accessId

Parâmetros de query:

Nome	Tipo	Obrigatório	Descrição
accessId	String	Sim	Identificador do acesso

Corpo da requisição:

{
  "permissions": [
    {
      "id": "ProfissionaisPage",
      "revokedOperations": []
    }
  ]
}

Resposta esperada:

Status code: 200 OK Body: (sem conteúdo)

---

Dicionário de dados:

Campo	Tipo	Descrição
id	String	Identificador da permissão (geralmente representa uma página funcional)
revokedOperations	Array	Lista de operações revogadas para a permissão. Pode estar vazia

---

Dicionário de erros:

Status code	Mensagem	Descrição
400	-	Requisição malformada ou inválida
404	-	Acesso não encontrado
500	-	Erro interno no servidor

Endpoint para listar grupos pelo id de acesso

GET /grupos/by-access-id/\:accessId

Query Parameters:

Parâmetro	Obrigatório	Descrição
fields	Não	Campos a serem retornados (ex: id,name,createat)
sort	Não	Ordenação (ex: name asc, createat desc)
offset	Não	Posição de início da paginação (padrão: 0)
limit	Não	Quantidade máxima de itens a retornar (padrão: 25)

Exemplo de requisição:

GET /grupos/by-access-id/68234ed379a39cbb7795ced4?fields=id,name,createat&sort=name asc

Resposta:

{
  "content": [
    {
      "id": "6824cd822d70b9000113563e",
      "name": "grupo de teste"
    },
    {
      "id": "68238893fcf750001feb4d9",
      "name": "teste"
    }
  ],
  "offset": 0,
  "limit": 25,
  "hasNext": false
}

---

Dicionário de dados:

Campo	Tipo	Descrição
id	String	ID do grupo vinculado ao acesso
name	String	Nome do grupo
createat	String	Data de criação (se solicitado via fields)

Endpoint para listar permissoes de um grupo

GET /grupos/\:groupId/permissions

Path Parameters:

Parâmetro	Obrigatório	Descrição
groupId	Sim	ID do grupo desejado

Exemplo de requisição:

GET /grupos/6824cd822d70b9000113563e/permissions

Resposta:

[
  {
    "id": "ConfiguracaoDirfPage",
    "revokedOperations": []
  },
  {
    "id": "ConfiguracaoIntegracaoContabilPage",
    "revokedOperations": []
  },
  {
    "id": "ConfiguracaoIntegracaoeSocialPage",
    "revokedOperations": []
  },
  {
    "id": "ConfiguracaoIntegracaoMinhaFolhaPage",
    "revokedOperations": []
  },
  {
    "id": "ConfiguracaoIntegracaoTransparenciaCloudPage",
    "revokedOperations": []
  },
  {
    "id": "ConfiguracaoRaisPage",
    "revokedOperations": []
  }
]

---

Dicionário de dados:

Campo	Tipo	Descrição
id	String	Identificador da permissão (geralmente relacionado à página ou recurso)
revokedOperations	String[]	Lista de operações revogadas para esta permissão no grupo (ex: "atualizar")