Gerenciador de Emails

Introdução

Este módulo EmailSender é responsável pela criação de grupos de destinatários de emails e configuração de acesso a um servidor de email para envio. Com este módulo a aplicação desenvolvida no ambiente tem acesso via scripts ao envio de emails para um ou mais grupos na ocorrência de um evento qualquer que deve ser notificado.

../_images/ems.jpg — Fig. Módulo de gerênciade E-mail

Visão geral da interface módulo EmailSender

O módulo EmailSender quando ativado, disponibiliza recursos para configuração do acesso a um servidor de email e criação de grupos de email. O módulo opera em plataforma windows, compatível com as versões XP, NT, Vista e Windows 7 (versões anteriores do windows não são compatíveis). Uma vez ativado, o EmailSender apresenta a seguinte tela:

../_images/abertura.jpg — Fig. Painel de projeto e editor de propriedades

Através dos menus e da barra de botões (área horizontal na parte superior) estão disponíveis os seguintes comandos:

Arquivo
Ícone	Item do Menu	Descrição	Tecla de atalho
	Salva projeto	Salva as alterações efetuadas no projeto corrente.	Ctrl+S
	Encerrar aplicação	Fecha o módulo. Se houverem alterações não salvas no projeto é solicitado ao usuário para salvar estas modificações antes de fechar.	(Nenhuma)

Edita
Ícone	Item do Menu	Descrição	Tecla de atalho
	Copia	Quando habilitado permite a cópia do item selecionado para área de transferência.	Ctrl+C
	Corta	Quando habilitado permite a exclusão do item selecionado mantendo uma cópia do mesmo na área de transferência.	Ctrl+X
	Cola	Cria um novo item no local selecionado a partir de uma cópia armazenada na área de transferência.	Ctrl+V
	Traz para frente	Move o item selecionado para o fim da lista que o contém.	(Nenhuma)
	Move para o anterior	Move o item selecionado uma posição para cima na lista que o contém.	(Nenhuma)
	Move para próximo	Move o item selecionado uma posição para baixo na lista que o contém.	(Nenhuma)
	Envia para trás	Move o item selecionado para o início da lista que o contém.	(Nenhuma)
	Adiciona Item	Quando selecionado, apresenta um submenu com a lista dos itens que podem ser inseridos como subitem do item selecionado.	(Nenhuma)
	Elimina Item	Elimina o item selecionado se o mesmo pode ser removido. Sempre apresenta uma mensagem de confirmação para efetivar a remoção do item.	Del

Suporte
Ícone	Item do Menu	Descrição	Tecla de atalho
	Informações sobre o produto	Tela com informações do HIscada Pro -Ide, tais como, versão, compilação e liberação.	Nenhuma
	http://www.hitecnologia.com.br	Abre o site da HI Tecnologia no navegador para consulta ao HIscada Pro e outras informações.	Nenhuma
	Contate a HI Tecnologia	Abre o aplicativo de email padrão instalado no computador do usuário apresentando um email com destinatário preenchido, caso o usuário queira enviar um email para o setor de suporte da HI Tecnologia.	Nenhuma

Painéis da Interface do módulo EmailSender

O aplicativo EmailSender possui na sua interface de operação 2 painéis distintos denominados Painel de Projeto e Editor de Propriedades conforme indicado na figura a seguir.

Painel de Projeto

Localizado na parte superior da tela principal do EmailSender, o Painel de Projeto é responsável por apresentar todos os itens utilizados pela interface da aplicação na forma de uma árvore hierárquica. Assim o usuário tem uma visão da estrutura da aplicação com suas dependências e relacionamentos, podendo acessar o conteúdo de qualquer dos itens clicando na sua representação na arvóre apresentada.
Editor de Propriedades

Localizado na parte inferior (abaixo do painel de projeto) da tela principal do EmailSender, o Editor de Propriedades é responsável por apresentar os atributos do item selecionado no Painel de Projeto, quando estes atributos exigem interação com o usuário da aplicação na forma de visualização do seu conteúdo e/ou edição do mesmo.

Operação do módulo EmailSender

Os parágrafos seguintes descrevem as operações principais que podem ser realizadas no ambiente do módulo EmailSender.

Configurando acesso ao servidor de email

Uma vez ativado o módulo em um novo projeto deve-se configurar o acesso ao servidor de email desejado. Este procedimento é realizado selecionando no painel de projetos o item Projeto. Esta ação irá apresentar no editor de propriedades, os atributos necessários para configuração do acesso ao servidor de email desejado, conforme indicado na figura anterior. São os seguintes os parâmetros a serem configurados:

Parâmetros de acesso ao servidor de email
Atributo	Descrição	Valor Inicial
Tipo de criptografia	Especifique se o servidor de email utilizado utiliza uma conexão segura para acesso. Opções de criptografia: Nenhuma TLS SSL	Nenhuma
Endereço do servidor de email	Especifique o endereço (URL) de acesso ao servidor de email desejado.
Porta ethernet	Especifique a porta de escuta do servidor de email desejado. Note que apesar da porta padrão de email ser a porta 25, atualmente a maioria dos servidores com conexão segura não utilizam esta porta de acesso.	25
Aplicação que enviou o email	Especifique o nome da aplicação que está enviando o email. Esta informação é opcional e é inserida no campo mail agent do email a ser enviado. Note que este parâmetro também pode ser especificado pela aplicação que utiliza o EmailSender.	EmailSender
Nome do usuário para autenticação	Especifique o nome do usuário para abertura da conexão ssl com o servidor quando o mesmo possuir esta funcionalidade.
Senha de autenticação	Especifique o nome da senha para abertura da conexão ssl com o servidor quando o mesmo possuir esta funcionalidade.
Endereço de email que originou a mensagem	Especifique o endereço de email que será utilizado como remetente do email enviado.

Parâmetros para teste de envio
Atributo	Descrição	Valor Inicial
Assunto para o email de teste	Define um texto a ser enviado como assunto de um email de teste.	EMS - Email de teste
Corpo do email de teste	Define um texto a ser enviado como corpo de um email de teste. Este campo é opcional e pode ser mantido vazio.	Esta mensagem é apenas para teste de envio de email
Nome do arquivo de anexo	Especifique um path completo de um arquivo para ser anexado ao email de teste. Este campo é opcional e pode ser mantido vazio caso o anexo dos email de teste não seja utilizado.

Criando uma lista de destinatários

Uma vez definidos os parâmetros de configuração de acesso ao servidor de email, podemos criar uma lista de destinatários de email a ser utilizada nos grupos de email que serão posteriormente definidos. O item principal da lista de destinatários (Destinatários) é automaticamente criado durante o processo de criação do projeto, bem como um primeiro item destinatário denominado Destinatario_001. Para modificar o nome do item; com o mesmo selecionado, clique uma vez com o botão esquerdo do mouse. O texto do item entrará em modo de edição permitindo que o mesmo seja alterado. Os nomes de itens não devem utilizar caracteres de acentuação nem caracteres especiais tais como ,[]()/%$&*-+!#{}. O ambiente não permite que os nomes dos itens de destinatário sejam repetidos. Para criar um novo item destinatário, selecione o item Destinatários com o botão direito do mouse. No menu apresentado e selecione a opção Adicionar Item. Após este procedimento um novo item Destinatário_NNN será criado e adicionado na lista. Ao selecionar um item destinatário, o editor de propriedades apresenta os atributos a serem configurados no mesmo, conforme apresentado na figura a seguir.

Parâmetros de identificação do destinatário
Atributo	Descrição
Nome	Especifique o nome a ser utilizado para identificar o destinatário no email enviado.
Email	Especifique o endereço de email completo do destinatário.

Criando um grupo de email

Uma vez definida a lista de todos os destinatários de email do projeto, deve-se organizá-los em grupos de emails. Durante a criação do projeto o item Grupos de Email é automaticamente criado juntamente com o item Grupo de Email_001 (criado abaixo), conforme apresentado na figura a seguir.

Identificação
Atributo	Descrição	Valor Inicial
Nome do Item	Especifique no nome do grupo criado.	GrupoEmail_001

Para criar um novo grupo de email, selecione o item Grupos de Email com o botão direito do mouse. No menu apresentado selecione a opção Adicionar Item. Após este procedimento um novo item Grupo de Email_NNN será criado e adicionado na lista. Um grupo de email reúne um conjunto de destinatários de email. Para acrescentar um membro (destinatário) a um grupo de email selecione o grupo de email desejado com o botão direto do mouse e, no menu apresentado selecione a opção Adicionar Item. Após este procedimento um novo item Membro_NNN será criado e adicionado na lista do grupo. Este item criado deverá ser associado a um destinatário do projeto. Para tanto, selecione o item Membro_NNN criado. No editor de propriedades serão apresentados os atributos associados ao item que deverão ser especificados conforme apresentado na tabel a seguir.

Parâmetros de identificação do destinatário
Atributo	Descrição
Destinatário	Especifique na lista fornecida qual o destinatário a ser acrescentado no grupo corrente.
Tipo de Lista	Especifique na lista fornecida se o email do destinatário será inserido na lista de Para:, cc: ou cco.

Enviando um email de teste

Terminada a definição dos grupos de email o projeto do módulo EmailSender está concluído e deve ser salvo (CTRL+S) para posterior utilização. Existe um recurso no ambiente que permite enviar um email de teste para qualquer um dos grupos criados, facilitando assim a validação da configuração dos parâmetros de acesso ao servidor de email, bem como dos destinatários definidos. Para utilizar este recurso, primeiramente configure os Parâmetros para teste de envio presentes no item de projeto. Em seguida selecione o item do grupo que se deseja enviar um email de teste, conforme apresentado na figura a seguir.

Ao selecionar o grupo, o editor de propriedades apresenta a linha com o título Envia email de teste para o grupo. Á frente do texto é apresentado um botão que, quando pressionado envia um email para todos os membros do grupo selecionado, utilizando o servidor de email definido no item projeto. Terminado o processo de envio, o resultado da operação é apresentado para o usuário em uma janela indicando sucesso no envio ou o tipo de erro ocorrido.

API LUA para envio de email

Função: SendEmail

Descrição

Esta API disponibiliza recursos para envio de email através de um script LUA. Sua operação necessita que o módulo EmailSender esteja integrado ao ambiente. Uma vez criado um projeto no módulo e configurado um ou mais grupos de email, esta função pode ser chamada de dentro de um script qualquer para enviar um email para um dos grupos definidos. A sintaxe da função LUA é a seguinte:

Sintaxe da função :

int result SendEmail(group, subject, body_text, attach_file, transaction_id, timeout)

Parâmetros de entrada

Entrada

group	Nome do grupo de email a ser notificado (o texto deve ser especificado entre parenteses).
subject	Texto a ser inserido no email como assunto (o texto deve ser especificado entre parenteses).
body_text	Texto a ser inserido no email como corpo do email (o texto deve ser especificado entre parenteses). Este parâmetro é opcional, quando não utilizado deve-se passar este parâmetro como string nula (“”).
attach_file	Nome (caminho completo) de um arquivo a ser anexado ao email. Este parâmetro é opcional, quando não utilizado deve-se passar este parâmetro como string nula (“”).
transaction_id	identificador numerico do email. Este parâmetro é utilizado pelo módulo de gerencia de email para identificar o email enviado. Finallizado o processo de envio, o resultado (sucesso ou falha) é salvo em um arquivo de log mantido pelo módulo (ems.log)
timeout	Tempo de em que a aplicação irá aguardar ate o envio do email se não retornará timeout.

Parâmetros de saida

String resultante com o caminho completo do arquivo selecionado pelo usuário. Se o usuário cancelar a seleção do arquivo, a função retorna uma string nula.

Saída

result

Código de retorno da função. Se zero indica execução do comando com sucesso. Se diferente de zero indica falha no envio. Possíveis códigos de retorno:

15202: Módulo de gerência de email não encontrado.
15359: Falha no processo de ativação do módulo de gerência de email.

obs

O processo de envio de email é realizado de forma assíncrona. Por este motivo, o código retornado pela função LUA indica apenas que o email foi encaminhado com sucesso para o gerenciador de email. O resultado final do processo de envio é salvo no arquivo de log do módulo de gerência de email (ems.log)

Exemplo de utilização

-- Envia email para o grupo G1 com arquivo anexado
 local result = SendEmail(
                                   "G1",                                      -- nome do grupo de email
                                   "Notificação de evento do HIscada Pro",    -- assunto
                                   "Variável Tp102 atingiu limite de alerta", -- corpo do email
                                   "c:\alm01.txt",                            -- arquivo a ser anexado ao email
                                   1010,                                      -- identificador do email (para log)
                                   5)                                         -- Timeout (segundos)

 if (result ~= 0) then
   msg = "Falha no processo de encaminhamento do email"
 else
   msg = "Email encaminhado com sucesso"
 end
 print (msg)