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

Recebe

Não recebe parâmetros

Retorna

Application/JSON

 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
	}]
}

Âncora
apps apps

Serviços de Aplicativo

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

Recebe

appID   – string – path parameter

page    - int    - query parameter

perPage – int    – query parameter

Retorna

Application/JSON

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 suporta ainda 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;. É o que costuma constar na tag <SourceApplication> da mensagem. Deve conter também o nome do produto no identificador do aplicativo, para evitar conflito de códigos no monitor (usar '@' como separador, por exemplo, 'app1@PROTHEUS').
• 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:

{
    “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”“”
   }]
}

O exemplo abaixo demonstra o uso dos parâmetros page e perPage.

{
	“messages” : [],
	“length” : 0, // não há registros dentro dos critérios informados
	“data” : []
}

Este é um exemplo de busca de dados de um aplicativo específico - 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 GET /totvseai/monitor/v1/apps/inspect-new-app{appID}/transactions?page={page}&perPage={perPage}

Recebe

appID   - string – path parameter

page    - int    - query parameter

perPage – int    – query parameter

Recebe

Application/JSON – form parameters

Retorna

Application/JSON

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).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. Cada objeto dentro do array terá 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}

Recebe

appID   - string – path parameter

page    - int    - query parameter

perPage – int    – query parameter

Retorna

Application/JSON

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.

• 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.

Segue JSON de exemplo para o retorno:

{
	“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
	}]
}

Exemplo de retorno, considerando os parâmetros page e perPage:

{
	“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}

Recebe

appID         - string – path parameter

transactionID - string – path parameter

Retorna

Application/JSON

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:

{
	“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” : []
	}]
}

Âncora
msgs msgs

Serviços de Mensagem

GET /totvseai/monitor/v1/msgs/{msgUUID}?originalMsg={originalMsgUUID}

Recebe

msgUUID - string – path parameter

originalMsgUUID - string - query parameter

Retorna

Application/JSON

Este serviço apenas retorna os dados principais da mensagem informada como parâmetro (UUID, data de geração, data de recebimento, aplicativo de origem, etc.). O conteúdo da mensagem é retornado em outro serviçodata de recebimento, aplicativo de origem, etc.). O conteúdo da mensagem é retornado em outro serviço. O parâmetro opcional originalMsgUUID deve ser informado quando a mensagem a ser obtida for originada de uma outra mensagem (por exemplo, uma ReceiptMessage ou uma ResponseMessage). O método GET /totvseai/monitor/v1/msgs/{msgUUID}/linked-msgs, que retorna as mensagens vinculadas, fornecerá o dado do tipo de mensagem.

Segue descrição de cada atributo retornado no JSON:

• msgUUID: identificador único da mensagem, consistindo num código com o seguinte formato: “aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa”, sendo que “a” representa um caracter numérico (0-9) ou uma letra do alfabeto, distinguindo maiúsculas de minúsculas (aA-zZ);
• sourceApplication: código do aplicativo que enviou a mensagem. O conteúdo deste campo deve obedecer a definição do atributo appID, do serviço GET /totvseai/monitor/v1/apps/{appID}?page={page}&perPage={perPage};
• originalMsgUUID: identificador único da mensagem que originou a mensagem atual, se houver;
• type: tipo da mensagem, que pode ser BusinessMessage, ReceiptMessage ou ReceiveMessage;
• status: situação da mensagem no aplicativo. Indica em qual etapa ela se encontra no fluxo de processamento. Os valores possíveis são:
  • Received: É o estado inicial de uma mensagem. Apenas chegou no destino, mas não foi sequer identificada como uma mensagem TOTVS;
  • Recognized: Quando a mensagem foi “parseada” e reconhecida como uma mensagem TOTVS;
  • Validated: Quando a mensagem foi validada e aceita para seguir o processamento. Algumas validações que colocam a mensagem neste estado são: unicidade do UUID da mensagem e aplicativo de origem da mensagem X mensagens anônimas habilitadas.
  • Delivering: Indica que a mensagem foi encaminhada pra entrega. Geralmente é o status que indica que a mensagem está na fila. Este status só se aplica ao fluxo de envio;
  • Delivered: Indica que a mensagem foi enviada para o destino. Não significa que ela foi processada com sucesso. No caso de mensagens assíncronas, o status mudaria para Delivered ao receber a ReceiptMessage do destino. Aplica-se somente a mensagens no fluxo de envio;
  • Processing: Indica que a mensagem está sendo processada pelo adapter de destino. Isso pode ocorrer tanto para mensagens síncronas, cujo adapter demore um tempo considerável para efetuar tal processamento quanto para mensagens assíncronas, que ficam na fila, aguardando para serem processadas. Este status aplica-se somente ao fluxo de recebimento.
  • Processed: Indica que a mensagem de negócio (BusinessMessage) foi processada sem erros.  Este status, que se aplica somente ao fluxo de recebimento, será opcional para mensagens do tipo ResponseMessage e ReceiptMessage.
  • Refused: Quando, durante o processo de validação, a mensagem não atende aos critérios. Exemplos: mensagem com UUID existente, mensagem recebida de aplicativo não cadastrado.
  • Malformed: Quando, na tentativa de “parsear” a mensagem, ela não se apresenta no formato de mensagem TOTVS;
  • NotDelivered: Quando a mensagem não é enviada ao destino. Os motivos estão relacionados a queda na conexão, erro na transmissão, entre outros. Neste estado, a resposta (ou recibo, no caso de envio assíncrono) não foi gerada pelo destinatário.
  • BusinessError: a mensagem foi enviada e a resposta contém erros.
• transaction: código da transação a qual se refere a mensagem (ex: AccountPayable, Item, Request, UnitOfMeasure, etc.).
• context: Conteúdo que identifica o processo de negócio no qual a mensagem foi gerada. Este atributo permite agrupar mensagens de transações distintas, permitindo, por exemplo, determinar qual processo de negócio gerou determinadas mensagens;
• receivedDateTime: Data e hora em que a mensagem foi recebida no aplicativo. O formato segue o padrão ISO-8601 (ex: 2016-04-14T12:50:00.000-03:00).
• comments: Observações que podem ser registradas pelo engine do EAI durante o processamento da mensagem.
• archived: Indica se a mensagem foi arquivada, ou seja, não deve ser mostrada por padrão ao usuário.
• deliveryType: indica o tipo de envio da mensagem (síncrono ou assíncrono). Os valores possíveis são “Sync” e “Async”.
• Sizesize: tamanho da mensagem, em bytes. Este atributo pode ser utilizado para recuperar o conteúdo da mensagem em partes, caso a mensagem inteira seja grande demais para o canal utilizado.

Segue exemplo de JSON retornado pelo serviço:

{
	“messages” : [ ],
	“length” : 1,
	“data” : [{
		“msgUUID” : “aBcDeFgH-0123-iJkL-4567-mNoPqRsTuVwX”,
		“sourceApplication” : “Instancia_Dts”Dts@DATASUL”,
		“originalMsgUUID” : “”,
		“type” : “BusinessMessage”,
		“status” : “DELIVERED”,
		“transaction” : “Request”,
		“context” : “Requisição de Material”,
		“receivedDateTime” : 2016-04-15T12:54:00.000-03:00,
		“comments” : “”,
		“archived” : false,
		“deliveryType” : “Sync”,
		“size” : 348
	}]
}

GET /totvseai/monitor/v1/msgs/{msgUUID}/content?start={start}&size={size}

Recebe

msgUUID - string  – path parameter

start   – inteiro – query parameter

size    – inteiro – query parameter

Retorna

Application/JSON

Este serviço retorna o conteúdo de uma mensagem informada. Além do código da mensagem (msgUUID), pode-se informar mais dois parâmetros de query:

• start: inteiro que indica o byte inicial do trecho que se deseja recuperar. Deve ser maior que zero e menor ou igual ao tamanho total da mensagem;
• size: inteiro que indica a quantidade de bytes a partir do byte inicial, informado em start. Deve ser maior que zero. Se size for maior que o tamanho total da mensagem, será retornado o trecho restante da mensagem, a partir de start.

O JSON de retorno terá a seguinte estrutura no atributo data:

• msgUUID: identificador único da mensagem requisitada;
• content: conteúdo da mensagem (toda a mensagem ou o trecho solicitado);
• size: tamanho (em bytes) do conteúdo presente no atributo content. Quando o parâmetro size for utilizado na requisição, no atributo length do JSON de retorno deve vir a quantidade de partes nas quais a mensagem pode ser dividida usando o valor em size. Por exemplo: se a mensagem possui 2000 bytes e size é igual a 100, o atributo length virá com o valor 20.

Para retornar o conteúdo completo no JSON de retorno, deve-se requisitar o serviço sem os parâmetros start e size.

Exemplo de requisição de uma mensagem em partes, com cada parte tendo 1000 bytes de tamanho:

{
	“messages” : [ ],
	“length” : 2, // Quantidade de partes da mensagem usando o size informado
	“data” : [{
		“msgUUID” : “f6f725cf‑3012‑bdb2‑0c14‑47427ca9cacf”,
		“content” : “<TOTVSMessage xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../../xmlschema/general/requests/whois_1_000.xsd"><MessageInformation version="1.000"><UUID>f6f725cf-3012-bdb2-0c14-47427ca9cacf</UUID><Type>Response</Type><Transaction>whois</Transaction><StandardVersion>1.0</StandardVersion><SourceApplication>jvd001651</SourceApplication><CompanyId/><Product name="Datasul" version="11.5.X"/><GeneratedOn>2016-03-22T13:26:00.348-03:00</GeneratedOn></MessageInformation><ResponseMessage><ReceivedMessage><SentBy>SoapUI</SentBy><UUID>WhoIsReq-uest-0001-0000-000000000003</UUID></ReceivedMessage><ProcessingInformation><ProcessedOn>2016-03-22T13:26:00.348-03:00</ProcessedOn><Status>OK</Status></ProcessingInformation><ReturnContent><EnabledTransactions><Transaction><Name>carrier</Name><Version>2.000</Version><Mode>SEND_ENABLED</Mode></Transaction><Transaction><Name>city</Name><Version>1.000</Version><Mode>BOTH_ENABLED</Mode></Transaction><Transaction><Name>eai”,
		“size” : 1000
	}]
}

Exemplo contendo a segunda parte da mensagem:

{
	“messages” : [ ],
	“length” : 2, #// Quantidade de partes da mensagem usando o size informado
	“data” : [{
		“msgUUID” : “f6f725cf‑3012‑bdb2‑0c14‑47427ca9cacf”,
		“content” : “environment</Name><Version>1.000</Version><Mode>BOTH_ENABLED</Mode></Transaction><Transaction><Name>getschema</Name><Version>1.000</Version><Mode>BOTH_ENABLED</Mode></Transaction><Transaction><Name>invoice</Name><Version>3.004</Version><Mode>BOTH_ENABLED</Mode></Transaction><Transaction><Name>item</Name><Version>3.001</Version><Mode>BOTH_ENABLED</Mode></Transaction><Transaction><Name>unitofmeasureconversion</Name><Version>1.000</Version><Mode>SEND_ENABLED</Mode></Transaction><Transaction><Name>user</Name><Version>3.001</Version><Mode>SEND_ENABLED</Mode></Transaction><Transaction><Name>warehouse</Name><Version>1.001</Version><Mode>RECEIVE_ENABLED</Mode></Transaction><Transaction><Name>whois</Name><Version>1.001</Version><Mode>BOTH_ENABLED</Mode></Transaction><Transaction><Name>workcenter</Name><Version>1.000</Version><Mode>RECEIVE_ENABLED</Mode></Transaction></EnabledTransactions></ReturnContent></ResponseMessage></TOTVSMessage>”,
		“size” : 941
	}]
}

Exemplo de requisição obtendo todo o conteúdo de uma só vez:

{
	“messages” : [ ],
	“length” : 1,
	“data” : [{
		“msgUUID” : “f6f725cf‑3012‑bdb2‑0c14‑47427ca9cacf”,
		“content” : “<TOTVSMessage xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../../xmlschema/general/requests/whois_1_000.xsd"><MessageInformation version="1.000"><UUID>f6f725cf-3012-bdb2-0c14-47427ca9cacf</UUID><Type>Response</Type><Transaction>whois</Transaction><StandardVersion>1.0</StandardVersion><SourceApplication>jvd001651</SourceApplication><CompanyId/><Product name="Datasul" version="11.5.X"/><GeneratedOn>2016-03-22T13:26:00.348-03:00</GeneratedOn></MessageInformation><ResponseMessage><ReceivedMessage><SentBy>SoapUI</SentBy><UUID>WhoIsReq-uest-0001-0000-000000000003</UUID></ReceivedMessage><ProcessingInformation><ProcessedOn>2016-03-22T13:26:00.348-03:00</ProcessedOn><Status>OK</Status></ProcessingInformation><ReturnContent><EnabledTransactions><Transaction><Name>carrier</Name><Version>2.000</Version><Mode>SEND_ENABLED</Mode></Transaction><Transaction><Name>city</Name><Version>1.000</Version><Mode>BOTH_ENABLED</Mode></Transaction><Transaction><Name>eaienvironment</Name><Version>1.000</Version><Mode>BOTH_ENABLED</Mode></Transaction><Transaction><Name>getschema</Name><Version>1.000</Version><Mode>BOTH_ENABLED</Mode></Transaction><Transaction><Name>invoice</Name><Version>3.004</Version><Mode>BOTH_ENABLED</Mode></Transaction><Transaction><Name>item</Name><Version>3.001</Version><Mode>BOTH_ENABLED</Mode></Transaction><Transaction><Name>unitofmeasureconversion</Name><Version>1.000</Version><Mode>SEND_ENABLED</Mode></Transaction><Transaction><Name>user</Name><Version>3.001</Version><Mode>SEND_ENABLED</Mode></Transaction><Transaction><Name>warehouse</Name><Version>1.001</Version><Mode>RECEIVE_ENABLED</Mode></Transaction><Transaction><Name>whois</Name><Version>1.001</Version><Mode>BOTH_ENABLED</Mode></Transaction><Transaction><Name>workcenter</Name><Version>1.000</Version><Mode>RECEIVE_ENABLED</Mode></Transaction></EnabledTransactions></ReturnContent></ResponseMessage></TOTVSMessage>",
		“size” : 1941
	}]
}

GET /totvseai/monitor/v1/msgs/{msgUUID}/download

Recebe

msgUUID - string – path parameter

Retorna

Application/XML

O serviço download recebe como parâmetro o código da mensagem e retorna o conteúdo da mensagem em formato XML, para download. O corpo da resposta deve conter o XML da mensagem na íntegra, enquanto no cabeçalho da resposta (header), deve constar “Content-disposition = attachment;filename=msg_{msgUUID}.xml” para indicar ao browser que o conteúdo deve ser salvo em arquivo local.

Exemplo de resposta HTTP (cabeçalhos):

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Last-Modified: Thu, 19 Nov 2015 14:16:38 GMT
Content-Type: application/xml
Content-Disposition: attachment; filename=msg_aBcDeFgH-0123-iJkL-4567-mNoPqRsTuVwX.xml
Content-Length: 1941
Date: Mon, 18 Apr 2016 16:56:44 GMT

GET /totvseai/monitor/v1/msgs/{msgUUID}/linked-msgs

Recebe

msgUUID - string – path parameter

Retorna

Application/JSON

Este serviço retorna as mensagens vinculadas a uma mensagem informada, por exemplo, a mensagem de resposta (ResponseMessage) gerada para uma mensagem de negócio (BusinessMessage). O parâmetro recebido – msgUUID – é o identificador único da mensagem para a qual se deseja recuperar os vínculos.

No JSON de retorno constarão os identificadores das mensagens vinculadas.

{
	"messages" : [],
	"length" : 3,
	"data" : [
		"aBcDeFgH-4567-iJkL-4567-mNoPqRsTuVwX",
		"aBcDeFgH-8901-iJkL-4567-mNoPqRsTuVwX",
		"bAdCfEhG-0123-iJkL-4567-mNoPqRsTuVwX"
	]
}

GET /totvseai/monitor/v1/msgs/{msgUUID}/logs?page={page}&perPage={perPage}

Recebe

msgUUID - string – path parameter

page    - int    - query parameter

perPage – int    - query parameter

Retorna

Application/JSON

Este serviço retorna os registros de mudança de estado da mensagem no aplicativo, ou seja, as etapas que a mensagem percorreu durante seu processamento pelo aplicativo interno. Os parâmetros deste serviço são:

• msgUUID: identificador único da mensagem.
• 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.

No JSON de retorno, constarão as entradas de log, dentro de um array no atributo data. Cada elemento do array terá os seguintes atributos:

• msgUUID: identificador único da mensagem;
• sequence: número que indica a sequência de criação da mensagem do log;
• dateTime: data e hora da geração da mensagem de log, seguindo o formato definido no padrão ISO-8601;
• description: texto da mensagem de log;
• level: indica se a mensagem de log é uma informação (INFO) ou se tem o objetivo de diagnosticar problemas (DEBUG).
• userCode: código do usuário logado no momento em que a mensagem de log foi gerada.

Segue exemplo de requisição e o respectivo JSON de retorno:

{
	“messages” : [],
	“length” : 2,
	“data” : [{
	    “msgUUID” : “aBcDeFgH-0123-iJkL-4567-mNoPqRsTuVwX”,
        “sequence” : 1,
        “dateTime” : ”2016-03-17T15:04:26.009-03:00”,
		“description” : ”Status alterado de RECEIVED para RECOGNIZED”,
        “level” : ”INFO”,
		“userCode” : ”super”
	}, {
		“msgUUID” : “aBcDeFgH-0123-iJkL-4567-mNoPqRsTuVwX”,
		“sequence” : 2,
		“dateTime” : ”2016-03-17T15:04:26.023-03:00”,
		“description” : ”Mensagem armazenada na tabela de mensagens sob método de envio Sync”,
		“level” : ”DEBUG”,
		“userCode” : ”super”
	}]
}

Exemplo de requisição usando os parâmetros page e perPage:

{
	“messages” : [],
    “length” : 0, // Não há dados para retornar na página solicitada
    “data” : []
}

GET /totvseai/monitor/v1/msgs/{msgUUID}/logs/download

Recebe

msgUUID - string – path parameter

Retorna

text/plain

Este serviço permite efetuar o download de todas as mensagens de log associadas a uma mensagem, salvando-as em um arquivo .txt.

Para isso, o serviço deve retornar os cabeçalhos “Content-Type: text/plain” e “Content-Disposition: attachment; file=log_{msgUUID}.txt” na resposta da requisição, onde {msgUUID} deve ser substituído pelo valor informado no parâmetro msgUUID.

Exemplo de resposta HTTP, com destaque dos cabeçalhos relacionados ao serviço:

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Last-Modified: Thu, 19 Nov 2015 14:16:38 GMT
Content-Type: text/plain
Content-Disposition: attachment; filename=log_aBcDeFgH-0123-iJkL-4567-mNoPqRsTuVwX.txt
Content-Length: 1941
Date: Mon, 18 Apr 2016 16:56:44 GMT

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>.