Histórico da Página

Informações Gerais

   Legenda: 1 – Inovação 2 – Manutenção (Os demais campos devem ser preenchidos para ambos os processos). 

Objetivo

Descrever os serviços WEB que devem ser disponibilizados pelos produtos TOTVS para monitoramento do EAI (status do serviço, mensagens e configurações).

Definição da Regra de Negócio

Pré-requisitos

Os serviços de monitoramento de EAI disponibilizados pelos produtos deverão atender os seguintes pré-requisitos:

• Plataforma com suporte a REST e autenticação HTTP Basic.
• Suporte a expressões XPath, para pesquisa de conteúdo em documentos XML.
• Suporte a tratamento de cross-domain, por conta das requisições de serviços em servidores de domínio diferente.

Definições gerais dos serviços

Todas as linhas de produto deverão definir uma URL base, a partir da qual os serviços REST do monitor de EAI serão disponibilizados. Todos os caminhos descritos neste documento serão relativos a esta URL base.

As URLs dos serviços - por exemplo, /totvseai/monitor/v1/admin - são compostas pelos seguintes elementos:

• totvseai - designa o contexto dos serviços relacionados ao EAI TOTVS.
• monitor - designa o sub-contexto dos serviços. Neste caso, são os serviços relacionados ao monitoramento. Outro sub-contexto possível seria config, para agrupar serviços de configuração do EAI.
• v1 - descreve a versão dos serviços dentro do sub-contexto. Isso permite a evolução dos serviços, sem quebrar clientes dos serviços de versões anteriores.
• entidade - descreve a entidade que provê os recursos acessados pelo serviço. No caso dos serviços de monitoramento, teremos apps, transactions, msgs, entre outras.

Os retornos dos serviços REST devem estar encapsulados dentro de um objeto JSON com a seguinte especificação:

{
	“messages” : [ { ... }, { ... }, ... ],
	“length” : 999,
	“data” : [{ ... }]
}

Conteúdos de negócio, listas, dados e objetos devem estar contidos dentro do atributo data. O atributo length especifica o tamanho da lista ou a quantidade de dados contida no atributo data; No caso das listas, o atributo length, quando aplicável, contém a quantidade total de itens correspondentes aos parâmetros de pesquisa, e não apenas os que estão contidos no retorno, o que é comum quando há paginação de dados. O atributo messages contém uma lista de mensagens para exibir ao usuário (mensagens de erro ou de negócio). Cada elemento do array será um objeto que obedece a seguinte estrutura:

{
	“code” : “string”,
	“type” : “danger|error|warning|info|success”,
	“detail” : “string”
}

O atributo code representa o código da mensagem. Caso a mensagem possua um detalhamento técnico, este deve constar no atributo detail. O atributo type identifica o tipo de mensagem a ser exibida ao usuário: danger (perigo), error (erro), warning (aviso), info (informação) ou success (sucesso).

Descrição dos serviços do monitor

Os serviços de monitoramento que serão descritos a seguir estão divididos nas seguintes categorias:

• Serviços de administração;
• Serviços de aplicativo;
• Serviços de mensagem;
• Serviços de sumarização de mensagem;
• Serviços de listagem de mensagem;
• Serviços de filtro de mensagem;
• Serviços de mapeamento de valores (“de-para”);

Na descrição de cada serviço podemos encontrar os seguintes elementos:

• Esquema geral da URL do serviço;
• Parâmetros de entrada e saída;
• Descrição do serviço com detalhes relativos ao seu funcionamento;
• Exemplos de uso do serviço, com URLs em situações específicas, e o respectivo retorno.

Âncora
admin admin

Serviços de Administração

GET /totvseai/monitor/v1/admin/context

 O método /totvseai/monitor/v1/admin/context é utilizado para obter informações de contexto de EAI do aplicativo, seja ele interno ou externo. No JSON de retorno, no atributo data, deve constar as seguintes informações:               

• hostAppID: Código do aplicativo interno (host application);
• databaseType: O tipo de banco de dados em uso pelo produto (ORACLE, SQLSERVER, PROGRESS, DB2, MYSQL, etc.);
• productName: Nome do produto instalado (DATASUL, PROTHEUS, RM, LOGIX, etc.);
• productVersion: Versão do produto instalado;
• userCode: código do usuário logado. Corresponde ao identificador único gerado pelo produto, por exemplo, “jose.silva”, “santos001”, etc.;
• userName: nome do usuário logado, por exemplo, “José da Silva”, “Luiz dos Santos”, etc.;
• userEmail: e-mail do usuário logado. Por exemplo: “[email protected]”, “[email protected]”, etc.;
• userDialect: dialeto do usuário logado, utilizado para fins de tradução da interface do usuário (i18n). Por exemplo, “pt-BR”, “es-ES”, “en-US”, etc.;
• userCanMonitor: indica se o usuário logado pode acessar o monitor de EAI (serviços e interface) ou não. Pode ser “true” ou “false”.

Exemplo de JSON de retorno:

{
	“messages” : [],
	“length” : 1,
	“data” : [{
    	“hostAppID” : “app1”,
		“databaseType” : “ORACLE”,
		“productName” : “PROTHEUS”,
		“productVersion” : “12.1.11”,
		“userCode” : “jose.silva”,
		“userName" : “Jose da Silva”,
		“userEmail” : “[email protected]”,
		“userDialect” : “pt-BR”,
		“userCanMonitor” : true
	}]

}

Serviços de Aplicativo

GET /totvseai/monitor/v1/apps/{appID}?page={page}&perPage={perPage}

Este método lista os detalhes do aplicativo solicitado, seja ele interno ou externo. Quando o parâmetro appID é omitido, todos os aplicativos serão considerados. O serviço ainda suporta os seguintes parâmetros:

• page: Indica qual a página de dados desejada. Quando não informado, assume a página 1.
• perPage: Indica a quantidade de registros por página. Quando não informado, assume por padrão 10 registros por página.

Para melhor compreensão do uso dos parâmetros acima, quando for informado algo como ?page=2&perPage=20, o JSON de retorno conterá, no atributo data, os elementos de nr. 21 a 40.

Os dados retornados para um aplicativo são:

• appID: código (identificador único) do aplicativo;
• name: nome (ou descrição resumida) do aplicativo;
• description: descrição longa do aplicativo;
• productCode: nome do produto do aplicativo (PROTHEUS, DATASUL, LOGIX, etc.);
• productVersion: versão do produto do aplicativo;
• isHost: indica se o aplicativo é interno (host application) no contexto que se está pesquisando. Os valores válidos para o atributo são ‘true’ e ‘false’;
• msgValidation: indica a forma de validação das mensagens recebidas e enviadas pelo aplicativo contra os XML Schemas que definem as transações (XSDs). Os valores possíveis para este atributo são:
  • skip: para indicar que não será feita validação;
  • sendOnly: as mensagens serão validadas somente no envio por parte do aplicativo;
  • receiveOnly: as mensagens serão validadas somente no recebimento por parte do aplicativo;
  • always: as mensagens serão validadas sempre que forem recebidas ou enviadas.
  • wsdlUrl: URL usada para conexão ao aplicativo, a qual aponta para o WSDL do serviço de recebimento de mensagens;
  • portName: nome da porta do web service, destinado a receber mensagens;
  • monitorUrl: URL base dos serviços REST de monitoramento no aplicativo. Esta URL será utilizada para obter informações de mensagens no aplicativo, a partir do monitor de outro aplicativo.

O JSON de retorno terá o seguinte formato:

GET /totvseai/v1/monitor/apps

{

       “messages” : [],

       “length” : 2, # total de registros, considerando page=1, perPage=10

       “data” : [{

              “appID“ : “app1”,

              “name” : “Aplicativo 1”,

              “description” : “Nome do aplicativo 1”,

              “productCode” : “DATASUL”,

              “productVersion” : “12.1.11”,

              “isHost” : true,

              “msgValidation” : “skip”,

              “wsdlUrl” : “http://localhost:8080/eai2-ws/EAIService?wsdl”,

              “portName” : “EAI”,

              “monitorUrl” : “http://localhost:8080/”

}, {

              “appID“ : “app2”,

              “name” : “Aplicativo 2”,

              “description” : “Nome do aplicativo 2”,

              “productCode” : “PROTHEUS”,

              “productVersion” : “12.1.9”,

              “isHost” : false,

              “msgValidation” : “sendOnly”,

              “wsdlUrl” : “http://localhost:8180/ws/EAIService.apw?wsdl”,

              “portName” : “EAISERVICESOAP”,

              “monitorUrl” : “http://localhost:8182”

}]

}

GET /totvseai/v1/monitor/apps?page=2&perPage=10

{

       “messages” : [],

       “length” : 0, # não há registros dentro dos critérios informados

       “data” : []

}

GET /totvseai/monitor/v1/apps/app1

{

       “messages” : [],

       “length” : 1,  # Para requisições de um item, não há o que paginar

       “data” : [{

              “appID“ : “app1”,

              “name” : “Aplicativo 1”,

              “description” : “Nome do aplicativo 1”,

              “productCode” : “DATASUL”,

              “productVersion” : “12.1.11”,

              “isHost” : true,

              “msgValidation” : “skip”,

              “wsdlUrl” : “http://localhost:8080/eai2-ws/EAIService?wsdl”,

              “portName” : “EAI”,

              “monitorUrl” : “http://localhost:8080/”

}]

}

GET /totvseai/monitor/v1/apps/inspect-new-app

Este método permite obter dados de um novo aplicativo a partir das propriedades de conexão fornecidas (URL do WSDL, porta WSDL, usuário e senha).

O JSON a ser enviado no corpo da requisição REST (payload), contendo os dados de conexão ao aplicativo, deve ter os seguintes atributos:

• wsdlUrl: URL usada para conectar ao web service do aplicativo.
• portType: porta SOAP usada para conectar ao web service do aplicativo.
• user: código do usuário usado para conectar ao web service do aplicativo.
• password: senha do usuário usado para conectar ao web service do aplicativo.

Exemplo de JSON de envio:

{

       “wsdlUrl” : “http://localhost:8480/EAISERVICE.apw?wsdl”,

       “portType” : “EAISERVICESOAP”,

       “user” : “”,

       “password” : “”

}

O JSON de retorno conterá os dados do aplicativo (código, nome, descrição, entre outros) e suas respectivas transações.

Os dados relativos ao aplicativo seguem o formato definido para o serviço GET /totvseai/monitor/v1/apps, ao qual é adicionado o atributo transactions, um array com as transações disponíveis no aplicativo em questão.

Cada objeto dentro do array transactions terá os seguintes atributos:

• transactionID: Nome da transação;
• version: Versão da transação;
• supportedMode: Modo suportado pela transação, ou seja, são as formas possíveis de uso da mesma. Os valores possíveis são:
  • send_enabled: A transação só pode ser usada no aplicativo para enviar mensagens;
  • receive_enabled: A transação só pode ser usada no aplicativo para receber mensagens;
  • both_enabled: A transação pode ser usada tanto para envio quanto para recebimento de mensagens.
  • enabledMode: Modo habilitado da transação, ou seja, o que de fato está habilitado no momento, que pode ser um dos valores a seguir:
    • send_enabled: indica que a transação, naquele aplicativo, está apenas enviando mensagens. Se o aplicativo receber mensagens dessa transação, elas serão recusadas;
    • receive_enabled: indica que o aplicativo apenas recebe mensagens dessa transação;
    • both_enabled: significando que a transação, naquele aplicativo, está apta a receber e enviar mensagens;
    • not_enabled: a transação não está habilitada no aplicativo.
    • allowAnonymous: indica se a transação pode ser requisitada de aplicativos anônimos, ou seja, que não estejam registrados no aplicativo como aplicativos externos;
    • includeOriginalMsg: indica se a mensagem de resposta de uma transação incluirá o corpo da mensagem original.

Veja exemplo completo do JSON de retorno:

{

       “messages” : [],

       “length” : 1,

       “data” : [{

            “appID“ : “app3”,

              “name” : “Aplicativo 3”,

              “description” : “Nome do aplicativo 3”,

              “productCode” : “LOGIX”,

              “productVersion” : “12.1.8”,

              “isHost” : false,

              “msgValidation” : “always”,

              “wsdlUrl” : “http://localhost:8480/EAISERVICE.apw?wsdl”,

              “portName” : “EAISERVICESOAP”,

              “monitorUrl” : “http://localhost:8481/”,

              “transactions” : [{

                     “transactionID” : “AccountPayable”,

                    “version” : “1.000”,

                    “supportedMode” : “both_enabled”,

                     “enabledMode” : “both_enabled”,

                    “allowAnonymous” : false,

                     “includeOriginalMsg” : false

              }, {

                     “transactionID” : “AccountReceivable”,

                    “version” : “1.003”,

                    “supportedMode” : “both_enabled”,

                     “enabledMode” : “receive_enabled”,

                    “allowAnonymous” : false,

                    “includeOriginalMsg” : false

              }]

       }]

}

GET /totvseai/monitor/v1/apps/{appID}/transactions?page={page}&perPage={perPage}

Este serviço retorna a lista de transações para um aplicativo fornecido. O parâmetro de entrada – appID – deve ser informado na URL da requisição. Adicionalmente outros dois parâmetros podem ser informados:

• page: Indica qual a “página” de dados desejada. Quando não informado, assume a página 1.
• perPage: Indica a quantidade de registros por página. Quando não informado, assume por padrão 10 registros por página.

O JSON de retorno conterá, no atributo data, um array com as transações do aplicativo. A definição dos atributos presentes no retorno é a mesma do serviço anterior, exceto pelo fato que será retornado apenas as transações do aplicativo, não suas propriedades.

Segue JSON de exemplo para o retorno:

GET /totvseai/monitor/v1/apps/app1/transactions

{

       “messages” : [],

       “length” : 3, # implicitamente, page=1, perPage=10

       “data” : [{

             “transactionID” : “order”,

             “version” : “2.000”,

             “supportedMode” : “both_enabled”,

             “enabledMode” : “both_enabled”,

             “allowAnonymous” : false,

             “includeOriginalMsg” : false

       } , {

             “transactionID” : “request”,

             “version” : “1.002”,

             “supportedMode” : “both_enabled”,

             “enabledMode” : “receive_enabled”,

             “allowAnonymous” : false,

             “includeOriginalMsg” : true

       } , {

             “transactionID” : “unitofmeasure”,

             “version” : “1.000”,

             “supportedMode” : “send_enabled”,

             “enabledMode” : “send_enabled”,

             “allowAnonymous” : false,

             “includeOriginalMsg” : true

       }]

}

GET /totvseai/monitor/v1/apps/app1/transactions?page=1&perPage=5

{

       “messages” : [],

       “length” : 3,

       “data” : [{

             “transactionID” : “order”,

             “version” : “2.000”,

             “supportedMode” : “both_enabled”,

             “enabledMode” : “both_enabled”,

             “allowAnonymous” : false,

             “includeOriginalMsg” : false

       } , {

             “transactionID” : “request”,

             “version” : “1.002”,

             “supportedMode” : “both_enabled”,

             “enabledMode” : “receive_enabled”,

             “allowAnonymous” : false,

             “includeOriginalMsg” : true

       } , {

             “transactionID” : “unitofmeasure”,

             “version” : “1.000”,

             “supportedMode” : “send_enabled”,

             “enabledMode” : “send_enabled”,

             “allowAnonymous” : false,

             “includeOriginalMsg” : true

       }]

}

GET /totvseai/monitor/v1/apps/{appID}/transactions/{transactionID}

Este serviço retorna detalhes da transação solicitada, como os contextos e as rotas estabelecidas. É possível que mais de uma versão da transação esteja registrada no aplicativo. Neste caso, todas as versões da transação serão retornadas.

Os dados serão retornados em um array no atributo data. Segue descrição dos atributos dos elementos do array:

• transactionID: nome da transação;
• version: versão da transação;
• contexts: array com os contextos registrados para a transação. Pelo menos o contexto padrão “*” deve constar no atributo. Atualmente, o conceito de contexto está em uso somente no LOGIX e no DATASUL. As demais marcas podem sempre retornar “*” neste atributo.
• routes: array com as rotas estabelecidas. Cada elemento do array tem os seguintes atributos:
  • context: nome do contexto ao qual está vinculada a rota (padrão “*”);
  • destination: nome do aplicativo de destino.

Segue exemplo de JSON de retorno:

GET /totvseai/monitor/v1/apps/app1/transactions/request

{

       “messages” : [],

       “length” : 2,

       “data” : [{

             “transactionID” : “request”,

             “version” : “1.000”,

             “contexts” : [“*”,”CRM”],

             “routes” : [{

                    “context” : “*”,

                    “destination” : “logix11”

             },{

                    “context” : “CRM”,

                    “destination” : “dts12”

             }]

       },{

              “transactionID” : “request”,

             “version” : “2.000”,

             “contexts” : [“*”],

             “routes” : []

       }]

}

Opcional

Protótipo de Tela

<Caso necessário inclua protótipos de telas com o objetivo de facilitar o entendimento do requisito, apresentar conceitos e funcionalidades do software>.

Protótipo 01

Opcional

Fluxo do Processo

<Nesta etapa incluir representações gráficas que descrevam o problema a ser resolvido e o sistema a ser desenvolvido. Exemplo: Diagrama - Caso de Uso, Diagrama de Atividades, Diagrama de Classes, Diagrama de Entidade e Relacionamento e Diagrama de Sequência>. 

Opcional

Dicionário de Dados

Arquivo ou Código do Script: AAA – Negociação Financeira / *Versao=CP.2014.12_03*/

(Opcional)

Grupo de Perguntas

<Informações utilizadas na linha Protheus>.

Nome: FINSRF2

(Opcional)

Consulta Padrão

<Informações utilizadas na linha Protheus>

Consulta: AMB

(Opcional)

Estrutura de Menu

<Informações utilizadas na linha Datasul>.

Procedimentos

Programas

Cadastro de Papéis

<O cadastro de papéis é obrigatório para os projetos de desenvolvimento FLEX a partir do Datasul 10>.

<Lembrete: o nome dos papeis em inglês descrito neste ponto do documento, devem ser homologados pela equipe de tradução>.