ER_FRWJOI01-3_Serviços_para_monitoramento_de_EAI

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 trafegadas e parametrizações em vigor).

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 utilizando versões anteriores dos serviços.
• 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 devem estar contidos dentro do atributo data. Quando houver mais de um elemento, o conteúdo do atributo data deve estar em formato de lista (array) contendo dados primitivos ou objetos. Se o retorno for um único elemento (tipo primitivo ou objeto), não se deve encapsulá-lo num array. O atributo length especifica o tamanho da lista ou a quantidade de dados contida no atributo data. Quando aplicável, o atributo length conterá 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 conterá 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.

Exemplos de chamadas de serviços para atender tarefas de monitoramento específicas podem ser vistos ao final do documento.

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). O produto já consta no JSON de retorno - atributo productName -, logo não precisa ser concatenado ao appID;
• 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;
• login: 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.;
• dialect: 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",
		"login" : "jose.silva",
		"userName" : "Jose da Silva",
		"userEmail" : "[email protected]",
		"dialect" : "pt-BR",
		"userCanMonitor" : true
	}
}

(voltar)

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. O parâmetro appID, quando informado, deve ser fornecido no formato "appID@productCode", já que há implementações de EAI que permitem registrar aplicativos externos com mesmo código identificador. Quando o parâmetro appID for 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) do aplicativo. É o que geralmente consta na tag <SourceApplication> de uma mensagem enviada pelo 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: Campo opcional que contém a 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" : "",
        "isHost" : false,
        "msgValidation" : "",
        "wsdlUrl" : "http://localhost:8180/ws/EAIService.apw?wsdl",
        "portName" : "",
        "monitorUrl" : ""
   }]
}

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/"
	}
}

(voltar)

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 seguindo o formato "appID@productCode". 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á 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.

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

(voltar)

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. O parâmetro appID usado na URL de requisição deve seguir o formato "appID@productCode".

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: código do aplicativo de destino da rota. Deve seguir o formato "appID@productCode".

Segue exemplo de JSON de retorno:

{
	"messages" : [],
    "length" : 2,
    "data" : [{
    	"transactionID" : "request",
        "version" : "1.000",
        "contexts" : ["*","CRM"],
        "routes" : [{
        	"context" : "*",
            "destination" : "logix11@LOGIX"
		},{
        	"context" : "CRM",
            "destination" : "dts12@DATASUL"
		}]
	},{
    	"transactionID" : "request",
        "version" : "2.000",
        "contexts" : ["*"],
        "routes" : []
	}]
}

(voltar)

Serviços de Mensagem

GET /totvseai/monitor/v1/msgs/{msgUUID}?originalMsgUUID={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ç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 caractere 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. Esse dado é necessário quando o provedor de informação não possuir um mecanismo de recuperação direta da mensagem requisitada, necessitando da mensagem original para realizar a busca.
• type: tipo da mensagem, que pode ser businessmessage, receiptmessage ou responsemessage;
• 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 por motivos não relacionados a conexão com o destino. Neste estado, a resposta (ou recibo, no caso de envio assíncrono) não foi gerada pelo destinatário.
  • waiting connection: É um status semelhante ao anterior, mas indica situações onde, após uma tentativa malsucedida de entrega, a mensagem está esperando para ser entregue novamente. Em implementações de EAI onde ocorre o reenvio automático de mensagens em caso de falha, as mensagens deveriam primeiramente receber o status waiting connection e após um determinado número de tentativas, ter o status atualizado para notdelivered.
  • 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.).
• version: versão da transação.
• 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. Quando não informado na mensagem, deve retornar o valor "*" (padrão);
• 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/erros 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".
• size: 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@DATASUL",
		"originalMsgUUID" : "",
		"type" : "businessmessage",
		"status" : "delivered",
		"transaction" : "request",
		"version" : "1.000",
		"context" : "Requisição de Material",
		"receivedDateTime" : 2016-04-15T12:54:00.000-03:00,
		"comments" : "",
		"archived" : false,
		"deliveryType" : "sync",
		"size" : 348
	}
}

(voltar)

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;
• messageFormat: formato do conteúdo da mensagem. Valores disponíveis: "xml" ou "json".
• 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",
		"messageFormat" : "xml"
		"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",
		"messageFormat" : "xml",
		"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",
		"messageFormat" : "xml"		
		"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
	}
}

(voltar)

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

Recebe

msgUUID - string – path parameter

Retorna

Application/XML ou

Application/JSON

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 - XML (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

Exemplo de resposta HTTP - JSON (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/json
Content-Disposition: attachment; filename=msg_aBcDeFgH-0123-iJkL-4567-mNoPqRsTuVwX.json
Content-Length: 1941
Date: Mon, 18 Apr 2016 16:56:44 GMT

(voltar)

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 as mensagens vinculadas completas (no mesmo modelo do serviço /totvseai/monitor/v1/msgs/{msgUUID}.

{
	"messages" : [],
	"length" : 3,   // Quantidade de mensagens vinculadas
	"data" : [{
		"msgUUID": "aBcDeFgH-4567-iJkL-4567-mNoPqRsTuVwX",
		"sourceApplication" : "app1@DATASUL",
		"originalMsgUUID" : "aBcDeFgH-0123-iJkL-4567-mNoPqRsTuVwX",
		"type" : "receiptmessage",
		"status" : "delivered",
		"transaction" : "request",
		"version" : "1.000",
		"context" : "padrao",
		"receivedDateTime" : 2016-04-15T12:54:00.000-03:00,
		"comments" : "",
		"archived" : false,
		"deliveryType" : "sync",
		"size" : 48
	}, {
		"msgUUID": "aBcDeFgH-8901-iJkL-4567-mNoPqRsTuVwX",
		"sourceApplication" : "app1@DATASUL",
		"originalMsgUUID" : "aBcDeFgH-0123-iJkL-4567-mNoPqRsTuVwX",
		"type" : "responsemessage",
		"status" : "notdelivered",
		"transaction" : "request",
		"version" : "1.000",
		"context" : "padrao",
		"receivedDateTime" : 2016-04-15T12:59:21.000-03:00,
		"comments" : "",
		"archived" : false,
		"deliveryType" : "async",
		"size" : 348
	}, {
		"msgUUID": "bAdCfEhG-0123-iJkL-4567-mNoPqRsTuVwX",
		"sourceApplication" : "app1@DATASUL",
		"originalMsgUUID" : "aBcDeFgH-0123-iJkL-4567-mNoPqRsTuVwX",
		"type" : "responsemessage",
		"status" : "delivered",
		"transaction" : "request",
		"version" : "1.000",
		"context" : "padrao",
		"receivedDateTime" : 2016-04-15T13:05:23.000-03:00,
		"comments" : "",
		"archived" : false,
		"deliveryType" : "sync",
		"size" : 348
	}]
}

(voltar)

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" : []
}

(voltar)

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

Exemplo de conteúdo do arquivo de log gerado. Na primeira linha constam o nome das colunas. Os campos são separados por "|".

Sequencia|Data/Hora|Descrição|Nivel|Usuário
1|17/03/2015 03:04:25|Status alterado de RECEIVED para RECOGNIZED|INFO|super
2|17/03/2015 03:04:25|Status alterado de RECOGNIZED para VALIDATED|INFO|super
3|17/03/2015 03:04:25|Status alterado de VALIDATED para PROCESSING|INFO|super
4|17/03/2015 03:04:25|Status alterado de PROCESSING para PROCESSED|INFO|super
5|17/03/2015 03:04:25|Mensagem armazenada no banco de dados|DEBUG|super

(voltar)

Serviços de sumarização de mensagens

GET /totvseai/monitor/v1/msgs/summary/sending?category={category}&date={date}&transactions={transactions}&deliveryType={deliveryType}&context={context}

Recebe

category     - string – query parameter

date         – string – query parameter

transactions – string – query parameter

deliveryType – string – query parameter

context      - string – query parameter

Retorna

Application/JSON

Este serviço retorna a quantidade de mensagens originadas do aplicativo interno. São consideradas neste serviço as mensagens com tipo igual a BusinessMessage, cujo aplicativo de origem seja o aplicativo interno. Os totais serão discriminados conforme os status de mensagem abrangidos pela categoria escolhida. Desta forma, o "consumidor" do serviço poderá utilizar os totais desta maneira, ou somar os totais para obter um "grande" total.

Segue descrição dos parâmetros:

• category: indica a etapa do processo de envio em que as mensagens se encontram. Quando o parâmetro for omitido, serão consideradas todas as mensagens que estão sendo ou que já foram enviadas. Os valores aceitos para este parâmetro são:
  • in-process: serão consideradas as mensagens cujo envio ainda não foi concluído (e não apresentou erro), representadas pelos status received, recognized, validated e delivering.
  • success: serão consideradas as mensagens cujo envio foi realizado com sucesso (status delivered).
  • error: serão consideradas as mensagens cujo envio apresentou erro, ou seja, cujo status seja malformed, refused, notdelivered ou businesserror.
• date: Indica um intervalo de data de criação de mensagens a considerar. Se o parâmetro for omitido, a data de criação não será usada como critério. O parâmetro permite as seguintes variações:
  • YYYY-MM-DD:YYYY-MM-DD: Define um intervalo com data de início e fim fixos, separadas por ":" (dois pontos).
  • YYYY-MM-DD: Indica que o intervalo tem apenas data de início fixo. A data de término é a data corrente.
  • :YYYY-MM-DD: Indica que o intervalo tem apenas data de término fixa. Todos os registros com data de criação menor ou igual a data de término serão considerados.
• transactions: indica uma lista de transações (transactionIDs) a considerar. Os elementos da lista serão separados por ";" (ponto-e-virgula). Por exemplo: "accountantaccount;invoice;item". Se o parâmetro for omitido, serão consideradas todas as transações.
• deliveryType: Quando informado, indica que o tipo de entrega será considerado como critério. Os valores possíveis são "sync" (enviadas de forma síncrona) e "async" (enviadas de forma assíncrona).
• context: Quando informado, contabiliza todas as mensagens que possuírem na tag <ContextName> o valor fornecido. Quanto for informado "*" (asterisco), contabiliza todas as mensagens sem contexto, ou utilizando o contexto padrão.

Seguem alguns exemplos de retorno, de acordo com a URL usada para acionar o serviço. O exemplo abaixo totaliza as mensagens enviadas, com categoria "in-process":

{
	"messages" : [],
	"length" : 4,
	"data" : [{
	    "status" : "received",
        "total" : 0
    },{
        "status" : "recognized",
        "total" : 1
    },{
        "status" : "validated",
        "total" : 3
    },{
        "status" : "delivering",
        "total" : 2
	}]
}

O exemplo a seguir retorna o total de mensagens enviadas com status na categoria "success".

{
	"messages" : [],
    "length" : 1,
    "data" : [{
    	"status" : "delivered",
        "total" : 10
	}]
 }

Exemplo de retorno para mensagens enviadas com status na categoria "error".

{
    "messages" : [],
    "length" : 4,
    "data" : [{
        "status" : "malformed",
        "total" : 0
    },{
        "status" : "refused",
        "total" : 2
	},{
        "status" : "notdelivered",
        "total" : 2
	},{
        "status" : "businesserror",
        "total" : 7
	}]
}

Requisição de totalização de mensagens enviadas onde, além da categoria de status (in-process), é informado o período de criação das mensagens e a lista de transações a considerar.

{
	"messages" : [],
    "length" : 4,
    "data" : [{
	    "status" : "received",
        "total" : 0
    },{
        "status" : "recognized",
        "total" : 0	
	},{
        "status" : "validated",
        "total" : 0
	},{
        "status" : "delivering",
        "total" : 0
	}]
}

Exemplo de requisição para totalização de mensagens enviadas, com status na categoria "success", criadas a partir de 20/03/2016, cujo tipo de entrega é síncrono e as transações sejam "request" ou "order".

{
	"messages" : [],
    "length" : 1,
    "data" : {
	    "status" : "delivered",
        "total" : 20
    }]
}

(voltar)

GET /totvseai/monitor/v1/msgs/summary/receiving?category={category}&sourceApp={sourceApp}&date={date}&transactions={transactions}&deliveryType={deliveryType}&context={context}

Recebe

category     - string – query parameter

sourceApp    – string – query parameter

date         – string – query parameter

transactions – string – query parameter

deliveryType – string – query parameter

context      - string – query parameter

Retorna

Application/JSON

Este serviço retorna a quantidade de mensagens provenientes de outros aplicativos. São consideradas neste serviço as mensagens com tipo igual a BusinessMessage, cujo aplicativo de origem seja diferente do aplicativo interno. Os totais serão discriminados conforme os status de mensagem abrangidos pela categoria escolhida. Desta forma, o "consumidor" do serviço poderá utilizar os totais desta maneira, ou somar os totais para obter um "grande" total.

Segue descrição dos parâmetros:

• category: indica a etapa do processo de recebimento em que as mensagens se encontram. Quando o parâmetro for omitido, serão consideradas todas as mensagens que estão sendo ou que já foram recebidas. Os valores aceitos para este parâmetro são:
  • in-process: serão consideradas as mensagens cujo recebimento ainda não foi concluído (e não apresentou erro), representadas pelos status received, recognized, validated e processing.
  • success: serão consideradas as mensagens cujo recebimento foi realizado com sucesso (status processed).
  • error: serão consideradas as mensagens cujo recebimento apresentou erro, ou seja, cujo status seja malformed, refused, notdelivered ou businesserror.
• sourceApp: indica o aplicativo de origem (appID) cujas mensagens devem ser consideradas. Quando omitido, não será usado como critério de contabilização. O conteúdo deve ser informado conforme definido para o atributo appID no método GET /totvseai/monitor/v1/apps/{appID}?page={page}&perPage={perPage}.
• date: Indica um intervalo de data de criação de mensagens a considerar. Se o parâmetro for omitido, a data de criação não será usada como critério de contabilização. O parâmetro permite as seguintes variações:
  • YYYY-MM-DD:YYYY-MM-DD: Define um intervalo com data de início e fim, separadas por ":" (dois pontos).
  • YYYY-MM-DD: Indica que o intervalo tem apenas data de início. A data de término é a data corrente.
  • :YYYY-MM-DD: Indica que o intervalo tem apenas data de término. Todos os registros com data de criação menor ou igual a data de término serão considerados.
• transactions: indica uma lista de transações (transactionIDs) a considerar. Os elementos da lista serão separados por ";" (ponto-e-virgula). Por exemplo: "accountantaccount;invoice;item". Se o parâmetro for omitido, serão consideradas todas as transações.
• deliveryType: Quando informado, indica que o tipo de entrega será considerado como critério. Os valores possíveis são "sync" (enviadas de forma síncrona) e "async" (enviadas de forma assíncrona).
• context: Quando informado, contabiliza todas as mensagens que possuírem na tag <ContextName> o valor fornecido. Quanto for informado "*" (asterisco), contabiliza todas as mensagens sem contexto, ou utilizando o contexto padrão.

Seguem alguns exemplos de retorno, de acordo com a URL usada para acionar o serviço:

{
	"messages" : [],
    "length" : 4,
    "data" : [{
	    "status" : "received",
        "total" : 3
    },{
        "status" : "recognized",
        "total" : 2
	},{
        "status" : "validated",
        "total" : 5
	},{
        "status" : "processing",
        "total" : 3
	}]
}

{
	"messages" : [],
    "length" : 1,
    "data" : [{
 	   "status" : "processed",
       "total" : 2
    }]
}

{
	"messages" : [],
	"length" : 4,
    "data" : [{
		"status" : "malformed",
		"total" : 2
    },{
        "status" : "refused",
        "total" : 1
	},{
		"status" : "notdelivered",
        "total" : 4
	},{
        "status" : "businesserror",
        "total" : 3
	}]
}

{
	"messages" : [],
	"length" : 4,
	"data" : [{
	    "status" : "received",
        "total" : 1
	},{
        "status" : "recognized",
        "total" : 0
	},{
        "status" : "validated",
        "total" : 2
	},{
        "status" : "processing",
        "total" : 1
	}]
}

{
	"messages" : [],
    "length" : 1,
    "data" : [{
	    "status" : "processed",
        "total" : 4
    }]
}

(voltar)

GET /totvseai/monitor/v1/msgs/summary/transactions/{transactionID}?sourceApp={sourceApp}&date={date}&deliveryType={deliveryType}&status={status}&msgflow={msgFlow}&context={context}&page={page}&perPage={perPage}&groupByVersion={groupByVersion}

Recebe

transactionID – string – path parameter

sourceApp     – string – query parameter

date          – string – query parameter

deliveryType  – string – query parameter

status        – string – query parameter

msgflow       - string – query parameter

context       - string – query parameter

page          - int    - query parameter

perPage       - int    - query parameter

groupByVersion - booleano - query parameter

Retorna

Application/JSON

Este serviço permite obter a quantidade de mensagens por transação. Na totalização serão consideradas somente as mensagens do tipo BusinessMessage.

Os parâmetros aceitos pelo serviço são os descritos a seguir:

• transactionID: Identificador da transação para a qual se deseja contabilizar as mensagens. Este parâmetro é opcional e quando não informado, indica ao serviço que todas as transações devem ser consideradas.
• sourceApp: identificador do aplicativo (appID) para o qual se deseja contabilizar as mensagens. Pode ser omitido, o que significa que as mensagens de todos os aplicativos serão contabilizadas. Quando infromado, seu conteúdo deve estar em conformidade com a descrição do atributo appID no método GET /totvseai/monitor/v1/apps/{appID}?page={page}&perPage={perPage}.
• date: Permite indicar um intervalo de data de criação de mensagem, onde apenas mensagens neste intervalo serão contabilizadas. O parâmetro permite as seguintes variações:
  • YYYY-MM-DD:YYYY-MM-DD: Indica um intervalo com data inicial e final, separadas por ":".
  • YYYY-MM-DD: indica um intervalo onde apenas a data inicial é informada. A data final assumida será a data corrente.
  • :YYYY-MM-DD: indica um intervalo onde apenas a data final é informada. Todas as mensagens com data de criação menor ou igual a data informada serão consideradas.
• deliveryType: indica o tipo de entrega informado que será usado como critério para a contabilização das mensagens. Pode-se informar "sync" (para mensagens síncronas) ou "async" (para mensagens assíncronas).
• status: permite informar uma lista de status a considerar na contabilização das mensagens. Os elementos da lista são separados por ";". Por exemplo: "received;validated;delivered".
• msgflow: quando informado, permite indicar se serão consideradas na totalização as mensagens enviadas (sending) ou as recebidas (receiving). Considera-se como enviadas as mensagens com aplicativo origem igual ao aplicativo interno, e recebidas as mensagens com aplicativo origem diferente do aplicativo interno.
• context: Quando informado, contabiliza todas as mensagens que possuam na tag <ContextName> o valor fornecido. Quanto for informado "*" (asterisco), contabiliza todas as mensagens sem contexto, ou utilizando o contexto padrão.
• page: permite indicar a página de dados que se deseja recuperar. O parâmetro é opcional, e quando não informado, deve assumir o valor 1.
• perPage: permite indicar a quantidade de registros por página de dados. O parâmetro é opcional, e quando não for informado, deve assumir o valor 10.
• groupByVersion: parâmetro opcional que permite indicar se o retorno do serviço considerará os totais por transação e versão (parâmetro = true), ou apenas por transação (parâmetro = false). Quando não informado, deve assumir o valor "true".

Abaixo tem-se alguns exemplos de requisição com os respectivos retornos:

{
	"messages" : [],
    "length" : 3, // Implicitamente, assume page=1 e perPage=10
    "data" : [{
	    "transaction" : "customervendor",
		"version": "1.000",
		"total" : 120
    },{
        "transaction" : "request",
		"version": "2.000",
		"total" : 23
    },{
        "transaction" : "userofmeasure",
		"version": "3.000",
		"total" : 78
    }]
}

{
	"messages" : [],
    "length" : 10, // Quantidade total de transações no servidor
    "data" : [{
	    "transaction" : "unitofmeasure",
		"version": "3.000",
		"total" : 12
    },{
        "transaction" : "getharvestorder",
		"version": "1.000",
		"total" : 21
    },{
        "transaction" : "customervendor",
		"version": "1.000",
		"total" : 34
    },{
        "transaction" : "item",		// Implicitamente, groupByVersion = true
		"version": "1.003",
		"total" : 29
    },{
        "transaction" : "item",
		"version": "2.000",
		"total" : 7
    }]
}

{
	"messages" : [],
    "length" : 1,
    "data" : [{
	    "transaction" : "accountantaccount", 
		"total" : 120	// Corresponde à soma das versões de accountantaccount (2.000 e 2.001)
    }]
}

{
	"messages" : [],
    "length" : 2,
    "data" : [{
	    "transaction" : "accountantaccount",
		"version": "2.000",
		"total" : 10
 	},{
		"transaction" : "accountantaccount",
		"version": "2.001",
		"total" : 5
	}]
}

(voltar)

GET /totvseai/monitor/v1/msgs/summary/applications/{appID}?date={date}&deliveryType={deliveryType}&status={status}&transactions={transactions}&msgflow={msgflow}&context={context}&page={page}&perPage={perPage}

Recebe

appID        – string – path parameter

date         – string – query parameter

deliveryType – string – query parameter

status       – string – query parameter

transactions - string – query parameter

msgflow      - string – query parameter

context      - string – query parameter

page         - int    - query parameter

perPage      - int    - query parameter

Retorna

Application/JSON

Este serviço permite obter a quantidade de mensagens por aplicativo, tanto as enviadas quanto as recebidas. Na totalização serão consideradas somente as mensagens do tipo BusinessMessage.

Os parâmetros aceitos pelo serviço são os descritos a seguir:

• appID: Identificador do aplicativo para a qual se deseja contabilizar as mensagens. Este parâmetro é opcional e quando não informado, indica ao serviço que todos os aplicativos devem ser considerados. Se informado, seu conteúdo deve estar em conformidade com o definido para o atributo appID no método GET /totvseai/monitor/v1/apps/{appID}?page={page}&perPage={perPage}.
• date: Permite indicar um intervalo de data de criação de mensagem, onde apenas mensagens neste intervalo serão contabilizadas. O parâmetro permite as seguintes variações:
  • YYYY-MM-DD:YYYY-MM-DD: Indica um intervalo com data inicial e final, separadas por ":";
  • YYYY-MM-DD: indica um intervalo onde apenas a data inicial é informada. A data final assumida será a data corrente;
  • :YYYY-MM-DD: indica um intervalo onde apenas a data final é informada. Todas as mensagens com data de criação menor ou igual a data informada serão consideradas.
• deliveryType: indica o tipo de entrega informado que será usado como critério para a contabilização das mensagens. Pode-se informar "sync" (para mensagens síncronas) ou "async" (para mensagens assíncronas);
• status: permite informar uma lista de status a considerar na contabilização das mensagens. Os elementos da lista são separados por ";". Por exemplo: "received;validated;delivered";
• transactions: permite informar uma lista de transações (transactionIDs) a considerar na contabilização das mensagens. Os elementos da lista são separados por ";". Por exemplo: "request;order;user";
• msgflow: quando informado, permite indicar se as mensagens enviadas (sending) ou as mensagens recebidas (receiving) serão contabilizadas. Mensagens recebidas são as que possuem aplicativo de origem diferente do aplicativo interno. Mensagens enviadas são aquelas cujo aplicativo origem é igual ao aplicativo interno;
• context: Quando informado, contabiliza todas as mensagens que possuírem na tag <ContextName> o valor fornecido. Quanto for informado "*" (asterisco), contabiliza todas as mensagens sem contexto, ou utilizando o contexto padrão.
• page: permite indicar a página de dados que se deseja recuperar. O parâmetro é opcional, e quando não informado, deve assumir o valor 1.
• perPage: permite indicar a quantidade de registros por página de dados. O parâmetro é opcional, e quando não for informado, deve assumir o valor 10.

Abaixo tem-se alguns exemplos de requisição com os respectivos retornos, onde o atributo identificador do aplicativo - appID - deve estar no formato "appID@productCode":

{
	"messages" : [],
    "length" : 3,
    "data" : [{
	    "appID" : "app1@DATASUL",
        "total" : 240
    },{
        "appID" : "app2@PROTHEUS",
        "total" : 130
    },{
        "appID" : "app3@RM",
        "total" : 102
    }]
}

{
	"messages" : [],
	"length" : 1,
    "data" : [{
	    "appID" : "app1@DATASUL",
        "total" : 120
	}]
}

{
	"messages" : [],
	"length" : 1,
	"data" : [{
		"appID" : "app2@PROTHEUS",
		"total" : 3
	}]
}

{
	"messages" : [],
    "length" : 9,  // Quantidade total de registros no servidor
    "data" : [{
	    "appID" : "app1@DATASUL",
        "total" : 240
    },{
        "appID" : "app2@PROTHEUS",
        "total" : 130
    },{
        "appID" : "app3@RM",
        "total" : 67
    },{
        "appID" : "app4@LOGIX",
        "total" : 82
    },{
        "appID" : "app5@RM",
        "total" : 124
    }]
}

(voltar)

GET /totvseai/monitor/v1/msgs/summary/contexts/{context}?date={date}&deliveryType={deliveryType}&status={status}&transactions={transactions}&msgflow={msgflow}&page={page}&perPage={perPage}&sourceApp={sourceApp}

Recebe

context      – string – path parameter

date         – string – query parameter

deliveryType – string – query parameter

status       – string – query parameter

transactions - string – query parameter

msgflow      - string – query parameter

page         - int    - query parameter

perPage      - int    - query parameter

sourceApp    - string - query parameter

Retorna

Application/JSON

Este serviço permite obter a quantidade de mensagens por contexto, tanto as enviadas quanto as recebidas. Na totalização serão consideradas somente as mensagens do tipo BusinessMessage.

Os parâmetros aceitos pelo serviço são os descritos a seguir:

• context: Conteúdo que indica o contexto de negócio (processo) a pesquisar nas mensagens. Este parâmetro é opcional e quando não informado, indica ao serviço que todos os contextos devem ser considerados. Quanto for informado "*" (asterisco), contabiliza todas as mensagens sem contexto, ou utilizando o contexto padrão;
• date: Permite indicar um intervalo de data de criação de mensagem, onde apenas mensagens neste intervalo serão contabilizadas. O parâmetro permite as seguintes variações:
  • YYYY-MM-DD:YYYY-MM-DD: Indica um intervalo com data inicial e final, separadas por ":";
  • YYYY-MM-DD: indica um intervalo onde apenas a data inicial é informada. A data final assumida será a data corrente;
  • :YYYY-MM-DD: indica um intervalo onde apenas a data final é informada. Todas as mensagens com data de criação menor ou igual a data informada serão consideradas.
• deliveryType: indica o tipo de entrega informado que será usado como critério para a contabilização das mensagens. Pode-se informar "sync" (para mensagens síncronas) ou "async" (para mensagens assíncronas);
• status: permite informar uma lista de status a considerar na contabilização das mensagens. Os elementos da lista são separados por ";". Por exemplo: "received;validated;delivered";
• transactions: permite informar uma lista de transações (transactionIDs) a considerar na contabilização das mensagens. Os elementos da lista são separados por ";". Por exemplo: "request;order;user";
• msgflow: quando informado, permite indicar se as mensagens enviadas (sending) ou as mensagens recebidas (receiving) serão contabilizadas. Mensagens recebidas são as que possuem aplicativo de origem diferente do aplicativo interno. Mensagens enviadas são aquelas cujo aplicativo origem é igual ao aplicativo interno.
• page: permite indicar a página de dados que se deseja recuperar. O parâmetro é opcional, e quando não informado, deve assumir o valor 1.
• perPage: permite indicar a quantidade de registros por página de dados. O parâmetro é opcional, e quando não for informado, deve assumir o valor 10.
• sourceApp: permite indicar o aplicativo de origem a considerar na contabilização das mensagens. O parâmetro é opcional, e quando informado, deve estar no formato "appID@productName". Quando não informado, deve-se considerar mensagens de qualquer aplicativo de origem.

O JSON de retorno terá os totais por contexto, encontrados entre as mensagens pesquisadas. Veja exemplos:

{
	"messages" : [],
	"length" : 3,
	"data" : [{
		"context" : "Requisição de materiais",
		"total" : 3
	},{
		"context" : "",
		"total" : 20
	},{   
		"context" : "*",
		"total" : 10
	}]
}

{
	"messages" : [],
	"length" : 8,    // Quantidade total de registros no servidor
	"data" : [{
		"context" : "Requisição de materiais",
		"total" : 3
	},{
		"context" : "Padrão",
		"total" : 20
	},{   
		"context" : "Financeiro",
		"total" : 8
	},{   
		"context" : "Pedido de venda",
		"total" : 15
	},{   
		"context" : "CRM",
		"total" : 7
	}]
}

{
	"messages" : [],
	"length" : 1,
	"data" : [{
		"context" : "Pedido de Venda",
		"total" : 10
	}]
}

(voltar)

Serviço de listagem de mensagens

GET /totvseai/monitor/v1/msgs/list?sourceApp={sourceApp}&status={status}&date={date}&msgtypes={msgtypes}&transactions={transactions}&content={content}&page={page}&perPage={perPage}&orderBy={orderBy}&msgflow={msgflow}&context={context}

Recebe

sourceApp    – string – query parameter

status       – string – query parameter

date         – string – query parameter

msgtypes     – string – query parameter

transactions – string – query parameter

content      – string – query parameter

page         - int    - query parameter

perPage      - int    - query parameter

orderBy      - string – query parameter

msgflow      - string – query parameter

context      - string – query parameter

Retorna

Application/JSON

Este serviço visa listar as mensagens que atendam aos critérios fornecidos pelos parâmetros descritos a seguir:

• sourceApp: Parâmetro opcional que, quando informado, indica que apenas mensagens originárias do aplicativo informado (appID) serão listadas. O atributo deve ser fornecido no formato "appID@productCode";
• status: Parâmetro opcional que, quando informado, provê uma lista de status que as mensagens devem possuir para serem selecionadas. Os elementos da lista são separados por ";’. Exemplo: "received;delivering;delivered";
• date: Parâmetro opcional que permite selecionar as mensagens dentro de um intervalo de data de criação. É permitido informar o intervalo conforme segue:
  • YYYY-MM-DD:YYYY-MM-DD: indica um intervalo com data inicial e data final, separadas por ":". Por exemplo: "2016-04-01:2016-05-01";
  • YYYY-MM-DD: indica um intervalo onde apenas a data de início é informada. A data final, neste caso, será a data corrente;
  • :YYYY-MM-DD: indica um intervalo onde apenas a data final é informada. Serão consideradas mensagens com data de criação menor ou igual a data informada no intervalo.
• msgtypes: Parâmetro opcional que permite informar a lista de tipos de mensagem a considerar na listagem. Os tipos que podem ser usados são: businessmessage, responsemessage e receiptmessage. Os elementos da lista são separados por ";". Exemplo: "businessmessage;responsemessage";
• transactions: Parâmetro opcional que permite informar a lista de transações (transactionIDs) presentes nas mensagens para serem consideradas na listagem. Os elementos da lista são separados por ";". Exemplo: "unitofmeasure;request;order";
• content: Parâmetro opcional que conterá um texto livre, para ser pesquisado em todo o conteúdo do XML, ou uma expressão XPath a ser usada para selecionar as mensagens, baseada no seu conteúdo XML. Para diferenciar o texto livre da expressão XPATH, esta ultima deve vir precedida da string "xpath:".
  A expressão XPath é um padrão de linguagem para recuperação de informações em um documento XML, sendo recomendado pelo W3C. Para mais informações sobre XPath, consultar os links a seguir:
  • http://www.w3schools.com/xsl/xpath_intro.asp.
  • https://en.wikipedia.org/wiki/XPath.
  • https://www.w3.org/TR/xpath/.

Como um exemplo, a expressão XPath para selecionar uma mensagem da transação Order cujo OrderId seja igual a 200 seria a seguinte:

   /TotvsMessage/BusinessMessage/BusinessContent[OrderId=200]

Ou ainda:

   //BusinessContent[OrderId=200]

• page: indica a página de dados desejada;
• perPage: indica a quantidade de registros por página;
• orderBy: indica a lista de campos, entre os retornados no JSON, que serão usados para ordenar os elementos no conjunto total de mensagens encontradas pelo serviço. Os elementos da lista serão separados por ";". Para ordenação decrescente informar como último elemento a string "DESC". Exemplo: "msgUUID;DESC";
• msgflow: quando informado, indica que serão listadas as mensagens enviadas (sending) ou as mensagens recebidas (receiving). Considera-se como mensagens enviadas aquelas cujo aplicativo origem é o aplicativo interno. Já as mensagens recebidas são aquelas cujo aplicativo origem é diferente do aplicativo interno.
• context: Quando informado, considera todas as mensagens que possuírem na tag <ContextName> o valor fornecido. Quanto for informado "*" (asterisco), contabiliza todas as mensagens sem contexto, ou utilizando o contexto padrão.

A respeito dos parâmetros page, perPage e orderBy, cabem algumas informações complementares. Os três parâmetros são opcionais, sendo assumidos os seguintes valores defaults:

• page = 1;
• perPage = 10;
• orderBy = msgUUID, ascendente.

A pesquisa será realizada com os critérios fornecidos pelos parâmetros, o que resultará em um conjunto de mensagens selecionadas ordenado conforme o parâmetro orderBy. Sobre este conjunto serão aplicados os parâmetros page e perPage. Desta forma, uma pesquisa com page = 2, perPage = 10 e orderBy = "transaction" que, pelos demais parâmetros, resulte em 300 mensagens, retornará no JSON as mensagens classificadas por transação, tendo como 1º elemento a 11ª mensagem e como último elemento a 20ª mensagem.

Abaixo um exemplo geral de JSON de retorno. O modelo de dados retornado é o mesmo do método GET /totvseai/monitor/v1/msgs/{msgUUID}?originalMsgUUID={originalMsgUUID}.

{
	"messages" : [],
	"length" : 300, // quantidade total de mensagens da pesquisa
	"data" : [{
		"msgUUID" : "aBcDeFgH-0123-iJkL-4567-mNoPqRsTuVwX",
		"sourceApplication" : "app1@DATASUL",
		"originalMsgUUID" : "",
		"type" : "businessmessage",
		"status" : "delivered",
		"transaction" : "request",
		"version" : "2.001",
		"context" : "Requisição de materiais",
		"receivedDateTime" : "2016-04-15T12:54:00.000-03:00",
		"comments" : "",
		"archived" : false,
		"deliveryType" : "sync",
		"size" : 348
	},{
		"msgUUID" : "mNoPqRsT-0123-iJkL-4567-aBcDeFgHuVwX",
		"sourceApplication" : "app2@PROTHEUS",
		"originalMsgUUID" : "aBcDeFgH-0123-iJkL-4567-mNoPqRsTuVwX",
		"type" : "responsemessage",
		"status" : "delivered",
		"transaction" : "request",
		"version" : "2.001",		
		"context" : "Requisição de materiais",
		"receivedDateTime" : "2016-04-15T12:59:05.000-03:00",
		"comments" : "",
		"archived" : false,
		"deliveryType" : "sync",
		"size" : 125
	},{
		"msgUUID" : "aBcDeFgH-4567-iJkL-0123-mNoPqRsTuVwX",
		"sourceApplication" : "app2@PROTHEUS",
		"originalMsgUUID" : "",
		"type" : "businessmessage",
		"status" : "delivered",
		"transaction" : "order",
		"version" : "2.005",
		"context" : "Pedido de compra",
		"receivedDateTime" : "2016-04-16T09:40:00.000-03:00",
		"comments" : "",
		"archived" : false,
		"deliveryType" : "async",
		"size" : 1020
	}]
}

(voltar)

Serviços de filtro de mensagens

POST /totvseai/monitor/v1/filters

Recebe

filter data – Application/JSON – payload

Retorna

Application/JSON

Este serviço permite salvar os filtros que o usuário realizar na interface do monitor, para utilização futura. O mesmo filtro será utilizando quando o usuário estiver consultando registros no aplicativo interno e no aplicativo externo.

O serviço recebe um JSON com os dados do filtro a incluir, conforme descrito abaixo:

• filterId: identificador único do filtro, pelo qual o mesmo será requisitado em outros serviços. O atributo, se estiver em branco, será preenchido no momento da criação do filtro no servidor. Se for informado, será utilizado o conteúdo do atributo, desde que não esteja em uso.  O formato sugerido para o atributo é "userCode-YYYY-MM-DD-hh-mm-ss", onde "userCode" é o conteúdo do atributo userCode, descrito logo abaixo; "YYYY-MM-DD" corresponde a data de criação do filtro e "hh-mm-ss" corresponde à hora, minuto e segundo de criação do filtro.
• userCode: código do usuário ao qual o filtro está vinculado;
• description: descrição resumida do filtro;
• items: estrutura com os critérios de seleção que compõem o filtro. Segue descrição dos atributos:
  • appID: identificador único do aplicativo de origem das mensagens a selecionar. O conteúdo deste atributo deve estar em conformidade com a definição do atributo appID no método GET /totvseai/monitor/v1/apps/{appID}?page={page}&perPage={perPage}.
  • status: lista com os status que devem constar nas mensagens a selecionar. Os elementos da lista são separados por ";". Por exemplo: "received;recognized;validated;delivering";
  • date: intervalo de criação das mensagens a selecionar. Neste atributo é possível informar o intervalo conforme segue:
    • YYYY-MM-DD:YYYY-MM-DD : período com data de início e término definidos. Serão consideradas as mensagens criadas dentro deste intervalo;
    • YYYY-MM-DD : período onde a data de início é informada. Serão consideradas mensagens com data de criação maior ou igual a data de início informada e menor ou igual a data de hoje;
    • :YYYY-MM-DD : período onde apenas a data de término é informada. Serão consideradas mensagens com data de criação menor ou igual a data de término.
    • today: indica um período móvel onde será considerada apenas a data corrente.
    • week: indica um período móvel onde serão considerados todos os registros com data no intervalo entre hoje e sete dias atrás. Por exemplo, sendo a data corrente 10/05/2017, serão considerados os registros no intervalo entre 04/05/2017 e 10/05/2017.
    • twoweeks: indica um período móvel onde serão considerados todos os registros com data no intervalo entre hoje e catorze dias atrás. Por exemplo, sendo a data corrente 10/05/2017, serão considerados os registros no intervalo entre 27/04/2017 e 10/05/2017.
    • month: indica um período móvel onde serão considerados todos os registros com data no intervalo entre hoje e trinta dias atrás. Por exemplo, para a data de 10/05/2017, serão considerados os registros com data entre 11/04/2017 e 10/05/2017.
  • msgtypes: lista dos tipos de mensagem que devem constar nas mensagens a selecionar. Os elementos da lista são separados por ";". Por exemplo: "BusinessMessage;ResponseMessage";
  • transactions: lista das transações (transactionID) que devem constar nas mensagens a selecionar. Os elementos da lista são separados por ";". Por exemplo: "order;invoice;user";
  • context: Contexto (processo) ao qual a mensagens pertence. Corresponde ao conteúdo da tag <ContextName>. Quanto for informado "*" (asterisco), contabiliza todas as mensagens sem contexto, ou utilizando o contexto padrão.
  • content: Texto livre ou expressão XPath que permite selecionar as mensagens por conteúdo. A expressão está relacionada às tags XML das mensagens e será precedida pela string "xpath:" para diferenciar de um texto livre.

O JSON abaixo exemplifica o conteúdo a ser enviado para o serviço:

{
	"filterId" : "",
	"userCode" : "user001",
	"description" : "my filter description",
	"items" : {
		"appID" : "app1@DATASUL",
		"status" : "businesserror;notdelivered;refused;malformed",
		"date" : "2016-04-01:2016-04-20",
		"msgtypes" : "responsemessage",
		"transactions" : "order;user;unitofmeasure",
		"context" : "Pedidos",
		"content" : "xpath://ListOfMessage/Message[@type='error']"
	}
}

O JSON de retorno conterá, no atributo data, o JSON do filtro com o filterId atualizado, caso seja enviado em branco, ou o conteúdo informado na requisição, caso não esteja em uso.

{
	"messages" : [],
	"length" : 1,
	"data" : {
		"filterId" : "user001-2016-04-26-15-48-01",
		"userCode" : "user001",
		"description" : "my filter description",
		"items" : {
			"appID" : "app1@DATASUL",
			"status" : "businesserror;notdelivered;refused;malformed",
			"date" : "2016-04-01:2016-04-20",
			"msgtypes" : "responsemessage",
			"transactions" : "order;user;unitofmeasure",
			"context" : "Compras",
			"content" : "xpath://ListOfMessage/Message[@type='error']"
		}
	}
}

(voltar)

PUT /totvseai/monitor/v1/filters/{filterId}

Recebe

filterId – string – path parameter

Filter data – Application/JSON - payload

Retorna

Application/JSON

Este serviço permite modificar um filtro já cadastrado. Para isso, será enviado uma nova versão do JSON correspondente ao filtro informado no parâmetro filterId. Com exceção dos atributos filterId e userCode, todos os demais podem ser alterados. O formato do JSON enviado e do JSON de retorno é o mesmo descrito no serviço POST /totvseai/monitor/v1/filters.

GET /totvseai/monitor/v1/filters/{filterId}

Recebe

filterId – string – path parameter.

Retorna

Application/JSON

Recupera os dados do filtro com o filterId informado, os quais serão retornados no atributo data do JSON de retorno.

{
	"messages" : [],
	"length" : 1,
	"data" : {
		"filterId" : "user001-2016-04-26-15-48-01",
		"userCode" : "user001",
		"description" : "my filter description",
		"items" : {
			"appID" : "app1@DATASUL",
			"status" : "businesserror;notdelivered;refused;malformed",
			"date" : "2016-04-01:2016-04-20",
			"msgtypes" : "responsemessage",
			"transactions" : "order;user;unitofmeasure",
			"content" : "error"
		}
	}
}

(voltar)

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

Recebe

page    – int – query parameter

perPage – int – query parameter

Retorna

Application/JSON

Este serviço permite recuperar todos os filtros salvos no aplicativo. Os dados retornados são paginados, e sua recuperação é controlada pelos parâmetros page e perPage.

• page: indica o número da página de dados a recuperar. Quando não for informado, assume o valor 1.
• perPage: indica a quantidade de registros por página. Quando não for informado, assume 10 registros por página como padrão.

Segue exemplo de retorno do serviço:

{
	"messages" : [],
	"length" : 2,
	"data" : [{
		"filterId" : "user001-2016-04-26-15-48-01",
		"userCode" : "user001",
		"description" : "my filter description",
		"items" : {
			"appID" : "app1@DATASUL",
			"status" : "businesserror;notdelivered;refused;malformed",
			"date" : "2016-04-01:2016-04-20",
			"msgtypes" : "responsemessage",
			"transactions" : "order;user;unitofmeasure",
			"content" : "xpath://ListOfMessage/Message[@type='error']"
		}
	}, {
		"filterId" : "user002-2016-04-26-15-30-10",
		"userCode" : "user002",
		"description" : "messages OK this month",
		"items" : {
			"appID" : "",
			"status" : "delivered",
			"date" : "2016-04-01:2016-04-30",
			"msgtypes" : "businessmessage",
			"transactions" : "",
			"content" : ""
		}
	}]
}

(voltar)

GET /totvseai/monitor/v1/filtersbyuser/{userCode}?page={page}&perPage={perPage}

Recebe

userCode – string – path parameter

page     – int    - query parameter

perPage  – int    – query parameter

Retorna

Application/JSON

Recupera os filtros de um usuário, informado no parâmetro userCode. O serviço suporta paginação das informações retornadas, através dos parâmetros page e perPage.

• page: permite informar a página de dados desejada. Se for omitido, assume a página 1 por padrão.
• perPage: permite informar a quantidade de registros por página. Se for omitido, assume 10 registros por página.

O retorno do serviço listará os filtros do usuário, seguindo os parâmetros de paginação. Veja exemplo:

{
	"messages" : [],
	"length" : 1,
	"data" : {
		"filterId" : "user001-2016-04-26-15-48-01",
		"userCode" : "user001",
		"description" : "my filter description",
		"items" : {
			"appID" : "app1@DATASUL",
			"status" : "businesserror;notdelivered;refused;malformed",
			"date" : "2016-04-01:2016-04-20",
			"msgtypes" : "responsemessage",
			"transactions" : "order;user;unitofmeasure"
			"content" : "xpath://ListOfMessage/Message[@type='error']"
		}
	}
}

(voltar)

DELETE /totvseai/monitor/v1/filters/{filterId}

Recebe

filterId – string – path parameter

Retorna

Application/JSON

Remove um filtro cadastrado, identificado pelo parâmetro filterId. O retorno será o próprio filterId, caso a exclusão ocorra com sucesso.

{
	"messages" : [],
	"length" : 1,
	"data" : {
		"filterId": "user001-2016-04-26-15-48-01"
    }
}

(voltar)

Serviços de mapeamento de valores ("de-para")

GET /totvseai/monitor/v1/mappings/definitions/{mappingID}?page={page}&perPage={perPage}

Recebe

mappingID - string – path parameter

page      – int    – query parameter

perPage   – int    – query parameter

Retorna

Application/JSON

Este serviço retorna a definição (estrutura) do "de-para" informado – mappingID (também conhecido como "internalID") –, no contexto do aplicativo interno. Estas definições visam orientar o registro dos valores de "de-para" no aplicativo. Quando não for informado o parâmetro mappingID, serão retornadas todas as definições de "de-para" registradas.

Além do mappingID, o serviço aceita os seguintes parâmetros:

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

O JSON de retorno do serviço conterá, no atributo data, os seguintes campos:

• mappingID: é o identificador único do "de-para" ou "internalID". Por exemplo, "AccountantAccountInternalId", "RequestInternalId", etc.
• table: é o nome da tabela, no banco de dados, à qual o "de-para" faz referência. Por exemplo: "emitente", "nota-fiscal", "ped-venda", etc.
• fields: é a lista dos campos, na tabela referenciada, que serão usados na composição do "de-para". Os campos são separados entre si por "|" (pipe). Exemplos: "cod-emitente", "cnpj-emit|cd-serie|nr-nf", "cod-estab|nr-ped-venda", etc.

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

{
	"messages" : [],
	"length" : 1,
	"data" : [{
		"mappingID" : "AccountantAccountInternalID",
		"table" : "conta-contabil",
		"fields" : "cod-conta|cod-subconta"
	}]
}

{
	"messages" : [],
	"length" : 13, // total de registros existentes
	"data" : [{
		"mappingID" : "AccountantAccountInternalID",
		"table" : "conta-contabil",
		"fields" : "cod-conta|cod-subconta"
	},{
		"mappingID" : "CustomerVendorInternalID",
		"table" : "emitente",
		"fields" : "cod-emitente"
	},{
		"mappingID" : "InvoiceInternalID",
		"table" : "nota-fiscal",
		"fields" : "cnpj-emit|cd-serie|nr-nf"
	}]
}

(voltar)

GET /totvseai/monitor/v1/mappings/values/{mappingID}?page={page}&perPage={perPage}

Recebe

mappingID – string – path parameter

page      – int    – query parameter

perPage   – int    – query parameter

Retorna

Application/JSON

Este serviço retorna os valores de "de-para" registrados no aplicativo para o identificador fornecido – mappingID (ou internalID). Quando não for informado, serão retornados todos os valores de "de-para" registrados.

Além do mappingID, o serviço aceita os seguintes parâmetros:

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

O serviço retorna um JSON onde, no atributo data, constará um array com objetos contendo os seguintes atributos:

• mappingID: é o identificador único do "de-para" ou "internalID". Por exemplo, "AccountantAccountInternalId", "RequestInternalId", etc. Deve ser o mesmo valor retornado no serviço GET /totvseai/monitor/v1/mappings/definitions.
• table: é o nome da tabela, no banco de dados, à qual o "de-para" faz referência. Por exemplo: "emitente", "nota-fiscal", "ped-venda", etc.
• internalValue: é o valor do internalID no aplicativo interno. Os valores são gravados de acordo com a definição presente no campo "fields" (ver descrição dos atributos do retorno do serviço GET /totvseai/monitor/v1/mappings/definitions/{mappingID}). Os valores dos campos são separados entre si por "|".
• externalApp: identificador do aplicativo externo com o qual o "de-para" está associado. O conteúdo deve estar em conformidade com o padrão "appID@productCode". Porém, quando o serviço retornar "@productCode" (sem o appID como prefixo), deve-se considerar os valores de de-para para qualquer aplicativo que tenha o mesmo "productCode".
• externalValue: é o valor do internalID no aplicativo externo. Este é o valor de pesquisa usado para determinar a chave equivalente no aplicativo interno.

Segue exemplo de JSON de retorno:

{
	"messages" : [],
	"length" : 4, 
	"data" : [{
		"mappingID" : "AccountantAccountInternalID",
		"table" : "conta-contabil",
		"internalValue" : "00001|00000001",
		"externalApp" : "logix11@LOGIX",
		"externalValue" : "00001-00001"
	}, {
		"mappingID" : "AccountantAccountInternalID",
		"table" : "conta-contabil",
		"internalValue" : "00001|00000002",
		"externalApp" : "logix11@LOGIX",
		"externalValue" : "00001-00002"
	}, {
		"mappingID" : "AccountantAccountInternalID",
		"table" : "conta-contabil",
		"internalValue" : "00001|00000005",
		"externalApp" : "logix11@LOGIX",
		"externalValue" : "00001-00005"
	}, {
		"mappingID" : "AccountantAccountInternalID",
		"table" : "conta-contabil",
		"internalValue" : "00002|00000002",
		"externalApp" : "logix11@LOGIX",
		"externalValue" : "00002-00002"
	}]
}

{
	"messages" : [],
	"length" : 18, // Quantidade total de registros
	"data" : [{
		"mappingID" : "AccountantAccountInternalID",
		"table" : "conta-contabil",
		"internalValue" : "00001|00000001",
		"externalApp" : "logix11@LOGIX",
		"externalValue" : "00001-00001"
	}, {
		"mappingID" : "InvoiceInternalID",
		"table" : "nota-fiscal",
		"internalValue" : "123456789000112|UN|12345",
		"externalApp" : "logix11@LOGIX",
		"externalValue" : "123456789000112|UN|000123456"
	}, {
		"mappingID" : "CustomerVendorInternalID",
		"table" : "emitente",
		"internalValue" : "23456",
		"externalApp" : "logix11@LOGIX",
		"externalValue" : "ABC001"
	}, {
		"mappingID" : "CustomerVendorInternalID",
		"table" : "emitente",
		"internalValue" : "999888",
		"externalApp" : "logix11@LOGIX",
		"externalValue" : "XYZ001"
	},{
		"mappingID" : "AccountantAccountInternalID",
		"table" : "conta-contabil",
		"internalValue" : "00001|00000001",
		"externalApp" : "logix11@LOGIX",
		"externalValue" : "00001-00001"
	}, {
		"mappingID" : "AccountantAccountInternalID",
		"table" : "conta-contabil",
		"internalValue" : "00001|00000002",
		"externalApp" : "logix11@LOGIX",
		"externalValue" : "00001-00002"
	}, {
		"mappingID" : "AccountantAccountInternalID",
		"table" : "conta-contabil",
		"internalValue" : "00001|00000005",
		"externalApp" : "logix11@LOGIX",
		"externalValue" : "00001-00005"
	}, {
		"mappingID" : "AccountantAccountInternalID",
		"table" : "conta-contabil",
		"internalValue" : "00002|00000002",
		"externalApp" : "logix11@LOGIX",
		"externalValue" : "00002-00002"
	}]
}

(voltar)

Tarefas de monitoramento X serviços do monitor

O objetivo desta seção é demonstrar como cumprir tarefas de monitoramento do EAI através dos serviços disponibilizados.  A tarefa é descrita como tópico principal, e os passos para cumpri-la são descritos como subtópicos.

Os seguintes "placeholders" são utilizados nas URLs abaixo:

<URL_monitor_local>: Refere-se à URL base dos serviços REST de monitoramento na instalação do aplicativo interno.

<URL_monitor_externo>: Refere-se à URL base dos serviços REST de monitoramento na instalação do aplicativo externo.

1. Verificar se um aplicativo externo está ativo:
   1. GET <URL_monitor_local>/totvseai/monitor/v1/apps/<id_aplicativo_externo>, para obter a URL base dos serviços REST de monitor do aplicativo externo.
   2. GET <URL_monitor_externo>/totvseai/monitor/v1/admin/context, para obter os dados do aplicativo externo. Se o retorno for o JSON esperado, o aplicativo externo está ativo.
2. Listar os dados do aplicativo interno:
   
   1. GET <URL_monitor_interno>/totvseai/monitor/v1/admin/context, para obter o atributo hostAppID, que identifica o aplicativo interno.
   2. GET <URL_monitor_local>/totvseai/monitor/v1/apps/<hostAppID>, para obter os dados do aplicativo interno.
3. Listar as transações do aplicativo interno:
   
   1. GET <URL_monitor_local>/totvseai/monitor/v1/apps/<hostAppID>/transactions, para obter as transações do aplicativo.
4. Listar os aplicativos externos de um aplicativo:
   
   1. GET <URL_monitor_local>/totvseai/monitor/v1/apps?page=1&perPage=100, para obter os 100 primeiros aplicativos cadastrados no produto.
   2. Se o atributo length do JSON de retorno da 1ª requisição for maior que 100, efetuar novas requisições até obter os demais aplicativos.
   3. Selecionar, na lista de aplicativos formada, os aplicativos com atributo isHost igual a false.
5. Obter as rotas de uma transação:
   
   1. As transações do aplicativo interno já devem ter sido obtidas, ver item 3.
   2. GET <URL_monitor_local>/totvseai/monitor/v1/apps/<hostAppID>/transactions/<id_transação>.
   3. Extrair o conteúdo do atributo routes.
6. Quantidade de mensagens recebidas com erro nesta semana:
   
   1. GET <URL_monitor_local>/totvseai/monitor/v1/msgs/summary/receiving?category=error&date=2016-04-18:2016-04-22.
7. Quantidade de mensagens, por transação, recebidas com erro nesta semana:
   
   1. GET <URL_monitor_local>/totvseai/monitor/v1/msgs/summary/transactions?msgflow=receiving&date=2016?04?18:2016?04?22&status=businesserror;refused;malformed;notdelivered.
8. Listagem das mensagens de determinada transação (order), recebidas com erro no período de 18 a 22 de Abril de 2016:
   
   1. GET <URL_monitor_local>/totvseai/monitor/v1/msgs/list?msgflow=receiving&status=businesserror;refused;malformed;notdelivered&date=2016-04-18:2016-04-22&msgtypes=businessmessage&transactions=order.
9. Detalhamento de uma mensagem da transação order, recebida com erro no período de 18 a 22 de Abril de 2016:
   
   1. GET <URL_monitor_local>/totvseai/monitor/v1/msgs/<msgUUID>.
10. Quantidade de mensagens por aplicativo recebidas com sucesso no período de 18 a 22 de Abril de 2016:
    
    1. GET <URL_monitor_local>/totvseai/monitor/v1/msgs/summary/applications/?date=2016-04-18:2016-04-22&status=delivered&msgflow=receiving.
11. Quantidade de mensagens em processamento, separadas por transação:
    
    1. GET <URL_monitor_local>/totvseai/monitor/msgs/summary/transactions?status=received;recognized;validated;delivering;processing.
12. Listar mensagens enviadas com erro de timeout:
    
    1. GET <URL_monitor_local>//totvseai/monitor/v1/msgs/list?msgflow=sending&status=businesserror;refused;malformed;notdelivered&content=//ListOfMessages/Message[@type='ERROR' and contains(text(),'timeout')].