Objetivo

...

Utilização da API utapi019 para envio de mensagens através do servidor pelo servidor de correio eletrônico e envio de FAX através de servidor pelo servidor de FAX.

Fontes

...

$/FOUNDATION/Fontes_Doc/Sustentacao/V11/V11/progress/src/utp

• utapi019.p
• utapi019.i
• utapi019.i1
  

Considerações gerais

...

• A utilização dessa API não é recomendada em ambientes WEB, pois a mesma pode solicitar informações ao usuário e, no caso de executar o Blat, o usuário do IIS deverá ter permissão para efetuar a tarefa de envio e rodar o aplicativo Blat.
• A include utapi019.i contém as definições das temp-table's tt-envio2, tt-mensagem e tt-erro que devem ser passadas como parâmetros à API.
• A include utapi019.i1 contém a definição da temp-table tt-paramEmail e chamada para a include utapi019.i, resultando na definição de todas as temp-table's necessárias para chamadas à API.
• É possível enviar e-mail e FAX em ambiente Windows e apenas e-mail em ambiente UNIX.Será
• Por padrão, será utilizado Outlook ou Blat no ambiente Windows ou comando sendmail no ambiente UNIX para envio de e-mail e será utilizado Outlook para envio de FAX.
• O Blat é um software freeware para envio de e-mail via protocolo SMTP, encontra-se no diretório (interfac/mail).
• Quando for utilizado envio de e-mail numa sessão background do Progress(batch-mode) e o ambiente for Windows, a API utilizará sempre o Blat.
• No envio da mensagem através de em ambiente UNIX, o sendmail e o uuencode devem estar configurados corretamente. Para testar o funcionamento do comando, digite no prompt, usando o mesmo usuário e na mesma pasta em que a API será executada, os respectivos comandos sendmail e uuencode. A execução destes programas não deve apresentar erros. Caso ocorram erros deve-se entrar em contato com a equipe de suporte do sistema operacional do servidor.
• A API possui um evento eventos de UPC chamado eMailBlat, que permite permitem ao cliente usuário alterar o comando de execução do Blat. Esse ponto de customização foi criado para atender as necessidades dos clientes que precisam informar informações específicas do seu envio. Esses pontos foram desenvolvidos para atender às necessidades de usuários que precisam adicionar informações específicas de ser serviço de e-mail , que não são contempladas pelos produtos Datasul.
• A API tem algumas restrições ao ser comparado a um serviço de e-mail, ela : não faz validações efetua validações dos tipos de arquivos anexados a à mensagem , nem outros tipos de tratamento que um serviço de e-mail realiza. Caso ocorra alguma destas dessas validações que a API não trata, será tratado considerado pela API que todos os e-mails foram enviados corretamente.Caso houver algum erro no envio do e-mail, o remetente receberá um e-mail do serviço de e-mail, que a mensagem não pode ser enviada ao destinatário.
• Em Agosto de 2012 foi incluído uma nova forma de envio de e-mail, que é utilizando a aplicação JAVA. Essa funcionalidade não está disponível para os envios padrões do produto. Essa funcionalidade só pode ser utilizada com programas específicos que utilizarem a API. No decorrer desta dessa documentação serão detalhados os procedimentos para utilização.
• Em Junho de 2013 foi disponibilizado o envio de e-mail com SSL que utiliza o programa MailSend que é freeware. Esse programa envia e-mails via protocolo SMTP e encontra-se no diretório (interfac/mail). Essa funcionalidade não esta disponível está disponível para os envios padrões do produto. Essa funcionalidade só pode ser utilizada com programas específicos que utilizarem a API. No decorrer desta dessa documentação serão detalhados os procedimentos para utilização.
  

Âncora
parametros parametros

Parâmetros de e-mail

...

O produto possui um cadastro de parâmetros de e-mail (BTB962ZB). Estes Esses parâmetros serão utilizados quando não informados na temp-table enviada à API:

Temp-tables

...

tt-envio2

Possui definições da mensagem a ser enviada.

...

...

1. Para utilização do Blat

...

1. , é necessário encontrar o arquivo “interfac/mail/blat.exe” na estrutura de diretórios do produto. Caso não seja encontrado, o e-mail será enviado sem o anexo. O arquivo “blat.exe” é distribuído gratuitamente junto às mídias/pacotes dos produtos Datasul.

...

1. Só é possível enviar e-mail no formato HTML utilizando Outlook 2000 ou posterior.

...

1. Não é possível enviar e-mail no formato HTML quando existir arquivo anexo no UNIX.

tt-mensagem

Possui o conteúdo da mensagem enviada. Essa temp-table foi criada porque o número máximo de caracteres por registro no Progress é de 32kb e se a caso a mensagem do e-mail possuísse mais 32 Kb acontecia o erro Progress era exibida a mensagem Progress 444.  Com essa temp-table será possível enviar e-mail com quantos caracteres forem necessários, menos com a opção Exchange que ainda mantém esta essa limitação.

tt-erro

Possui os erros encontrados pela API.

tt-paramEmail

Indica tipo de envio de e-mail.

Execução

...

A API possui dois métodos que podem ser executados:

1. pi-execute3: recebe quatro temp-tables como parâmetros: tt-envio2 (INPUT), tt-mensagem (INPUT), tt-paramEmail (INPUT) e tt-erros (OUTPUT).
2. pi-execute2: recebe três temp-table's como parâmetros: tt-envio2 (INPUT), tt-mensagem (INPUT) e tt-erros (OUTPUT). Esse método possui as seguintes validações para o tipo de envio:
   1. se o caso o sistema operacional for UNIX, utilizará envio via UNIX;
   2. se não caso não for UNIX e o campo tt-envio2.exchange estiver marcado, utilizará envio via exchange;
   3. caso contrário, utilizará o envio via BLAT.

...

1. Versão de integração: verifica se o programa chamador está íntegro com a API, e isto ocorre através por meio da verificação da versão de integração passada como parâmetro. Caso a versão esteja incompatível, a API abortará a execução retornando o código de erro 3941a mensagem 3941.
2. Inconsistência ou insuficiência de dados: verifica a inconsistência e/ou insuficiência dos dados. Isto ocorre através por meio da verificação dos dados passados como parâmetros. Caso os dados sejam inconsistentes ou insuficientes, a API abortará a execução retornando o código de erro 8646. Cabe ao programa de origem, verificar a consistência do registro que está sendo enviado.

...

1. OK: Mensagem enviada com sucesso.
2. NOK: Envio de mensagem abortado. Os erros encontrados serão retornados através da por meio da temp-table tt-erros.

Exemplos

...

{utp/utapi019.i}
RUN utp/utapi019.p PERSISTENT SET h-utapi019.
CREATE tt-envio2.
ASSIGN tt-envio2.versao-integracao = 1
       tt-envio2.destino     = "[fax:0,0474417020]"   
       tt-envio2.assunto     = "xxxxxxxxxx"      
       tt-envio2.arq-anexo   = "c:/tmp/api-fax.doc".

CREATE tt-mensagem.
ASSIGN tt-mensagem.seq-mensagem = 1
       tt-mensagem.mensagem = "Mensagem 1".

CREATE tt-mensagem.
ASSIGN tt-mensagem.seq-mensagem = 2
       tt-mensagem.mensagem = "Mensagem 2".

OUTPUT TO VALUE(SESSION:TEMP-DIRECTORY + "envemail.txt").
    RUN pi-execute2 IN h-utapi019(INPUT TABLE tt-envio2,
                                  INPUT TABLE tt-mensagem,
                                  OUTPUT TABLE tt-erros).
OUTPUT CLOSE.
 
IF RETURN-VALUE = "NOK" THEN DO:
    FOR EACH tt-erros:
        DISPLAY tt-erros WITH 1 COLUMN WIDTH 300.
    END.
END.

DELETE PROCEDURE h-utapi019.

...

1. Para o envio de FAX, é necessário que esteja instalado algum software client de envio de FAX.
2. Quando a API de envio de FAX/MAIL for utilizada para envio de FAX, o campo tt-envio2.destino deve seguir a seguinte o padrão de sintaxe – “[fax:número]”.
3. Caso haja a necessidade de se enviar de enviar mais de 32kb de texto, a mensagem que será apresentada no FAX, deve estar dentro do arquivo anexo.

...

{utp/utapi019.i1}
RUN utp/utapi019.p PERSISTENT SET h-utapi019.

CREATE tt-envio2.
ASSIGN tt-envio2.versao-integracao = 1
       tt-envio2.servidor    = "172.16.1.80"
       tt-envio2.porta       = 25
       tt-envio2.destino     = "[email protected],[email protected]"
       tt-envio2.remetente   = "[email protected]"
       tt-envio2.assunto     = "subject"
       tt-envio2.arq-anexo   = "c:/tmp/texto.doc"
       tt-envio2.formato     = "HTML".

CREATE tt-mensagem.
ASSIGN tt-mensagem.seq-mensagem = 1
       tt-mensagem.mensagem     = "<h1><center>message body 1</pre>".

CREATE tt-mensagem.
ASSIGN tt-mensagem.seq-mensagem = 2
       tt-mensagem.mensagem     = "<h1><center>message body 2</pre>".

CREATE tt-paramEmail.
ASSIGN tt-paramEmail.caminhoEmail = 3. /*0-Unix,1-Blat,2-Exchange,3-Java,4-MailSend*/

OUTPUT to value(SESSION:TEMP-DIRECTORY + "envemail.txt"). 
    RUN pi-execute3 IN h-utapi019 (INPUT  table tt-envio2,
                                   INPUT  table tt-mensagem,
                                   INPUT  table tt-paramEmail,
                                   OUTPUT table tt-erros).
OUTPUT close.
       
IF  RETURN-VALUE = "NOK" THEN DO:
    FOR EACH tt-erros:
        DISP tt-erros WITH 1 COLUMN WIDTH 300.
    END. 
END.

DELETE PROCEDURE h-utapi019.

Pontos de customização

...

A API possui eventos de UPC que permitem ao cliente alterar usuário alterar o comando de execução. Esses pontos foram criados para desenvolvidos para atender as necessidades de clientes que usuários que precisam adicionar informações específicas não contempladas no produto Datasul.

OBS: Não A partir da versão 12.1.7, não é mais necessário alterar a linha de comando para adição de usuário e senha, a autenticação é feita através por meio dos dados informados nos parâmetros.

{include/i-epc200.i1} /* definição da temp-table tt-epc */

DEFINE INPUT        PARAMETER p-ind-event AS CHARACTER NO-UNDO.
DEFINE INPUT-OUTPUT PARAMETER TABLE       FOR tt-epc.

DEFINE VARIABLE cComandoEmail AS CHARACTER NO-UNDO.

IF p-ind-event = "eMailBlat" THEN DO:
    FIND FIRST tt-epc
        WHERE tt-epc.cod-event     = "eMailBlat":U
        AND   tt-epc.cod-parameter = "CommandEmail":U
        EXCLUSIVE-LOCK NO-ERROR.
    IF AVAILABLE tt-epc THEN 
        ASSIGN cComandoEmail = tt-epc.val-parameter.
    
    ASSIGN cComandoEmail = cComandoEmail + " -hostname ~"tech-valdir~"":U.

    IF AVAILABLE tt-epc THEN 
        ASSIGN tt-epc.val-parameter = cComandoEmail.
END.

...