Linha de Produto: | T-Reports |
Segmento: | T-Reports |
Módulo: | T-Reports. |
Essa especificação deve ser utilizada como guia para o desenvolvimento de provedores integrados para dados relacionais do T-Reports.
Os endpoints expostos por esses serviços serão chamados automaticamente pela ferramenta T-Reports utilizando para isso o cadastro de provedores de dados localizado no front-end do T-Reports.
A documentação completa dos provedores está disponível em :Provedor de Dados#1
O retorno dos serviços REST dos endpoints descritos abaixo devem estar encapsulados dentro de um objeto JSON com a seguinte especificação:
Mensagens de erro (códigos HTTP 4xx e 5xx retornados no cabeçalho da resposta)
Devem-se retornar obrigatoriamente os campos a seguir:
Exemplo:
|
Devem-se retornar diretamente a entidade que representa o objeto resultado da operação do endpoint.
|
Todas as linhas de produto devem estabelecer uma URL base, a partir da qual os serviços REST de provedor integrado serão disponibilizados.
Como exemplo, no ERP RM foi definida a seguinte URL base:
/api/trep/v1/dbdataproviders/
Essa Url base deve ser informada no cadastro de provedores de dados localizado no front-end do T-Reports no campo "Rota" conforme figura abaixo:
Com o objetivo de facilitar o entendimento do documento, a URL base do RM descrita acima será utilizada no restante do documento para melhor localização dos endpoints. |
Segue abaixo a lista dos serviços REST que devem ser implementados:
Na descrição de cada serviço podemos encontrar os seguintes elementos:
GET /api/trep/v1/dbdataproviders/parameters
Recebe | Não recebe parâmetros |
Retorna | Application/JSON |
Esse método é utilizado para obtenção dos parâmetros do provedor integrado. A necessidade e definição desses parâmetros é de responsabilidade do dono do provedor.
No JSON de retorno, deve constar as seguintes informações:
name: Nome do parâmetro;
name: Nome do parâmetro;
isPassword: Define se o valor do parâmetro será gravado e mostrado de forma criptografada. Pode ser true ou false
{ “providerParams” : [{ “name” : “aliasName”, “description” : “Nome do alias do RM”, “value” : “CorporeRM”, “isPassword” : false, }] } |
Os parâmetros retornados por esse serviço aparecerão na grid de parâmetros localizada no "cadastro de provedores de dados" do front-end do T-Reports, conforme abaixo: |
Serviço de teste de conexão do provedor
POST /api/trep/v1/dbdataproviders/testconnection
Recebe | Application/JSON |
Retorna | Application/JSON |
Esse método é utilizado para testar a conexão de um provedor integrado.
No Json de entrada devem ser enviados os parâmetros cadastrados na tela de "Provedores de dados". Esses parâmetros são os mesmos recuperados pelo serviço definido acima "GET /api/trep/v1/dbdataproviders/parameters".
{ “providerParams” : [{ “name” : “aliasName”, “description” : “Nome do alias do RM”, “value” : “CorporeRM”, “isPassword” : false, }] } |
No JSON de retorno, deve constar as seguintes informações:
testSuccess: Informa se o teste do bem sucedido. Pode ser true ou false
{ “testSuccess” : true; } |
Esse método é utilizado no click do botão "Testar conexão" localizado no "cadastro de provedores de dados" do front-end do T-Reports, conforme abaixo:
c) Serviço de teste de sentenças sql
POST /api/trep/v1/dbdataproviders/testquery
Recebe | Application/JSON |
Retorna | Application/JSON |
Esse método é utilizado para testar a sintaxe de uma sentença sql.
No Json de entrada devem ser enviadas os seguintes informações:
{ “providerParams” : [{ “name” : “aliasName”, “description” : “Nome do alias do RM”, “value” : “CorporeRM”, “isPassword” : false, }], "sqlText": "select * from pfunc where codcoligada = :codcol", "sqlParameters": [{ "paramName": "codcol", "paramValue": "1", "paramType": "system.Int32" }] } |
No JSON de retorno, deve constar as seguintes informações:
testSuccess: Informa se o teste do bem sucedido. Pode ser true ou false
{ “testSuccess” : true; } |
d) Serviço de leitura de schema de tabelas físicas;
GET /api/trep/v1/dbdataproviders/schematable
Recebe | Application/JSON |
Retorna | Application/JSON |
Esse método é utilizado para retornar o schema (estrutura) de uma tabela localizada fisicamente em um determinado provedor de dados.
No Json de entrada devem ser enviadas os seguintes informações:
tablesSourceGetRelations: Lista contendo informações de todas as tabelas físicas cadastradas no dicionário de dados do relatório.
Através dessa lista todos os relacionamentos entre essas tabelas poderão ser recuperados automaticamente no dicionário de dados do ERP em questão, evitando assim, o cadastro manual dos relacionamentos. |
{ “providerParams” : [{ “name” : “aliasName”, “description” : “Nome do alias do RM”, “value” : “CorporeRM”, “isPassword” : false, }], "tableSourceName": "PFUNC", "tablesSourceGetRelations": [ {"tableSourceName": "PSECAO"}, {"tableSourceName": "PFDEPEND"} ] } |
No JSON de retorno, deve constar as seguintes informações:
schemaTable: Objeto contendo as seguinte informações:
{ “schemaTable” : { "tableSourceName": "PFUNC", "tableSourceDescription": "Funcionários", "columns": [ {"columnName": "CODCOLIGADA", "columnDescription": "Codigo da coligada", "columnType": "System.Int32"}, {"columnName": "CHAPA", "columnDescription": "Chapa do funcionario", "columnType": "System.string"}, {"columnName": "SALARIO", "columnDescription": "Salario do funcionário", "columnType": "System.double"}] “relations” : [{ "relationName": "PFUNC_PFDEPEND", "parentSourceName": "PFUNC", "childSourceName": "PFDEPEND", "parentColumns": [{"columnName": "CODCOLIGAGA"}, {"columnName": "CHAPA"}], "childColumns": [{"columnName": "CODCOLIGAGA"}, {"columnName": "CHAPA"}], { "relationName": "PFUNC_PSECAO "parentSourceName": "PFUNC", "childSourceName": "PSECAO, "parentColumns": [{"columnName": "CODCOLIGAGA"}, {"columnName": "CODSECAO}], "childColumns": [{"columnName": "CODCOLIGAGA"}, {"columnName": "CODIGO"}] } } |
Esse método é utilizado na tela de cadastro de entidade do tront-end do reports, ao escolher uma fonte de dados ligada a uma tabela física:
e) Serviço de leitura de schema de sentenças sql;
GET /api/trep/v1/dbdataproviders/schemasql
Recebe | Application/JSON |
Retorna | Application/JSON |
Esse método é utilizado para retornar o schema (estrutura) de uma sentença sql disparada em um determinado provedor de dados.
No Json de entrada devem ser enviadas os seguintes informações:
sqlParameters: Lista de objeto contendo informações dos parâmetros da sentença sql:
paramName: Nome do parâmetro da sentença sql;
{ “providerParams” : [{ “description” : “Nome do alias do RM”, “value” : “CorporeRM”, “isPassword” : false, }], "sqlText": "select * from pfunc where codcoligada = :codcol", "sqlParameters": [{ "paramName": "codcol", "paramValue": "1", "paramType": "system.Int32" }] } |
No JSON de retorno, deve constar as seguintes informações:
schemaSql: objeto contendo as seguinte informações:
Esse método não contêm informações de relacionamento, visto que, trata-se de uma sentença sql. Nesse caso, as informações de relacionamento não poderão ser recuperadas automaticamente de dicionários de dados. |
{ “schemaSql” : { "columns": [ {"columnName": "CODCOLIGADA", "columnDescription": "Codigo da coligada", "columnType": "System.Int32"}, {"columnName": "CHAPA", "columnDescription": "Chapa do funcionario", "columnType": "System.string"}, {"columnName": "SALARIO", "columnDescription": "Salario do funcionário", "columnType": "System.double"}] }, ] |
Esse método é utilizado na tela de cadastro de entidade do tront-end do reports, ao escolher uma fonte de dados ligada a uma sentença sql:
f) - Serviço de leitura de dados;
GET /api/trep/v1/dbdataproviders/data
Recebe | Application/JSON |
Retorna | Application/JSON |
Esse método é utilizado para retornar os dados do relatórios.
No Json de entrada devem ser enviadas as seguintes informações:
entityName: Nome da entidade cadastrada no reports que receberá os dados.
sqlParameters: Lista de objeto contendo informações dos parâmetros da sentença sql:
paramName: Nome do parâmetro da sentença sql;
{ “providerParams” : [{ “description” : “Nome do alias do RM”, “value” : “CorporeRM”, “isPassword” : false, }], "sentenceMember": { "entityName": "Funcionarios", "sqlText": "select * from pfunc where codcoligada = :codcol", "sqlParameters": [{ "paramName": "codcol", "paramValue": "1", "paramType": "system.Int32" }], maxRecords: 10} } |
No JSON de retorno, deve constar as seguintes informações:
entityName: Nome da entidade enviada no parâmetros "entityName" do objeto de request;
Os dados recuperados devem ser retornados no formato xml ou no formato json. É necessário enviar no cabeçalho da resposta o tipo de conteúdo enviado. Content-type = application/xml ou Content-type = application/json |
{ “entityName” :"Funcionarios", "data": "xml ou json contendo o resultado da execução da sentença sql" } |