Histórico da Página
Objetivo
Utilização da API utapi019 para envio de mensagens pelo servidor de correio eletrônico..
Informações | ||
---|---|---|
| ||
|
Fontes
$/FOUNDATION/Fontes_Doc/Sustentacao/V11/V11/progress/src/utp
- utapi019.p
- utapi019.i
- utapi019.i1
- utapi019.i2
Considerações gerais
Âncora | ||||
---|---|---|---|---|
|
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.
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. Caso 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. Caso 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. | |
copia | character | 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". | |
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 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. | |
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 | DatasulMailService | EXCHANGE | BLAT/OCX | SENDMAIL (UNIX) | JAVA | MAILSEND (SSL) |
---|---|---|---|---|---|---|
versao-integracao | Obrigatório | Obrigatório | Obrigatório | Obrigatório | Obrigatório | Obrigatório |
servidor | Opcional | Desnecessário | Opcional | Opcional | Obrigatório | Obrigatório |
porta | Opcional | 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 | Opcional(*) | Desnecessário | Obrigatório | Opcional | Obrigatório | Obrigatório |
assunto | Obrigatório | Opcional | Obrigatório | Opcional | Obrigatório | Obrigatório |
mensagem | Obrigatório | Obrigatório | Obrigatório | Obrigatório | Obrigatório | Obrigatório |
arq-anexo | Opcional | Opcional | Opcional¹ | Opcional³ | Opcional | Opcional |
importancia | Desnecessário | Opcional | Desnecessário | Desnecessário | Desnecessário | Desnecessário |
log-enviada | Desnecessário | Opcional | Desnecessário | Desnecessário | Desnecessário | Desnecessário |
log-lida | Desnecessário | Opcional | Desnecessário | Desnecessário | Desnecessário | Desnecessário |
acomp | Desnecessário | Opcional | Desnecessário | Desnecessário | Desnecessário | Desnecessário |
formato | Opcional | Opcional² | Opcional¹ | Opcional³ | Desnecessário | Desnecessário |
Informações | ||
---|---|---|
| ||
|
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.
Atributo | Tipo | Valor Inicial | Descrição |
---|---|---|---|
seq-mensagem | integer | Sequência da mensagem | |
mensagem | character | Conteúdo da mensagem |
ttAttachment
Possui informações dos arquivos que serão anexos ao e-mail.
Atributo | Tipo | Valor Inicial | Descrição |
---|---|---|---|
fileName | Character | Nome do arquivo | |
fileType | Character | Tipo de arquivo em formato MIME type. Se não for informado, o valor será definido de acordo com a extensão do arquivo. | |
fileContent | Blob | Conteúdo do arquivo em formato binário |
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 |
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.
Atributo | Tipo | Valor Inicial | Descrição | ||
---|---|---|---|---|---|
caminhoEmail | integer | 1 | Esse campo pode receber os seguintes valores: 5-DatasulMailService
| ||
mailUser | character | Código do usuário para autenticação (se necessário) | |||
mailPass | character | Senha do usuário para autenticação (se necessário) | |||
TLS | logical | no | Protocolo - Apenas pra DatasulMailService | ||
SSL | logical | no | Protocolo - Apenas para o MailSend | ||
Debug | logical | no | Ativa o debug para o servidor de aplicação | ||
remetente | logical | no | Remetente do envio de e-mail | ||
ativaRemetPadrao (*) | logical | no | Estando como "yes" ativa o comportamento de "responder para", onde o remetente será sempre o from alias e o remetente padrão será quem receberá a resposta do e-mail;(*) | ||
codRemetPadrao (*) | character | Código (e-mail) do remetente que ira receber a resposta, caso o campo logico ativaRemetPadrao estiver como yes.(*) |
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 | ||
---|---|---|
| ||
* Estes dois campos só funcionam com 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.
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. |
Execução
A API possui um método que pode ser executado:
- 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:
- 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.
- 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:
- OK: Mensagem enviada com sucesso.
- NOK: Envio de mensagem abortado. Os erros encontrados serão retornados por meio da temp-table tt-erros.
Exemplos
Bloco de código | ||||
---|---|---|---|---|
| ||||
{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 = "[email protected]" tt-envio2.assunto = "teste envio DATASUL MAIL SERVICE" tt-envio2.arq-anexo = "C:\teste.txt". 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 | ||
---|---|---|
| ||
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 | ||||
---|---|---|---|---|
| ||||
{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 | ||
---|---|---|
| ||
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 | ||
---|---|---|
| ||
{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 | ||
---|---|---|
| ||
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 | ||
---|---|---|
| ||
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 | ||||
---|---|---|---|---|
| ||||
{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:
- 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).