Árvore de páginas

Versões comparadas

Chave

  • Esta linha foi adicionada.
  • Esta linha foi removida.
  • A formatação mudou.
Informações
iconfalse

Índice


Pré Requisitos

...

  • TOTVS 12 com versão 12.1.15 ou superior

...

  • ;
  • Comunicação com o AppServer ativa e funcional para o resgate das informações 'base' para o envio de e-mail;
  • Servidor de e-mails com

...

  • suporte a SMTP e uma conta válida para envio de e-mails.

Configurações

...

Mínimas

...

Para utilização do serviço

...

, algumas configurações

...

são necessárias:

  • Inserir o trecho de código abaixo Verificar no arquivo "josso-agent-config.xml o trecho de código abaixo e caso não exista, é necessário efetuar a inclusão do mesmo:".
Bloco de código
languagexml
<partner-app>
	<context>/dts/datasul-mail</context>
</partner-app>


  • Configurar os parâmetros de localização e porta, interno e externo, do servidor de aplicação (JBoss) no programa 'Parâmetros Gerais Módulo Básico' (btb946aa) na , aba 'Servidor'.  Mais informações estão disponíveis em: Para mais informações acesse Configurar Aba Servidor (BTB946AA).

  • Configurar os parâmetros de para envio de e-mail no utilizando o programa 'Parâmetros Email Foundation' (btb962zb).  Mais informações estão disponíveis em:   Para mais informações acesse Parâmetros Email Foundation (BTB962ZB).

Mail Service

...

O Datasul Mail Service é um serviço que permite

...

tanto aplicações Progress

...

quanto HTML possam realizar

...

envio de e-mails de forma simples.

Por se tratar de um serviço, a chamada para o envio do e-mail

...

usando esta funcionalidade é realizada através de chamadas REST.

...

Exemplo da arquitetura do serviço:

 


Image RemovedImage Added

Serviços

...

Disponíveis

...

Através do contexto datasul-mail/resources

...

existem 3 serviços

...

disponíveis para envio de e-mails com as seguintes assinaturas:

...

@GET /help

Path: N/A.

Query: N/A.

Response: Retorna as propriedades do Mail Service (mail.smtp.sender, mail.smtp.auth, mail.smtp.user, mail.smtp.pass, mail.smtp.host, mail.smtp.port, mail.smtp.ssl.enable, mail.smtp.starttls.enable, mail.smtp.debug.enable).

...


Bloco de código
languagejava
titleEXEMPLO
http://

...

<server>:

...

8080/dts/datasul-mail/resources/help/


@POST /send: @Consumes({ MediaType.APPLICATION_JSON, MediaType.TEXT_PLAIN })

Este serviço recebe o e-mail e suas opções para envio. Não suporta anexos.

Path: N/A.

Query: N/A.

Body: JSON contendo a entidade Mail;

Response: Uma cópia da entidade Mail em formato JSON.

...


Bloco de código
languagejava
titleEXEMPLO
http://<server>:8080

...

/dts/datasul-mail/resources/send/


@POST /send: @Consumes(MediaType.MULTIPART_FORM_DATA)

Este serviço recebe o e-mail e suas opções para envio. Suporta anexos.

Path: N/A.

Query: N/A.

Body: JSON contendo a entidade Mail;

Response: Uma cópia da entidade Mail em formato JSON.

...


Bloco de código
languagejava
titleEXEMPLO
http://

...

<server>:

...

8080/dts/datasul-mail/resources/send/

...


Âncora
mail_object
mail_object

...


Painel
borderColororange
borderStyledashed

O objeto Mail, encaminhado no corpo das requisições, possui a seguinte estrutura:

  1. subject: (string) assunto do e-mail;
  2. content: (string) conteúdo do e-mail, podendo ser HTML;
  3. reply: (string) (opcional) endereço de e-mail que receberá a resposta do e-mail enviado;
  4. to: ([string]) lista contendo os endereços de destinatários;
  5. cc: ([string]) (opcional) lista contendo os endereços de destinatários a receberem a cópia do e-mail;
  6. bcc: ([string]) (opcional) lista contendo os endereços de destinatários a receberem a cópia oculta do e-mail;
  7. returnNotificationType: (integer) (opcional): indica como deve ser o retorno em caso do envio retornar alguma confirmação ou erro.
    1. 1. Retorna o e-mail completo;
    2. 2. Retorna apenas o cabeçalho (default). 
  8. deliveryNotification: (integer) (opcional): indica o tipo de notificação que o remetente gostaria de receber.
    1. -1. Nenhuma (defaul);
    2. 1. Ao entregar o e-mail ao destinatário;
    3. 2. Ao falhar na entrega ao destinatário;
    4. 4. Ao atrasar a entrega ao destinatário;
  9. readNotificationTo: (string) Em caso de leitura do e-mail, caso tenha sido informado um endereço válido para este atributo, este receberá uma notificação de que o e-mail foi lido;
  10. priority: (integer) (opcional): prioridade do e-mail:
    1. 1: Alta;
    2. 3: (default) Normal;
    3. 5: Baixa.

 



tip
Dica
  • As mensagens de confirmação de entrega e falhas serão retornadas a caixa de e-mail do usuário que estiver sendo utilizado como sender pelo serviço de e-mail. Entretanto, quando informado um endereço de e-mail válido no atributo readNotificationTo, este receberá o e-mail de confirmação de leitura.


  • O envio de e-mail ocorre de forma assíncrona, desta forma os erros ou retornos de falhas do envio propriamente dito não são resgatados no momento da execução. Isso se deve ao fato de que o Datasul Mail Service delega ao servidor SMTP o envio da mensagem, sendo que este pode não efetuar o envio no momento em que for solicitado, variando de acordo com a sua fila de despachos e parametrizações.



Recursos

...

Disponíveis

...

Para mais informações de quais são os recursos disponíveis quanto a esta opção de envio, consultar o link: Envio de

...

E-mail Datasul.


API Progress

A API a ser utilizada no progress é a utapi019.p

...

que está preparada para enviar e-mails de acordo com a configuração indicada no programa 'Parâmetros Email Foundation' (btb962zb).

Para mais informações sobre como utilizar a API utapi019

...

acesse Utilização de API de envio de e-mail

...

API Javascript

Está é a API para utilização nos projetos com o THF.

A API está disponível em forma de um service através do nome 'MailService'. Para utilizá-lo, basta injetar o MailService no construtor do seu controller.

Sua principal função é realizar os envios de e-mail a partir de programas HTML, abstraindo a chamada REST (utilizando o Datasul Rest) para a API utapi019, que centraliza todo e qualquer envio de e-mail, tornando a configuração de envio de e-mails única.

O MailService dispõe de 2 métodos para serem utilizados para realizar o envio de e-mail, contendo as seguintes assinaturas:

...

  • email: contendo o objeto Mail;
  • files: anexo ou lista de arquivos anexos obtidos através do seletor de arquivos do navegador;
  • callback: função a ser chamada quando terminar o processo.
  • callbackProgress: função que devolve o '%' de progresso do envio dos anexos para o serviço, o evento retornado pelo server a entidade de Mail relacinada ao anexo;
  • callbackError: função a ser chamada caso ocorra algum erro inesperado.

.


Bloco de código
languagejava
themeEclipse
firstline1
titleEXEMPLO Progress: sendWithAttachment
linenumberstrue
collapsetrue
{utp\utapi019.i2}

RUN utp/utapi019.p PERSISTENT SET h-utapi019. 

create tt-envio2.
assign tt-envio2.versao-integracao = 1
       tt-envio2.exchange    = NO
       tt-envio2.servidor    = 'smtp.totvs.com.br'
       tt-envio2.porta       = 587
       tt-envio2.destino     = "[email protected]"
       tt-envio2.remetente   =

Exemplos

Bloco de código
languagejs
firstline1
titleJavascript: send
linenumberstrue
collapsetrue
var controller;

controller = function ($rootScope, $scope, MailService) {
	this.sendEmail = funcion() {
		MailService.send({
			reply: "[email protected]",
			alias: "[email protected]",
		      to: "[email protected]",
			cc: "[email protected]",
			subject: tt-envio2.assunto     = "Datasul Mail Service",
			content:
       tt-envio2.mensagem    = "Hello from the other side !"
		}, function(result) {
			console.info(result);
		});
       };
};

controller.$inject = ['$rootScope', '$scope', 'MailService'];
Bloco de código
languagejs
firstline1
titleJavascript: sendWithAttachment
linenumberstrue
collapsetrue
var controller;

controller = function ($rootScope, $scope, MailService) {

	this.onSelectFiles = function(selectedFiles) {
		if (angular.isDefined(selectedFiles)) {
			this.sendEmail(selectedFiles);
		}
	};

	this.sendEmail = funcion(files) {
		MailService.sendWithAttachment({
			reply: "[email protected]",
			alias: "[email protected]",
		    to: "[email protected]",
			cc: "[email protected]",
			subject: "Datasul Mail Service",
			content: "Hello from the other side !"
		}, files, 
		function(result, mail) {
			console.info(result, mail);
		}, function(progress, evt, mail) {
			console.warn(progress, evt, mail);
		}, function(result, status, headers, config, email) {
			console.error(result, status, headers, config, email);
		});
    };
};

controller.$inject = ['$rootScope', '$scope', 'MailService'];

------------------------------------------------------------------------------------
<html>
<head></head>
<body>
	
	<label class="btn btn-default pull-right"
    	   role="button"
tt-envio2.importancia = 2
       tt-envio2.log-enviada = NO
       tt-envio2.log-lida    = NO
       tt-envio2.acomp       = NO
       tt-envio2.formato     = 'html'.

CREATE tt-mensagem.
ASSIGN tt-mensagem.mensagem = tt-envio2.mensagem.

caso não sejam informados os campos da tabela tt-paramEmail2, serão utilizados as configurações dos parâmetros de email foundation */
CREATE tt-paramEmail2.
ASSIGN tt-paramEmail2.caminhoEmail = 5
       tt-paramEmail2.mailUser = '<user_email>'
       tt-paramEmail2.mailPass = '<senha_email>'
       tt-paramEmail2.TLS      = NO
       tt-paramEmail2.SSL      = NO
       tt-paramEmail2.DEBUG    = YES. 


CREATE ttAttachment.
ASSIGN ttAttachment.fileName = '<nome_arquivo>'.

COPY-LOB FROM FILE ttAttachment.FILENAME TO ttAttachment.fileContent NO-CONVERT NO-ERROR.  /* caso esteja disponível apenas o binário do arquivo, basta atribui-lo ao campo ttAttachment.fileContent */

RUN pi-execute4 IN h-utapi019 (INPUT  Table tt-envio2,
    INPUT  Table tt-mensagem,
    INPUT  Table tt-paramEmail2,
    INPUT  TABLE ttAttachment,
    OUTPUT Table tt-erros).
if  return-value = "NOK" then do:
    for each tt-erros:
        disp tt-erros with 1 column width 300.
    end.                             for="file-input">
		Selecione os arquivos...
	</label>
	
	<span class="file-text"></span>
    
	<input id="file-input"
           type="file"
           style="position:fixed;top:-999px;"
           ngf-select
           ngf-change="controller.onSelectFiles($files);"
           ngf-multiple="true"
           ngf-allow-dir="false"/>

</body>
</html>
end.


API Javascript

Está é a API para utilização nos projetos utilizando THF e está disponível em forma de um serviço nomeado como 'MailService'. Para utilizá-lo, basta injetar o MailService no construtor do seu controller.

Sua principal função é realizar os envios de e-mail a partir de programas HTML, abstraindo a chamada REST (utilizando o Datasul Rest) para a API utapi019, que centraliza qualquer envio de e-mail, tornando a configuração de envio de e-mails única.


O MailService disponibiliza 2 métodos para realizar o envio de e-mail, contendo as seguintes assinaturas:



Painel
borderColororange
borderStyledashed
  1. send
    1. email: contendo o objeto Mail;
      1. reply: Remetente do e-mail;
      2. mailTo: Destinatário do e-mail;
      3. cc: Endereço de e-mail em cópia;
      4. subject: Assunto da mensagem;
      5. content: Conteúdo da mensagem.
    2. callback: função a ser chamada quando terminar o processo.



Painel
borderColororange
borderStyledashed
  1. sendWithAttachment
    1. email: contendo o objeto Mail;
      1. reply: Remetente do e-mail;
      2. mailTo: Destinatário do e-mail;
      3. cc: Endereço de e-mail em cópia;
      4. subject: Assunto da mensagem;
      5. content: Conteúdo da mensagem;
    2. files: anexo ou lista de arquivos anexos obtidos através do seletor de arquivos do navegador;
    3. callback: função a ser chamada quando terminar o processo;
    4. callbackProgress: função que devolve o '%' de progresso do envio dos anexos para o serviço, o evento retornado pelo server a entidade de Mail relacionada ao anexo;
    5. callbackError: função a ser chamada caso ocorra algum erro inesperado.



Bloco de código
languagejs
titleEXEMPLO JavaScript: send
linenumberstrue
collapsetrue
var controller;
controller = function ($rootScope, $scope, MailService) {
	this.sendEmail = funcion() {
		MailService.send({
			reply: "[email protected]",
		    mailTo: "[email protected]",
			cc: "[email protected]",
			subject: "Datasul Mail Service",
			content: "Hello from the other side !"
		}, function(result) {
			console.info(result);
		});
    };
};
controller.$inject = ['$rootScope', '$scope', 'MailService'];
Bloco de código
languagejs
titleEXEMPLO JavaScript: sendWithAttachment
linenumberstrue
collapsetrue
var controller;
controller = function ($rootScope, $scope, MailService) {
	this.onSelectFiles = function(selectedFiles) {
		if (angular.isDefined(selectedFiles)) {
			this.sendEmail(selectedFiles);
		}
	};
	this.sendEmail = funcion(files) {
		MailService.sendWithAttachment({
			reply: "[email protected]",
		    mailTo: "[email protected]",
			cc: "[email protected]",
			subject: "Datasul Mail Service",
			content: "Hello from the other side !"
		}, files, 
		function(result, mail) {
			console.info(result, mail);
		}, function(progress, evt, mail) {
			console.warn(progress, evt, mail);
		}, function(result, status, headers, config, email) {
			console.error(result, status, headers, config, email);
		});
    };
};
controller.$inject = ['$rootScope', '$scope', 'MailService'];
Bloco de código
languagexml
titleEXEMPLO HTML: sendWithAttachment
linenumberstrue
collapsetrue
<html>
	<head></head>
	<body>	
		<label class="btn btn-default pull-right"
    		   role="button"
	           for="file-input">
			Selecione os arquivos...
		</label>
		<span class="file-text"></span>
    	<input id="file-input"
        	type="file"
	        style="position:fixed;top:-999px;"
    	    ngf-select
        	ngf-change="controller.onSelectFiles($files);"
        	ngf-multiple="true"
Bloco de código
languagejava
themeEclipse
firstline1
titleProgress: sendWithAttachment
linenumberstrue
collapsetrue
{utp\utapi019.i2}

RUN utp/utapi019.p PERSISTENT SET h-utapi019. 

create tt-envio2.
assign tt-envio2.versao-integracao = 1
       tt-envio2.exchange    = NO
       tt-envio2.servidor    = 'smtp.totvs.com.br'
       tt-envio2.porta       = 587
       tt-envio2.destino     = "[email protected]"
       tt-envio2.remetente   = "[email protected]"
       tt-envio2.assunto     = "Datasul Mail Service"
       tt-envio2.mensagem    = "Hello from the other side !"
       tt-envio2.importancia = 2
       tt-envio2.log-enviada = NO
       tt-envio2.log-lida    = NO
       tt-envio2.acomp       = NO
       tt-envio2.formato     = 'html'.

CREATE tt-mensagem.
ASSIGN tt-mensagem.mensagem = tt-envio2.mensagem.

caso não sejam informados os campos da tabela tt-paramEmail2, serão utilizados as configurações dos parâmetros de email foundation */
CREATE tt-paramEmail2.
ASSIGN tt-paramEmail2.caminhoEmail = 5
       tt-paramEmail2.mailUser = '<user_email>'
       tt-paramEmail2.mailPass = '<senha_email>'
       tt-paramEmail2.TLS      = NO
       tt-paramEmail2.SSL      = NO
       tt-paramEmail2.DEBUG    = YES. 


CREATE ttAttachment.
ASSIGN ttAttachment.fileName = '<nome_arquivo>'.

COPY-LOB FROM FILE ttAttachment.FILENAME TO ttAttachment.fileContent NO-CONVERT NO-ERROR.  /* caso esteja disponível apenas o binário do arquivo, basta atribui-lo ao campo ttAttachment.fileContent */

RUN pi-execute4 IN h-utapi019 (INPUT  Table tt-envio2,
    INPUT  Table tt-mensagem,
    INPUT  Table tt-paramEmail2,
    INPUT  TABLE ttAttachment,
    OUTPUT Table tt-erros).
if  return-value = "NOK" then do:
    for each tt-erros:
        disp tt-erros with 1 column width 300.
    end.                               
end.ngf-allow-dir="false"/>
	</body>
</html>