Linha Datasul

Árvore de páginas

Versões comparadas

Versão antiga 20

changes.mady.by.user Rafael Cesar Borges

Gravado em

comparado com

Nova versão Atual

changes.mady.by.user Ieda Ferreira Alves Flock

Gravado em

Chave

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

Índice

Objetivo

Utilização da API utapi019

...

para envio de mensagens pelo servidor de correio eletrônico

...

..

Informações
titleÍndice

Índice


Fontes

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

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

Considerações gerais



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

...


  • A include utapi019.i2

Contém a definição da temp-table tt-paramEmail2 e chamada paras as includes ut-mail-api.i (definição da TempTable de anexo), i_prdvers (Include de versão do produto) e utapi019.i1, supracitada.


  • Por padrão

Será utilizado o método de envio definido na tela de parâmetros (Exchange, Blat ou Datasul Mail Service) no ambiente Windows ou

...

comando sendmail no ambiente UNIX para envio de e-mail

...

.


  • Sessão background do Progress

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.


  • Envio da mensagem em ambiente UNIX

No envio da mensagem 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.


  • Eventos de UPC 

A API possui eventos de UPC que permitem ao usuário alterar o comando de execução do 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.


  • Restrições

A API tem algumas restrições ao ser comparado a um serviço de e-mail: não efetua validações dos tipos de arquivos anexados à mensagem nem outros tipos de tratamento que um serviço de e-mail realiza. Caso ocorra alguma dessas validações que a API não trata, será considerado pela API que todos os e-mails foram enviados corretamente.

...

O produto possui um cadastro de parâmetros de e-mail (BTB962ZB). Mais informações quanto a parametrização estão disponíveis em: Parâmetros Email Foundation (BTB962ZB).

...


  • Protocolos SSL (Secure Sockets Layer) e TLS (Transport Layer Security)

 Verificar se o servidor utiliza estes tipos de protocolo, caso prefira uma conexão segura com criptografia. Assim será possível marcar e ativar as opções SSL e TLS no produto. Lembrando que estas opções de envio são válidas somente para Datasul Mail Service.


Âncora
parametros
parametros
Parâmetros de e-mail

O produto possui um cadastro de parâmetros de e-mail (BTB962ZB). Mais informações quanto a parametrização estão disponíveis em: Parâmetros Email Foundation (BTB962ZB).

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.

Painel
borderColororange
borderStyledashed
AtributoTipoValor InicialDescrição
versao-integracaointeger
Versão de integração da API.
servidorcharacter
Hostname ou endereço IP do servidor de e-mail. Caso não informado, é utilizado o cadastro dos parâmetros de e-mail do produto.
portainteger0Número da Porta do servidor de e-mail. Caso não informado, é utilizado o cadastro dos parâmetros globais do produto.

...

 Só influencia quando utilizado OCX para envio da mensagem.
exchangelogicalnoUtilizar servidor Exchange para envio da mensagem.
destinocharacter
Destinatário(s) da mensagem.  Quando é mais de um, devem ser separados por vírgulas. Deve ser informado obrigatoriamente.

...

copiacharacter
Cópia Carbono da mensagem. Quando é mais de um, devem ser separados por vírgulas. Para ambiente UNIX, os endereços adicionados nesse campo serão incluídos no campo "para".
remetentecharacter
Remetente da mensagem. Só influencia quando utilizado OCX para envio da mensagem. Precisa ter os padrões de um endereço de e-mail([email protected]). Tem que ser um e-mail valido quando utilizado JAVA.
assuntocharacter
Assunto da mensagem.
mensagemcharacter
Corpo da mensagem. Informação obrigatória.
arq-anexocharacter
Caminho completo do arquivo a ser anexado na mensagem. Disponível apenas para envio de mensagem por MS-Exchange, Blat, Java e UNIX. Em outros casos, é incorporado na mensagem, o caminho do arquivo. Para anexar mais de um arquivo, eles devem ser separados por virgula.
importanciainteger0Nível da importância da mensagem. Só influencia quando utilizado servidor Exchange. Os valores possíveis são de 0 a 2: 0 – Prioridade Baixa, 1 – Prioridade Normal, 2 – Prioridade Alta.
log-enviadalogicalnoEnvia uma mensagem para o remetente assim que a sua mensagem original for enviada. Só influencia quando utilizado servidor Exchange.
log-lidalogicalnoEnvia uma mensagem para o remetente assim que a sua mensagem original for lida. Só influencia quando utilizado servidor Exchange.
acomplogicalyesExecução do utilitário ut-acomp, para verificar o desenvolvimento da execução. Só influencia quando utilizado servidor Exchange.
formatocharacterTextoAceita dois valores: "TEXTO", para enviar e-mail sem formatação e "HTML" , onde o e-mail será enviado no formato HTML.


Abaixo é possível visualizar onde cada atributo é obrigatório ou opcional:


Painel
borderColororange
borderStyledashed
AtributoDatasul Mail ServiceEXCHANGE

...

BLAT/OCXSENDMAIL (UNIX)JAVAMAILSEND (SSL)
versao-integracaoObrigatórioObrigatórioObrigatórioObrigatórioObrigatórioObrigatório
servidor

...

OpcionalDesnecessárioOpcionalOpcionalObrigatórioObrigatório
porta

...

OpcionalDesnecessárioOpcionalDesnecessárioObrigatórioObrigatório
destinoObrigatórioObrigatórioObrigatórioObrigatórioObrigatórioObrigatório
copiaOpcionalOpcionalOpcionalDesnecessárioDesnecessárioOpcional
remetente

...

Opcional4DesnecessárioObrigatórioOpcionalObrigatórioObrigatório
assunto

...

ObrigatórioOpcionalObrigatórioOpcionalObrigatórioObrigatório
mensagemObrigatórioObrigatórioObrigatórioObrigatórioObrigatórioObrigatório
arq-anexoDesnecessário5Opcional

...

Opcional1Opcional3OpcionalOpcional
importanciaDesnecessárioOpcionalDesnecessárioDesnecessárioDesnecessárioDesnecessário

...

log-enviadaDesnecessárioOpcionalDesnecessárioDesnecessárioDesnecessárioDesnecessário

...

log-lidaDesnecessárioOpcionalDesnecessárioDesnecessárioDesnecessárioDesnecessário
acompDesnecessário

...

OpcionalDesnecessárioDesnecessárioDesnecessárioDesnecessário

...

formato

...

Opcional

...

Opcional2

...

Opcional1

...

Opcional3DesnecessárioDesnecessário
Informações
titleImportante
  1. Para utilização do Blat, é necessário encontrar o arquivo

...

  1. interfac/mail/blat.

...

  1. exe na estrutura de diretórios do produto. Caso não seja encontrado, o e-mail não será enviado

...

  1. . O arquivo

...

  1. blat.

...

  1. exe é distribuído gratuitamente junto às mídias/pacotes dos produtos Datasul.
  2. Só é possível configurar servidor Exchange Outlook 2000 ou posterior.
  3. Não é possível enviar e-mail no formato HTML

...

  1. quando existir arquivo anexo no UNIX.
  2. Campo utilizado para a funcionalidade Responder Para
  3. Par envio de anexos via Datasul Mail Service deve ser utilizada a tabela ttAttachment.


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 caso a mensagem do e-mail possuísse mais 32 Kb 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 essa limitação.

Painel
borderColororange
borderStyledashed
AtributoTipoValor InicialDescrição
seq-mensageminteger
Sequência da mensagem
mensagemcharacter
Conteúdo da mensagem


ttAttachment

Possui informações dos arquivos que serão anexos ao e-mail.

Painel
borderColororange
borderStyledashed
AtributoTipoValor InicialDescrição
fileNameCharacter
Nome do arquivo
fileTypeCharacter
Tipo de arquivo em formato MIME type. Se não for informado, o valor será definido de acordo com a extensão do arquivo.
fileContentBlob
Conteúdo do arquivo em formato binário
Informações

O envio de anexos via Datasul Mail Service funciona somente através da tabela ttAttachment.

A tabela pode ser utilizada também para os outros métodos de envio.

tt-paramEmail

Indica somente o tipo de envio de e-mail (campo caminhoEmail) e sua evolução segue na definição da TempTable tt-paramEmail2, abaixo.

tt-paramEmail2

Informações

A include utapi019.i2 contempla a Definição da TempTable tt-paramEmail2 como forma de evolução da api utapi019, de modo a seguir o Guia TOTVS de Implementação de APIs.

Indica tipo de envio de e-mail, usuário e senha para autenticação no servidor de e-mail caso venha a ser necessário, opção de ativar comportamento de resposta do para utilização de remetente padrão.

Painel
borderColororange
borderStyledashed
AtributoTipoValor InicialDescrição
caminhoEmailinteger1

Esse campo pode receber os seguintes valores:
0-Unix
1-Blat
2-Exchange
3-Java
4-MailSend (SSL)

5-Datasul Mail Service

Informações

Caso for atribuído um valor diferente desses, o valor padrão será BLAT

mailUsercharacter
Código do usuário para autenticação (se necessário)
mailPasscharacter
Senha do usuário para autenticação (se necessário)
TLSlogicalnoProtocolo - Apenas para Datasul Mail Service
SSLlogicalnoProtocolo - Apenas para Datasul Mail Service
DebuglogicalnoAtiva o debug para o servidor de aplicação
remetentelogicalnoRemetente do envio de e-mail
ativaRemetPadrao (*)logicalno

Ativa o comportamento "Responder Para" (*)

codRemetPadrao (*)character
Código (e-mail) do remetente que ira receber a resposta, caso o campo logico ativaRemetPadrao estiver como yes (*)

(aviso)  Os parâmetros acima (tt-paramEmail2) não são obrigatórios, caso não sejam informados, serão utilizadas as informações da tela de parâmetros de e-mail do foundation (btb962zb).

Informações
titleImportante:

(*) Estes dois campos só funcionam com o tipo de envio de e-mail Datasul Mail Service. Os mesmo foram incluídos na release 12.1.23.

Aviso
titleAtenção:

Para execução do programa de teste do Datasul Mail Service na release 12.1.29 o supra citado deverá ser compilado, ou, deve possuir no propath a include prgvers.i, nesta versão ainda existia um pré-processador de versão que é utilizado em tempo de compilação, o progress na execução de um código no editor realiza a compilação para realizar a execução, desta forma, se o programa de exemplo for compilado, ou, existir a include no propath o erro de "O parâmetro identificador de temp-table tt-paramEmail2 não confere com a temp-table destino tt-paramEmail2. (5363)" não irá ocorrer.

 

tt-erro

Possui os erros encontrados pela API.

Painel
borderColororange
borderStyledashed
AtributoTipoValor InicialDescrição
cod-errointeger
Número do erro
desc-errocharacter
Descrição do erro
desc-arqcharacter
Caminho do arquivo que não pode ser anexado, por se tratar de envio de mensagem no ambiente UNIX.


Âncora
replyto
replyto
Funcionalidade Responder Para

A funcionalidade Responder Para serve foi criada para que a resposta do e-mail seja direcionada para um endereço diferente do que o utilizado para o envio, por exemplo, equipes de marketing. Caso a função seja ativada, a resposta ao e-mail será enviada ao valor informado no campo "remetente" da tabela tt-envio2. Caso este campo não esteja preenchido, será utilizado o remetente informado no cabeçalho do e-mail. Para decisão do remetente do e-mail enviado será utilizada a seguinte estrutura:

  1. campo "codRemetPadrao" da tabela tt-paramEmail2;
  2. campo "Remetente Padrão" da tela Parâmetros Email Foundation (BTB962ZB);
  3. campo "remetente" da tabela tt-envio2

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 caso a mensagem do e-mail possuísse mais 32 Kb 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 essa limitação.

...

ttAttachment

Possui informações dos arquivos que serão anexos ao e-mail.

...

tt-paramEmail

Indica tipo de envio de e-mail, usuário e senha para autenticação no servidor de e-mail caso venha a ser necessário, opção de ativar comportamento de resposta do para utilização de remetente padrão.

...

Esse campo pode receber os seguintes valores:
0-Unix
1-Blat
2-Exchange
3-Java
4-MailSend (SSL)

5-DatasulMailServer

*** Caso for atribuído um valor diferente desses, o valor padrão será BLAT

...

(aviso)  Os parâmetros acima (tt-paramEmail) não são obrigatórios, caso não sejam informados, serão utilizadas as informações da tela de parâmetros de e-mail do foundation (btb962zb).

*Estes dois campos só funcionam com para o tipo de envio de e-mail DatasulMailService, os mesmo foram incluídos na release 12.1.23.

tt-erro

Possui os erros encontrados pela API.

...

  1. .

Execução

A API possui um método que pode ser executado:

  1. pi-execute4: recebe cinco temp-tables como parâmetros: tt-envio2 (INPUT), tt-mensagem (INPUT), tt-paramEmail (INPUT), ttAttachment (INPUT) e tt-erros (OUTPUT).

A API irá executar duas validações básicas:

  1. Versão de integração: verifica se o programa chamador está íntegro com a API, e isto ocorre 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 a mensagem 3941.
  2. Inconsistência ou insuficiência de dados: verifica a inconsistência e/ou insuficiência dos dados. Isto ocorre 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.

Existem dois retornos possíveis para a execução da API:

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

...

  1. erros.

Exemplos

Nota
titleAtenção

Para correto funcionamento dos exemplos, os mesmo devem ser compilados antes da execução

...

Bloco de código
titleDatasul Mail Service
linenumberstrue
{utp/utapi019.i2}

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

CREATE tt-envio2.
ASSIGN tt-envio2.versao-integracao = 1
       tt-envio2.

...

destino   = "[email protected]"	
	   tt-envio2.remetente = "pedro.

...

[email protected]"
	   tt-envio2.

...

assunto   =

...

"teste envio DATASUL MAIL SERVICE".

CREATE ttAttachment.
ASSIGN

...

ttAttachment.fileName    = "

...

teste.txt"
       ttAttachment.fileType

...

 = "text/plain"

...

.

// COPIANDO CONTEÚDO DE ARQUIVO DO COMPUTADOR PARA O CAMPO BLOB
COPY-LOB FILE "C:\teste.txt" TO ttAttachment.fileContent.   //conteúdo do arquivo em formato binário


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

CREATE tt-paramEmail2.
ASSIGN tt-paramEmail2.caminhoEmail = 5.

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.
ELSE
    MESSAGE "OK" VIEW-AS ALERT-BOX.

DELETE PROCEDURE h-utapi019.
Dica
titleObservações:.

1)     Os valores para os campos mensagem, importancia, log-enviada, log-lida e acomp podem ser desconsiderados na tabela tt-envio2 porque não influenciarão no funcionamento.

2)     Os valores para os campos servidor e porta são opcionais para a tabela tt-envio2. Caso não sejam informados, serão utilizados os valores cadastrados nos parâmetros de e-mail.

3)     Os valores para os campos mailUser, mailPass, TLS, SSL, debug, ativaRemetPadrao e codRemetPadrao podem ser desconsiderados na tabela tt-paramEmail2 porque não

...

influenciarão no funcionamento.

4)     Não é necessário

...

popular a temp-table tt-paramEmail2 com dados, porém é obrigatório sua definição.

Bloco de código
titleE-mail - BLAT
linenumberstrue
{utp/utapi019.i2}

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

CREATE tt-envio2.
ASSIGN tt-envio2.versao-integracao = 1
	   tt-envio2.servidor          = "servidor"
       tt-envio2.porta             = 999
	   tt-envio2.exchange          = FALSE
	   tt-envio2.destino           = "destino@dominio"
	   tt-envio2.remetente         = "remetente@dominio"
	   tt-envio2.assunto           = "teste envio BLAT"
	   tt-envio2.arq-anexo         = "XXXXX".

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

CREATE tt-paramEmail2.
ASSIGN tt-paramEmail2.caminhoEmail = 1.

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.
ELSE
    MESSAGE "OK" VIEW-AS ALERT-BOX.

DELETE PROCEDURE h-utapi019.
Dica
titleObservações:.

1)    Os valores para os campos mensagem, importância, log-enviada, log lida e acomp podem ser desconsiderados na tabela tt-envio2 porque não influenciarão no funcionamento.

2)

...

     Os valores para os campos mailUser, mailPass, TLS, SSL, debug, ativaRemetPadrao e codRemetPadrao podem ser desconsiderados na tabela tt-paramEmail2 porque não

...

influenciarão no funcionamento.

3)

...

     Não é necessário

...

popular a temp-table tt-paramEmail2 com dados, porém é obrigatório sua definição.

  

Bloco de código
titleMS-Exchange
{utp/utapi019.i2}

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


CREATE tt-envio2.
ASSIGN tt-envio2.versao-integracao = 1
	   tt-envio2.destino           = "destino@dominio"
	   tt-envio2.assunto           = "teste envio EXCHANGE"
	   tt-envio2.arq-anexo         = "XXXXX"
	   tt-envio2.importancia       = 1
	   tt-envio2.log-enviada       = TRUE
	   tt-envio2.log-lida          = TRUE.

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


CREATE tt-paramEmail2.
ASSIGN tt-paramEmail2.caminhoEmail = 2.
 
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.
ELSE
    MESSAGE "OK" VIEW-AS ALERT-BOX.


DELETE PROCEDURE h-utapi019.
Dica
titleObservações:.

1)     Os valores para os campos servidor, porta, remetente e mensagem podem ser desconsiderados na tabela tt-envio2 porque não influenciarão no funcionamento.

2)     Os valores para os campos mailUser, mailPass, TLS, SSL, debug, ativaRemetPadrao e codRemetPadrao podem ser desconsiderados na tabela tt-paramEmail2 porque não

...

influenciarão no funcionamento.

3)     Não é necessário

...

popular a temp-table tt-paramEmail2 com dados, porém é obrigatório sua definição.

4)     Os campos importancia, log-enviada, log-lida e acomp só influem neste tipo de execução e são opcionais.


Pontos de customização

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

Nota
titleOBS:

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 por meio dos dados informados nos parâmetros.

Bloco de código
titleExemplo de UPC - BLAT
linenumberstrue
{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.

O nome do evento pode possuir os seguintes valores:


Painel
borderColororange
borderStyledashed
  • eMailUnix: evento para customização de envio em UNIX (tt-paramEmail.caminhoEmail = 0);
  • eMailBlat: evento para customização de envio via BLAT (tt-paramEmail.caminhoEmail = 1);
  • SaveEmail: evento para customização de envio via Exchange (tt-paramEmail.caminhoEmail = 2);
  • eMailJava: evento para customização de envio via JAVA (tt-paramEmail.caminhoEmail = 3);
  • eMailSend: evento para customização de envio via MailSend (tt-paramEmail.caminhoEmail = 4).