EM DESENVOLVIMENTO - PREVISÃO 12.1.14

Pré Requisitos

TOTVS 12 com versão 12.1.14 ou superior.

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

Mail Service

O Datasul Mail Service é um serviço que permite que tanto aplicações Progress como HTML possam realizar de forma simples o envio de e-mails.

Por se tratar de um serviço a chamada para o envio do e-mail se dá através de chamadas REST. A imagem abaixo exemplifica a arquitetura do serviço:

 

Configurações mínimas

Para utilização do serviço é preciso se atentar a algumas configurações no produto.

#+----------------------------------------------------------+
#|              DATASUL MAIL                                |
#+----------------------------------------------------------+
# E-mail do usuário da conta indicado para o envio de e-mail.
[email protected]
# Usuário e senha da conta que irá realizar o envio de e-mail.
mail.smtp.user=jhon.doe
mail.smtp.pass=minhasenhasuperdificil@321
# Endereço e porta do serviço de e-mail.
mail.smtp.host=mail.totvs.com.br
mail.smtp.port=587
# Habilita o suporte a SMTPS caso o servidor de e-mail esteja com HTTPS (SSL) habilitado.
mail.smtp.ssl.enable=true
# Indica se o servidor de e-mail está com o suporte ao TLS ativo.
mail.smtp.starttls.enable=true
# Habilita o DEBUG da API do JAVA MAIL.
mail.smtp.debug.enable=true

Serviços disponíveis

Através do contexto datasul-mail/resources estão disponíveis 3 serviços para envio de e-mails com as seguintes assinaturas:

 

  1. @GET /help

    1. Path: N/A.
    2. Query: N/A.
    3. 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).

    Exemplo: http://cordas:8480/dts/datasul-mail/resources/help/

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

    1. Path: N/A.
    2. Query: N/A.
    3. Body: JSON contendo a entidade Mail;
    4. Response: Uma cópia da entidade Mail em formato JSON.

    Exemplo: http://cordas:8480/dts/datasul-mail/resources/send/

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

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

    1. Path: N/A.
    2. Query: N/A.
    3. Body: JSON contendo a entidade Mail;
    4. Response: Uma cópia da entidade Mail em formato JSON.

    Exemplo: http://cordas:8480/dts/datasul-mail/resources/send/

 

Já o objeto Mail que é encaminhado no corpo das requisições possui a seguinte estrutura:

 

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.

API Progress

A API Progress se destina ao uso exclusivo para envio de e-mails, partindo o princípio que conteúdo do e-mail já esteja estruturado e o Progress vai apenas solicitar o envio da mensagem. Para este cenário foi disponibilizada a api: utp/ut-mail-api.p

Nesta API estão disponíveis 3 método, com a seguintes assinaturas:

 

  1. sendSimple: Destina-se ao envio de um e-mail simples.

    1. INPUT
      1. c_to: (CHARACTER EXTENT): lista contendo os endereços de destinatários;
      2. c_cc: (CHARACTER EXTENT): (opcional) lista contendo os endereços de destinatários a receberem a cópia do e-mail;
      3. c_bcc: (CHARACTER EXTENT): (opcional) lista contendo os endereços de destinatários a receberem a cópia oculta do e-mail;
      4. c_subject: (CHARACTER): assunto do e-mail;
      5. c_reply_to: (CHARACTER): (opcional) endereço de e-mail que receberá a resposta do e-mail enviado;
      6. c_from_alias: (CHARACTER): (opcional) caso queira utilizar um 'apelido' para sobrepor o endereço de e-mail do remetente (conta do sistema utilizada para envio da mensagem);
      7. lc_content: (LONGCHAR): conteúdo do e-mail;
      8. l_html: (LOGICAL): indica se o conteúdo do e-mail será um HTML.

    2. OUTPUT
      1. m_response: (MEMPTR): entidade Mail em formato JSON, ou erro em caso de algum problema na execução;
      2. i_response_code: (INTEGER): código do status de resposta da chamada REST ao serviço;
      3. c_response_status: (CHARACTER): descrição do status de resposta da chamada REST ao serviço.

  2. sendWithAttachment: Destina-se ao envio de um e-mail simples com anexos. Para utilização dos anexos é preciso adicionar a include utp/ut-mail-api.i para ter acesso a ttAttachment.

    1. INPUT
      1. c_to: (CHARACTER EXTENT): lista contendo os endereços de destinatários;
      2. c_cc: (CHARACTER EXTENT): (opcional) lista contendo os endereços de destinatários a receberem a cópia do e-mail;
      3. c_bcc: (CHARACTER EXTENT): (opcional) lista contendo os endereços de destinatários a receberem a cópia oculta do e-mail;
      4. c_subject: (CHARACTER): assunto do e-mail;
      5. c_reply_to: (CHARACTER): (opcional) endereço de e-mail que receberá a resposta do e-mail enviado;
      6. c_from_alias: (CHARACTER): (opcional) caso queira utilizar um 'apelido' para sobrepor o endereço de e-mail do remetente (conta do sistema utilizada para envio da mensagem);
      7. lc_content: (LONGCHAR): conteúdo do e-mail;
      8. l_html: (LOGICAL): indica se o conteúdo do e-mail será um HTML.
      9. ttAttachment: (TEMP-TABLE):
        1. fileName: (CHARACTER): nome do arquivo;
        2. fileType: (CHARACTER): tipo do arquivo, caso não seja informado o serviço vai tentar descobrir com base na extensão do arquivo;
        3. fileContent: (BLOB): conteúdo binário do arquivo.

    2. OUTPUT
      1. m_response: (MEMPTR): entidade Mail em formato JSON, ou erro em caso de algum problema na execução;
      2. i_response_code: (INTEGER): código do status de resposta da chamada REST ao serviço;
      3. c_response_status: (CHARACTER): descrição do status de resposta da chamada REST ao serviço.

  3. sendEmail: Destina-se ao envio de e-mail com solicitação de entrega e outros.

    1. INPUT
      1. c_to: (CHARACTER EXTENT): lista contendo os endereços de destinatários;
      2. c_cc: (CHARACTER EXTENT): (opcional) lista contendo os endereços de destinatários a receberem a cópia do e-mail;
      3. c_bcc: (CHARACTER EXTENT): (opcional) lista contendo os endereços de destinatários a receberem a cópia oculta do e-mail;
      4. c_subject: (CHARACTER): assunto do e-mail;
      5. c_reply_to: (CHARACTER): (opcional) endereço de e-mail que receberá a resposta do e-mail enviado;
      6. c_from_alias: (CHARACTER): (opcional) caso queira utilizar um 'apelido' para sobrepor o endereço de e-mail do remetente (conta do sistema utilizada para envio da mensagem);
      7. lc_content: (LONGCHAR): conteúdo do e-mail;
      8. l_html: (LOGICAL): indica se o conteúdo do e-mail será um HTML;
      9. c_read_notification: (CHARACTER): 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. i_delivery_notification: (INTEGER): indica o tipo de notificação que o remetente gostaria de receber;
      11. i_return_type: (INTEGER): indica como deve ser o retorno em caso do envio retornar alguma confirmação ou erro;
      12. i_priority: (INTEGER): prioridade do e-mail;
      13. ttAttachment: (TEMP-TABLE):
        1. fileName: (CHARACTER): nome do arquivo;
        2. fileType: (CHARACTER): tipo do arquivo, caso não seja informado o serviço vai tentar descobrir com base na extensão do arquivo;
        3. fileContent: (BLOB): conteúdo binário do arquivo.

    2. OUTPUT
      1. m_response: (MEMPTR): entidade Mail em formato JSON, ou erro em caso de algum problema na execução;
      2. i_response_code: (INTEGER): código do status de resposta da chamada REST ao serviço;
      3. c_response_status: (CHARACTER): descrição do status de resposta da chamada REST ao serviço.

 

Internamente esta API utiliza a API utp/ut-http-api.p para realizar as chamadas REST ao Datasul Mail Service.

Tanto para montagem do conteúdo do e-mail como para adicionar o conteúdo do arquivo a TEMP-TABLE de anexos, utilize o comando COPY-LOB. No caso do conteúdo do e-mail utilize a opção NO-CONVERT para evitar problemas com charset; por padrão o Datasul Mail Service utiliza o encode UTF-8. Na sessão de exemplos é possível verificar como realizar as operações.

API Javascript

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

A API está disposta em forma de um service através do nome: 'MailService'.

Sua principal função é abstrair a chamada REST para o serviço do Datasul Mail Service, desta forma ela possui apenas 2 métodos com as seguintes assinaturas:

 

Exemplos

var controller;

controller = function ($rootScope, $scope, MailService) {
	this.sendEmail = funcion() {
		MailService.send({
			reply: "[email protected]",
			alias: "Jhon Doe",
		    to: ["[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'];
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: "Jhon Doe",
		    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"
           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>
DEFINE VARIABLE h_mail AS HANDLE NO-UNDO.

IF NOT VALID-HANDLE(h_mail) THEN DO: 
	RUN utp/ut-mail-api.p PERSISTENT SET h_mail.
END.

DEFINE VARIABLE c_to                    AS CHARACTER NO-UNDO EXTENT.
DEFINE VARIABLE c_cc                    AS CHARACTER NO-UNDO EXTENT.
DEFINE VARIABLE c_bcc                   AS CHARACTER NO-UNDO EXTENT.
DEFINE VARIABLE c_subject               AS CHARACTER NO-UNDO INITIAL 'Teste API Progress - Datasul Mail Service':U.
DEFINE VARIABLE c_reply_to              AS CHARACTER NO-UNDO INITIAL '[email protected]':U.
DEFINE VARIABLE c_from_alias            AS CHARACTER NO-UNDO INITIAL 'Datasul Mail Service':U.
DEFINE VARIABLE lc_content_mail         AS LONGCHAR  NO-UNDO.
DEFINE VARIABLE l_html                  AS LOGICAL   NO-UNDO INITIAL TRUE.

ASSIGN lc_content_mail = 'Teste de envio de e-mail pelo PROGRESS :D':U.

EXTENT (c_to) = 1.                                       
ASSIGN c_to[1] = '[email protected]':U.

RUN sendSimple IN h_mail(
    INPUT c_to,
    INPUT c_cc,
    INPUT c_bcc,
    INPUT c_subject,
    INPUT c_reply_to,
    INPUT c_from_alias,
    INPUT lc_content_mail,
    INPUT l_html,
    OUTPUT mptr_response,
    OUTPUT i_response_code,
	OUTPUT c_response_status
).

IF VALID-HANDLE(h_mail) THEN DO: 
	DELETE PROCEDURE h_mail.
END.
{utp/ut-mail-api.i}

DEFINE VARIABLE h_mail AS HANDLE NO-UNDO.

IF NOT VALID-HANDLE(h_mail) THEN DO: 
	RUN utp/ut-mail-api.p PERSISTENT SET h_mail.
END.

DEFINE VARIABLE c_to                    AS CHARACTER NO-UNDO EXTENT.
DEFINE VARIABLE c_cc                    AS CHARACTER NO-UNDO EXTENT.
DEFINE VARIABLE c_bcc                   AS CHARACTER NO-UNDO EXTENT.
DEFINE VARIABLE c_subject               AS CHARACTER NO-UNDO INITIAL 'Teste API Progress - Datasul Mail Service':U.
DEFINE VARIABLE c_reply_to              AS CHARACTER NO-UNDO INITIAL '[email protected]':U.
DEFINE VARIABLE c_from_alias            AS CHARACTER NO-UNDO INITIAL 'Datasul Mail Service':U.
DEFINE VARIABLE lc_content_mail         AS LONGCHAR  NO-UNDO.
DEFINE VARIABLE l_html                  AS LOGICAL   NO-UNDO INITIAL TRUE.

ASSIGN lc_content_mail = 'Teste de envio de e-mail pelo PROGRESS :D':U.

EXTENT (c_to) = 1.                                       
ASSIGN c_to[1] = '[email protected]':U.

CREATE ttAttachment.
ASSIGN ttAttachment.fileName = '<NOME ANEXO 1>'.
    
COPY-LOB FROM FILE '<CAMINHO ANEXO 1>' 
	TO ttAttachment.fileContent NO-CONVERT NO-ERROR.

CREATE ttAttachment.
ASSIGN ttAttachment.fileName = '<NOME ANEXO 2>'.
    
COPY-LOB FROM FILE '<CAMINHO ANEXO 2>' 
	TO ttAttachment.fileContent NO-CONVERT NO-ERROR.

RUN sendWithAttachment IN h_mail(
    INPUT c_to,
    INPUT c_cc,
    INPUT c_bcc,
    INPUT c_subject,
    INPUT c_reply_to,
    INPUT c_from_alias,
    INPUT lc_content_mail,
    INPUT l_html,
	INPUT TABLE ttAttachment,
	OUTPUT mptr_response,
    OUTPUT i_response_code,
	OUTPUT c_response_status
).

IF VALID-HANDLE(h_mail) THEN DO: 
	DELETE PROCEDURE h_mail.
END.
{utp/ut-mail-api.i}

DEFINE VARIABLE h_mail AS HANDLE NO-UNDO.

IF NOT VALID-HANDLE(h_mail) THEN DO: 
	RUN utp/ut-mail-api.p PERSISTENT SET h_mail.
END.

DEFINE VARIABLE c_to                    AS CHARACTER NO-UNDO EXTENT.
DEFINE VARIABLE c_cc                    AS CHARACTER NO-UNDO EXTENT.
DEFINE VARIABLE c_bcc                   AS CHARACTER NO-UNDO EXTENT.
DEFINE VARIABLE c_subject               AS CHARACTER NO-UNDO INITIAL 'Teste API Progress - Datasul Mail Service':U.
DEFINE VARIABLE c_reply_to              AS CHARACTER NO-UNDO INITIAL '[email protected]':U.
DEFINE VARIABLE c_from_alias            AS CHARACTER NO-UNDO INITIAL 'Datasul Mail Service':U.
DEFINE VARIABLE lc_content_mail         AS LONGCHAR  NO-UNDO.
DEFINE VARIABLE l_html                  AS LOGICAL   NO-UNDO INITIAL TRUE.
    
ASSIGN lc_content_mail = 'Teste de envio de e-mail pelo PROGRESS :D':U.

EXTENT (c_to) = 1.                                       
ASSIGN c_to[1] = '[email protected]':U.

CREATE ttAttachment.
ASSIGN ttAttachment.fileName = '<NOME ANEXO 1>'.
    
COPY-LOB FROM FILE '<CAMINHO ANEXO 1>' 
	TO ttAttachment.fileContent NO-CONVERT NO-ERROR.

RUN sendEmail IN h_mail(
    INPUT c_to,
    INPUT c_cc,
    INPUT c_bcc,
    INPUT c_subject,
    INPUT c_reply_to,
    INPUT c_from_alias,
    INPUT lc_content_mail,
    INPUT l_html,
	INPUT '[email protected]',
    INPUT 1, /* Notificar: -1. Nunca 1. Sucesso 2. Falha 3. Atraso */
    INPUT 1, /* Tipo de Retorno: 1. Completo 2. Cabeçalho          */
	INPUT 1, /* Prioridade: 1. Alta 3. Normal 5. Baixa             */
    INPUT TABLE ttAttachment,
	OUTPUT mptr_response,
    OUTPUT i_response_code,
	OUTPUT c_response_status
).

IF VALID-HANDLE(h_mail) THEN DO: 
	DELETE PROCEDURE h_mail.
END.
{utp/ut-mail-api.i}
{utp/ut-report-api.i}

DEFINE VARIABLE i_ocorrencia      AS INTEGER   NO-UNDO INITIAL 101552.
DEFINE VARIABLE c_report          AS CHARACTER NO-UNDO INITIAL 'crm/rel_ratec_tecnico/':U.
DEFINE VARIABLE c_program         AS CHARACTER NO-UNDO INITIAL 'program=/report/crm/crm0001':U.
DEFINE VARIABLE c_format          AS CHARACTER NO-UNDO INITIAL 'html':U.
DEFINE VARIABLE c_dialect         AS CHARACTER NO-UNDO INITIAL 'pt':U.
DEFINE VARIABLE l_publish         AS LOGICAL   NO-UNDO INITIAL TRUE.
DEFINE VARIABLE l_download        AS LOGICAL   NO-UNDO INITIAL TRUE.

DEFINE VARIABLE h_api             AS HANDLE    NO-UNDO.
DEFINE VARIABLE h_mail            AS HANDLE    NO-UNDO.
DEFINE VARIABLE h_report          AS HANDLE    NO-UNDO.

DEFINE VARIABLE lc_content        AS LONGCHAR  NO-UNDO.
DEFINE VARIABLE c_query_params    AS CHARACTER NO-UNDO.

DEFINE VARIABLE i_response_code   AS INTEGER   NO-UNDO.
DEFINE VARIABLE c_response_status AS CHARACTER NO-UNDO.
DEFINE VARIABLE mptr_response     AS MEMPTR    NO-UNDO.

/* ************************************************** */
/* *** Busca os dados para impressão do relatório *** */
/* ************************************************** */

ASSIGN c_query_params = '&num_id_ocor=':U + STRING(i_ocorrencia).

IF NOT VALID-HANDLE(h_api) THEN DO: 
    RUN report/crm/crm0001.p PERSISTENT SET h_api.
END.

RUN getReportDataRPW IN h_api(INPUT TABLE ttReport, INPUT i_ocorrencia, OUTPUT lc_content, OUTPUT TABLE RowErrors).

IF VALID-HANDLE(h_api) THEN DO: 
    DELETE PROCEDURE h_api.
END.

/* ************************************************** */
/* *** Realiza a chamada para o Datasul Report    *** */
/* ************************************************** */

IF NOT VALID-HANDLE(h_report) THEN DO: 
    RUN utp/ut-report-api.p PERSISTENT SET h_report.
END.

RUN print IN h_report (
    INPUT c_report, 
    INPUT c_program, 
    INPUT c_format, 
    INPUT c_dialect,
    INPUT l_publish, 
    INPUT l_download, 
    INPUT lc_content, 
    INPUT c_query_params,
    OUTPUT mptr_response,
    OUTPUT i_response_code,
    OUTPUT c_response_status
).

IF VALID-HANDLE(h_report) THEN DO: 
    DELETE PROCEDURE h_report.
END.

IF i_response_code EQ 200 AND mptr_response NE ? THEN DO:

    /* ************************************************** */
    /* *** Agora enviamos por e-mail o HTML gerado    *** */
    /* ************************************************** */
    
    IF NOT VALID-HANDLE(h_mail) THEN DO: 
        RUN utp/ut-mail-api.p PERSISTENT SET h_mail.
    END.
    
    DEFINE VARIABLE c_to                    AS CHARACTER NO-UNDO EXTENT.
    DEFINE VARIABLE c_cc                    AS CHARACTER NO-UNDO EXTENT.
    DEFINE VARIABLE c_bcc                   AS CHARACTER NO-UNDO EXTENT.
    DEFINE VARIABLE c_subject               AS CHARACTER NO-UNDO INITIAL 'Teste API Progress - Datasul Mail Service':U.
    DEFINE VARIABLE c_reply_to              AS CHARACTER NO-UNDO INITIAL '[email protected]':U.
    DEFINE VARIABLE c_from_alias            AS CHARACTER NO-UNDO INITIAL 'Datasul Mail Service':U.
    DEFINE VARIABLE lc_content_mail         AS LONGCHAR  NO-UNDO.
    DEFINE VARIABLE l_html                  AS LOGICAL   NO-UNDO INITIAL TRUE.
    
    COPY-LOB FROM mptr_response TO lc_content_mail NO-CONVERT NO-ERROR.

    EXTENT (c_to) = 1.                                   
    
    ASSIGN c_to[1] = '[email protected]':U.   
    
    CREATE ttAttachment.
    ASSIGN ttAttachment.fileName = '<NOME ANEXO 1>'.
    
    COPY-LOB FROM FILE '<CAMINHO ANEXO 1>' 
        TO ttAttachment.fileContent NO-CONVERT NO-ERROR.

    RUN sendEmail IN h_mail(
        INPUT c_to,
        INPUT c_cc,
        INPUT c_bcc,
        INPUT c_subject,
        INPUT c_reply_to,
        INPUT c_from_alias,
        INPUT lc_content_mail,
        INPUT l_html,
        INPUT '[email protected]',
        INPUT 1, /* Notificar: -1. Nunca 1. Sucesso 2. Falha 3. Atraso */
        INPUT 1, /* Tipo de Retorno: 1. Completo 2. Cabeçalho          */
		INPUT 1, /* Prioridade: 1. Alta 3. Normal 5. Baixa             */
		INPUT TABLE ttAttachment,
        OUTPUT mptr_response,
        OUTPUT i_response_code,
        OUTPUT c_response_status
    ).
    
    IF VALID-HANDLE(h_mail) THEN DO: 
        DELETE PROCEDURE h_mail.
    END.

END.

Anexos