Histórico da Página
...
- 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á 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 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 de UPC chamado eMailBlat, que permite ao cliente 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 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 dos tipos de arquivos anexados a mensagem, nem outros tipos de tratamento que um serviço de e-mail realiza. Caso ocorra alguma destas validações que a API não trata, será tratado 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 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 para os envios padrões do produto. Essa funcionalidade só pode ser utilizada com programas específicos que utilizarem a API. No decorrer desta documentação serão detalhados os procedimentos para utilização.
Temp-tables
...
tt-envio2
Possui definições da mensagem a ser enviada.
Atributo | Tipo | Valor Inicial | Descrição |
---|---|---|---|
versao-integracao | integer | Versão de integração da API. | |
servidor | character | Hostname ou endereço IP do servidor de e-mail. Se não informado, é utilizado o cadastro dos parâmetros de e-mail do produto. | |
porta | integer | 0 | Número da Porta do servidor de e-mail. Se não informado, é utilizado o cadastro dos parâmetros globais do produto. Só influencia quando utilizado OCX para envio da mensagem. |
exchange | logical | no | Utilizar servidor Exchange para envio da mensagem. |
destino | character | Destinatário(s) da mensagem. Quando é mais de um, devem ser separados por vírgulas. Deve ser informado obrigatoriamente. Quando for utilizado para envio de fax, deve ser passada a inicial “[fax:número]”. | |
copia | character | Cópia Carbono da mensagem. Quando é mais de um, devem ser separados por vírgulas. Para ambiente UNIX, os endereços adicionados neste campo serão incluídos no campo "para". | |
remetente | character | 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. | |
assunto | character | Assunto da mensagem. | |
mensagem | character | Corpo da mensagem. Informação obrigatória. | |
arq-anexo | character | Caminho completo do arquivo a ser anexado na mensagem. Disponível apenas para envio de mensagem através de MS-Exchange, Blat, Java e UNIX. Em outros casos, é incorporado na mensagem, o caminho do arquivo. Para anexar mais de um arquivo os mesmos devem ser separados por virgula. | |
importancia | integer | 0 | Ní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-enviada | logical | no | Envia uma mensagem para o remetente assim que a sua mensagem original for enviada. Só influencia quando utilizado servidor Exchange. |
log-lida | logical | no | Envia uma mensagem para o remetente assim que a sua mensagem original for lida. Só influencia quando utilizado servidor Exchange. |
acomp | logical | yes | Execução do utilitário ut-acomp, para verificar o desenvolvimento da execução. Só influencia quando utilizado servidor Exchange. |
formato | character | Texto | Aceita 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:
Atributo | EXCHANGE | FAX | BLAT/OCX | SENDMAIL (UNIX) | JAVA | MAILSEND (SSL) |
---|---|---|---|---|---|---|
versao-integracao | Obrigatório | Obrigatório | Obrigatório | Obrigatório | Obrigatório | Obrigatório |
servidor | Desnecessário | Desnecessário | Opcional | Opcional | Obrigatório | Obrigatório |
porta | Desnecessário | Desnecessário | Opcional | Desnecessário | Obrigatório | Obrigatório |
destino | Obrigatório | Obrigatório | Obrigatório | Obrigatório | Obrigatório | Obrigatório |
copia | Opcional | Opcional | Opcional | Desnecessário | Desnecessário | Opcional |
remetente | Desnecessário | Desnecessário | Obrigatório | Opcional | Obrigatório | Obrigatório |
assunto | Opcional | Opcional | Obrigatório | Opcional | Obrigatório | Obrigatório |
mensagem | Obrigatório | Obrigatório | Obrigatório | Obrigatório | Obrigatório | Obrigatório |
arq-anexo | Opcional | Obrigatório | Opcional¹ | Opcional³ | Opcional | Opcional |
importancia | Opcional | Desnecessário | Desnecessário | Desnecessário | Desnecessário | Desnecessário |
log-enviada | Opcional | Desnecessário | Desnecessário | Desnecessário | Desnecessário | Desnecessário |
log-lida | Opcional | Desnecessário | Desnecessário | Desnecessário | Desnecessário | Desnecessário |
acomp | Opcional | Desnecessário | Desnecessário | Desnecessário | Desnecessário | Desnecessário |
formato | Opcional² | Desnecessário | Opcional¹ | Opcional³ | Desnecessário | Desnecessário |
1 - Utilização do Blat. É 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.
2 - Devido a limitações técnicas, só é possível enviar e-mail no formato HTML utilizando Outlook 2000 ou posterior.
3 - Devido a limitações técnicas, 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 mensagem do e-mail possuísse mais 32 Kb acontecia o erro 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 limitação.
Atributo | Tipo | Valor Inicial | Descrição |
---|---|---|---|
seq-mensagem | integer | Sequência da mensagem | |
mensagem | character | Conteúdo da mensagem |
tt-erro
Possui os erros encontrados pela API.
Atributo | Tipo | Valor Inicial | Descrição |
---|---|---|---|
cod-erro | integer | Número do erro | |
desc-erro | character | Descrição do erro | |
desc-arq | character | Caminho do arquivo que não pode ser anexado, por se tratar de envio de mensagem no ambiente UNIX. |
tt-paramEmail
Indica tipo de envio de e-mail.
Atributo | Tipo | Valor Inicial | Descrição |
---|---|---|---|
caminhoEmail | integer | 1 | Esta campo pode receber os seguintes valores: |
Execução
...
A API irá executar duas validações básicas:
- Versão de integração: verifica se o programa chamador está íntegro com a API, e isto ocorre através 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 3941.
- Inconsistência ou insuficiência de dados: verifica a inconsistência e/ou insuficiência dos dados. Isto ocorre através 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:
- OK: Mensagem enviada com sucesso.
- NOK: Envio de mensagem abortado. Os erros encontrados serão retornados através da temp-table tt-erros.
Exemplos
...
Bloco de código | ||||
---|---|---|---|---|
| ||||
{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. |
Observações:
- Para o envio de FAX, é necessário que esteja instalado algum software client de envio de FAX.
- Quando a API de envio de FAX/MAIL for utilizada para envio de FAX, o campo tt-envio2.destino deve seguir a seguinte sintaxe – “[fax:número]”.
- Caso haja a necessidade de se enviar mais de 32kb de texto, a mensagem que será apresentada no FAX, deve estar dentro do arquivo anexo.
Bloco de código | ||||
---|---|---|---|---|
| ||||
{utp/utapi019.i}
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>".
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:
DISP tt-erros WITH 1 COLUMN WIDTH 300.
END.
END.
DELETE PROCEDURE h-utapi019. |
Observações:
- Campo "exchange" retirado da tt-envio2, pois valor inicial é "no".
- Campo "remetente" é obrigatório e deve ter um valor válido.
- Campo "copia" é opcional.
- Temp-table tt-paramEmail não é necessária, pois valor padrão do envio de e-mail é o BLAT.
Bloco de código | ||
---|---|---|
| ||
{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. |