Solicitação de Treinamento - trainingNecessity - INTEGRAÇÃO GPEA923API

Sistemas Envolvidos

  • Protheus (módulo Treinamento): Módulo responsável pela gestão de cursos e treinamentos realizados pelos colaboradores.

  • Quírons - NG


Integração

O objetivo desta integração é permitir que o RH ou área responsável pela Gestão de Treinamentos dos Colaboradores no Protheus, receba os dados do Controle de Solicitações de Treinamento dos funcionários de outros sistemas especializados, reduzindo assim o trabalho de inclusão/alteração/exclusão manual dessas informações dentro do sistema;

  • Benefícios
    • Não terá um investimento alto de tempo para o cadastramento, pois os dados já serão enviados, editados ou excluídos através da integração a cada requisição do sistema especialista através da API de Solicitação de Treinamento.
    • A informação será atualizada de forma automática, facilitando que conferência e confiabilidade dos dados recebidos.
  • Arquitetura (Tecnologia)

Toda integração entre o Protheus e o Sistema é feita por intermédio de comunicação direta com os Web Services(que são fixos) REST(Representation State Transfer) utilizando o formato JSON(JavaScript  Object Notation) de serialização de dados, onde através da ativação do serviço do REST do Protheus esteja disponível para utilizar o serviço.

Escopo

Por intermédio desta integração será disponibilizada a seguinte funcionalidade:

  • Manutenção de solicitações de necessidade de treinamento do funcionário no módulo SIGATRM;

Fora do escopo

  • Automatização de consultas de solicitação de treinamento,
  • Importação de base cadastral - dados do Funcionário,
  • Informações da solicitações de treinamento que não se enquadram dentro da tabela de solicitação de treinamento

Pré-requisitos instalação/implantação/utilização

  • Versões mínimas do Protheus: 12.1.23
  • Possuir acesso à Internet, caso o sistema que venha a utilizar a integração com a aplicação Protheus.
  • Estrutura de rede estável, para que haja tráfego de dados sem interrupção.
  • Protheus devidamente configurado e serviço Rest habilitado em seu server.

Instalação/Atualização

Este tópico tem por objetivo orientar a instalação da integração, visando o seu funcionamento completo.

Instalação de produtos ou ferramentas necessárias podem referenciar outros documentos existentes, desde que estejam disponíveis no repositório de documentação da TOTVS ou sejam enviados junto com o documento da integração em si.

As informações mínimas necessárias para este tópico são:

Ativação/Desativação da integração

Por padrão esta integração estará em repositório, porém demanda realizar a devida configuração conforme abaixo:

Controle de Ambiente

Exige que os seguintes pontos sejam revisados:

  • Protheus com sua arquitetura devidamente estruturada.
  • Módulo de Treinamento (SIGATRM) com suas entidades base, devidamente populadas por dados que no momento da integração serão utilizados na criação do registro de solicitação de necessidade de treinamento. (Para melhor compreensão, analise o cadastro disponível dentro do sistema e verifique os campos que possuem consultas em outras tabelas se as mesmas estão com os seus dados devidamente cadastrados).

Controle de Versão

O grupo TOTVS, representado por suas marcas, irá administrar as demandas de evolução dos layouts e demais ajustes, acordando junto aos solicitantes o prazo de liberação de release.

Todas as evoluções programadas deverão ser discutidas e aprovadas pelas marcas antes do início do desenvolvimento e somente serão desenvolvidas em caso de concordância das marcas e alinhamento com as diretivas definidas pelo Comitê de Integração TOTVS.


Suporte

O suporte aos recursos da Integração será de responsabilidade da linha Protheus, onde será analisada pela equipe de suporte da Totvs.

Fluxo das Informações

Esta integração traz a funcionalidade exclusivamente à área de Treinamento, no processo de cadastramento (inclusão/alteração/exclusão) de solicitação de Necessidade de Treinamento.

Cadastro

Esta integração contempla apenas o cadastramento(inclusão/alteração/exclusão) da solicitação de necessidade de treinamento dentro do módulo SIGATRM.

Processos

O Sistema requisitante enviará as informações via json para a interface de integração, desta forma será gerado um novo registro na tabela de solicitações de necessidade de treinamentos no Protheus, caso tenha êxito na geração do registro, será retornada a mesma estrutura de json recebida, acompanhada de uma nova tag chamada id, que será uma chave única composta de informações da entidade dentro do sistema.  Desta forma será confirmada sua gravação, caso contrário enviará as informações de inconsistências que serão citadas nos próximos tópicos.

Limitações / Restrições Gerais

  • Com o objetivo de manter a estrutura e a agilidade da estrutura Rest, o Web Service Rest receberá o registro individual de cada solicitação de treinamento.

Como realizar a chamada da API REST

Para realizar a integração com o parceiro TOTVS são necessárias as informações básicas de consulta para retorno do funcionário desejado.

  • Preenchimento do EndPoint da API TRMA010API;
  • Utilizar a chamada do método Post, Put e Delete e do Serviço trainingNecessity;
  • Preenchimento dos parâmetros obrigatórios da API.




Parâmetros de Entrada POST:

Parâmetro

Valor de Exemplo

Obrigatório

Tipo

Valor Default

Descrição
authorization usuario:senhaSim

header


autenticação é requerida para o funcionamento correto da API em casos de ambientes com autenticação Http Basic.
content

{
"companyId": "T1",
"branchId": "D MG 01 ",
"employeeId": "T1|D MG 01 |160001",
"trainingNecessityCode": "T1|D MG    |0003"
}

Simbody

Estrutura json com informações de necessidade de treinamento:

Propriedades Obrigatórias:

Dados de preparação de ambiente:

  • companyId: Grupo de empresa
  • branchId: Empresa+Unidade de negócio+Filial

Dados de solicitação de treinamento:

  • employeeId: Informação pertinente ao funcionário.
  • trainingNecessityCode: Tipo de treinamento registrado.

Parâmetros e Chamada do Método:

Para a realização de testes foi utilizado a ferramenta POSTMAN e após a configuração do server protheus a API Rest, a  requisição deverá ser semelhante a imagem abaixo:

{protocolo}://{host}/{api}/rh/v1/trainingnecessity



Dados utilizados da API

Por ser uma estrutura única para todas as linhas, cada linha utilizará os campos pertinentes aos seus ambientes.

Propriedade API RESTCAMPO PROTHEUSDESCRIÇÃOFormato
companyId
Informações de acesso ao sistema, campo contém informação do grupo de empresa"T1"
branchIdRA3_FILIALInformações de acesso ao sistema, campo compõe Empresa+Unidade de Negócio+ Filial"D MG 01 "
employeeIdEmpresa|RA_FILIAL|MATChave do funcionário"T1|D MG 01 |000001"

trainingnecessidadecode

Empresa|RA2_FILIAL|RA2_CURSO

Chave do cursoT1|D MG   |001"

Situações Tratadas

O envio de dados inesperados nos parâmetros de entrada da API REST pode ocasionar alguns erros.
Desta forma, foram criados alguns tratamentos de erros, listados abaixo, cada um com sua respectiva mensagem e solução.


Mensagens Validação

Erro

Mensagem

Solução

API RESPONSE
201Registro criado.Registro incluído com sucesso.
{
    "companyId": "T1",
    "branchId": "D MG 01 ",
    "trainingNecessityCode": "T1|D MG    |0001",
    "employeeId": "T1|D MG 01 |160001",
    "id": "T1;D MG 01 ;T1|D MG 01 |160001;T1|D MG    |0001"
}
400Erro na validação do recebimento da mensagem.Verificar se as propriedade json trainingNecessityCode
está preenchida e com dados válidos no pacote enviado ..
{
    "code": 400,
    "detailedMessage": "Erro na validacao do recebimento da mensagem",
    "helpUrl": "https://tdn.totvs.com/x/BJuMHw",
    "message": "Verifique o conteudo da TAG (trainingNecessityCode) pois nao foi possivel encontrar esta informacao no Protheus.\r\n"
}
500

Ocorreu uma falha no retorno da informação.

É necessário avaliar se o servidor está funcionando corretamente.
{
   "errorCode": 500,
   "errorMessage": "Ocorreu uma falha no retorno da informação."
}


OBS: Estas mensagens de validações serão retornadas sempre que algum campo passado que seja obrigatório ou que algum campo enviado tenha sua origem de dados em outra tabela e não seja localizado na mesma, vale lembrar que são apenas exemplos de mensagens de erros e podendo variar o nome da propriedade enviada.


Parâmetros de Entrada PUT:

Parâmetro

Valor de Exemplo

Obrigatório

Tipo

Valor Default

Descrição
authorization usuario:senhaSim

header


autenticação é importante para o funcionamento correto da API em casos de ambientes com autenticação Http Basic.
trainingNecessityId

T1;D MG 01 ;T1|D MG 01 |160001;T1|D MG |0004

Simrequest

Composição da string a ser enviada, deve ser ser composta por "GRUPODEEMPRESA|RA3_FILIAL|CHAVEDOFUNCIOARIO|CHAVEDOCURSO".

contentlayout jsonsimbody

Estrutura json com informações de necessidade de treinamento:

Propriedades Obrigatórias:

Dados de preparação de ambiente:

  • companyId: Grupo de empresa
  • branchId: Empresa+Unidade de negócio+Filial

Dados de solicitação de treinamento:

  • employeeId: Informação pertinente ao funcionário.
  • trainingNecessityCode: Tipo de treinamento registrado.

Parâmetros e Chamada do Método:

Para a realização de testes foi utilizado a ferramenta POSTMAN e após a configuração do server protheus a API Rest, a  requisição deverá ser semelhante a imagem abaixo:

{protocolo}://{host}/{api}/rh/v1/trainingNecessity{trainingNecessityId}



Dados utilizados da API

Por ser uma estrutura única para todas as linhas, cada linha utilizará os campos pertinentes aos seus ambientes.

Propriedade API RESTCAMPO PROTHEUSDESCRIÇÃOFormato
companyId
Informações de acesso ao sistema, campo contém informação do grupo de empresa"T1"
branchIdRA3_FILIALInformações de acesso ao sistema, campo compõe Empresa+Unidade de Negócio+ Filial"D MG 01"
employeeIdRA3_MATChave do Funcionário."T1|D MG 01 |000001"

trainingNecessityCode

RA2_CURSOChave do Curso"T1|D MG |001"

Situações Tratadas

O envio de dados inesperados nos parâmetros de entrada da API REST pode ocasionar alguns erros.
Desta forma, foram criados alguns tratamentos de erros, listados abaixo, cada um com sua respectiva mensagem e solução.


Mensagens Validação

Erro

Mensagem

Solução

API RESPONSE
200Atualizado com sucesso.Registro alterado com sucesso.
{
    "companyId": "T1",
    "branchId": "D MG 01 ",
    "trainingNecessityCode": "T1|D MG    |0001",
    "employeeId": "T1|D MG 01 |160001",
    "id": "T1;D MG 01 ;T1|D MG 01 |160001;T1|D MG    |0001"
}

400

Erro na validação do recebimento da mensagem.

Verificar se as propriedade json trainingNecessityId está preenchida e com dados válidos no pacote enviado.

  1. Dados de Empresa e Filial,
  2. Dados de Filial e Matrícula,
  3. Código do curso;
{
    "code": 400,
    "detailedMessage": "Informação trainingNecessityId ausente ou inválida.",
    "helpUrl": "https://tdn.totvs.com/x/ZYNvI",
    "message": "Erro na validação do recebimento da mensagem."
}
500

Ocorreu uma falha no retorno da informação.

É necessário avaliar se o servidor está funcionando corretamente.
{
   "errorCode": 500,
   "errorMessage": "Ocorreu uma falha no retorno da informação."
}


OBS: Estas mensagens de validações serão retornadas sempre que algum campo passado que seja obrigatório ou que algum campo enviado tenha sua origem de dados em outra tabela e não seja localizado na mesma, vale lembrar que são apenas exemplos de mensagens de erros e podendo variar o nome da propriedade enviada.



Parâmetros de Entrada DELETE:

Parâmetro

Valor de Exemplo

Obrigatório

Tipo

Valor Default

Descrição
authorization usuario:senhaSim

header


autenticação é importante para o funcionamento correto da API em casos de ambientes com autenticação Http Basic.
trainingNecessityId

T1;D MG 01 ;T1|D MG 01 |160001;T1|D MG |0003

Simquery

Composição da string a ser enviada, deve ser ser composta por "GRUPODEEMPRESA|RA3_FILIAL|CHAVEDOFUNCIOARIO|CHAVEDOCURSO".

Parâmetros e Chamada do Método:

Para a realização de testes foi utilizado a ferramenta POSTMAN e após a configuração do server protheus a API Rest, a  requisição deverá ser semelhante a imagem abaixo:

{protocolo}://{host}/{api}/rh/v1/trainingNecessity{trainingNecessityid}

Situações Tratadas

O envio de dados inesperados nos parâmetros de entrada da API REST pode ocasionar alguns erros.
Desta forma, foram criados alguns tratamentos de erros, listados abaixo, cada um com sua respectiva mensagem e solução.


Mensagens Validação

Erro

Mensagem

Solução

API RESPONSE
200Atualizado com sucesso.Registro foi deletado com sucesso.
{
    "code": "200",
    "description": "Opera��o realizada com sucesso!"
}

400

Erro na validação do recebimento da mensagem.

Verificar se as propriedade json trainingNecessityId está preenchida e com dados válidos no pacote enviado.

  1. Dados de Empresa e Filial,
  2. Dados de Filial e Matrícula,
  3. Código do Curso.
{
    "code": 400,
    "detailedMessage": "Informação trainingNecessityId ausente ou inválida.",
    "helpUrl": "https://tdn.totvs.com/x/ZYNvI",
    "message": "Erro na validação do recebimento da mensagem."
}
500

Erro no acesso ao Endpoint.

É necessário avaliar se o servidor está funcionando corretamente.
{
   "errorCode": 500,
   "errorMessage": "Ocorreu uma falha no retorno da informação."
}


OBS: Estas mensagens de validações serão retornadas sempre que algum campo passado que seja obrigatório ou que algum campo enviado tenha sua origem de dados em outra tabela e não seja localizado na mesma, vale lembrar que são apenas exemplos de mensagens de erros e podendo variar o nome da propriedade enviada.


Checklist de suporte da aplicação

Itens a serem verificados durante o atendimento:

  • Verificar se os pré-requisitos foram atendidos para a chamada da API;
  • Verificar se na chamada da API o EndPoint, o nome do serviço e todos os campos obrigatórios foram informados;
  • Verificar se o retorno da API apresenta algum erro tratado (códigos e mensagens de erro citados neste documento) e consultar a solução na mesma tabela que descreve o erro;
  • Em caso de erro não tratado, verificar se possui alguma informação de banco de dados, conexão com o servidor ou algo que possa identificar a origem do problema.


Anexos