Почтовые процессы с новыми агентами в R5
(перевод А.Булгаков)
Вам когда-нибудь требовалось обработать поступающую почту прежде, чем она достигла почтового ящика пользователя mail.box? В Notes R5 вы можете сделать это!
Notes R5 включает новых pre-delivery почтовых агентов, которые вы можете установить на выполнение перед тем, как придёт новая почта. Это значит, что вы можете сделать такие вещи:
· Доставку сообщений в паку иную, чем Inbox, если сообщение удовлетворяет определённым критериям. Например, вы можете получать сообщения об ошибках в папку для ошибок. Поскольку агент выполняется, когда сообщение ещё в процессе доставки, то пользователь не видит, как оно приходит в Inbox, а затем перемещается в другую папку.
· Удалять большие вложения из писем перед тем, как они будут доставлены пользователю. Агент удаляет большие вложения перед тем, как письмо будет доставлено в почтовый ящик пользователя; таким образом вы можете сохранить дисковое пространство и устранить потребность копировать дополнительные данные.
· Определение (основанное на каких-либо данных), что сообщение не может быть доставлено и удаление его. Например, вы можете удалить сообщения от некоего пользователя «Spam». Таким образом вы можете сохранить пространство вашего диска и уменьшить размер реплики базы.
Эта статья расскажет больше о pre-delivery агентах и о том, как вы можете использовать их, чтобы выполнить эти операции. Мы расскажем о поведении агента, ограничениях, наложенных на этот тип и ситуациях, в которых лучше использовать этот, нежели post-delivery почтовый агент. Затем мы посмотрим как отлаживать агенты и пробежимся по нескольким специфическим примерам. Как вы увидите, эти агенты могут быть полезными для увеличения свободного места и повышения эффективности.
Замечание: Предшествующие версии Lotus/Domino не знали pre-delivery агентов и нового триггера типа «Before new mail arrives». Если сервер R5, на котором разрешены и действуют pre-delivery агенты, допустил сбой, роутер доставит почту без выполнения этих агентов. Вы можете создать pre-delivery агент на R5 клиенте и затем попытаться редактировать или выключит его на pre-R5 клиенте, то вам вернётся сообщение об ошибке: агент имеет неизвестный триггер.
Введение в pre-delivery почтовые агенты
Почтовые агенты в R5 теперь входят в два типа разновидностей, согласно которым они работают: перед приходом новой почты, после прихода новой почты. Pre-delivery агенты идентифицируются новым почтовым триггером: «Before new mail arrives». Cтарыt версии R4.x почтовых агентов всё ещё поддерживаются в R5, такие агенты идентифицируются как агент триггера «After new mail arrives». Мы ссылаемся на эти агенты как на post-delivery почтовые агенты. Следующая картинка показывает новые почтовые триггера агентов:
Pre-delivery почтовые агенты обрабатывают почту прежде, чем она поступает в почтовую базу пользователя; для примера, перемещая входящую почту в папку.
Агенты запускаются почтовым роутером, это гарантирует, что он будет выполнен прежде, чем письмо будет доставлено пользователю. В противоположность, post-delivery почтовые агенты запускаются после того, как письмо придёт в почтовую базу пользователя. Таким образом вы можете использовать post-delivery агенты для операций, которые не зависят от выбора времени при доставке почты, например для ответов на почтовые сообщения.
Хотя вы можете использовать оба типа агентов в вашей почтовой базе, вы можете использовать только один pre-delivery агент за раз. Вы можете иметь неограниченное число выключенных pre-delivery агентов. В дополнение вы можете иметь неограниченное число post-delivery агентов, как разрешённых, так и запрещённых. Обратите внимание, что синяя стрелка ниже переключателя идентифицирует текущее состояние агента (разрешенно) для pre-delivery агентов:
Порядок выполнения:
Если вы разрешили оба, pre-delivery и post-delivery агентов в вашей почтовой базе, pre-delivery агент всегда выполняется первым (перед тем, как сообщение будет отправлено в почтовую базу). Затем выполняется post-delivery агент (после того, как сообщение было доставленно в почтовую базу). Рost-delivery агенты выполняют обработку новых сообщений, даже если pre-delivery агенты переместили их в другую папку. Если pre-delivery агент удалил почтовое сообщение, оно никогда не будет доставленно в почтовую базу. Это значит, что рost-delivery агенты не запускаются для обработки этого сообщения.
В дополнение к почтовым агентам, R5 обеспечивает две другие опции фильтрации почты: новый router controls и шаблоны почтовых правил. Вы можете использовать встроенные средства управления для роутера (трассировщика) для разрешения приёма почты только из определённого домена, только из определённой организации, запретить приём почты из определённой организации и поставить ограничения на размер входящей почты. С помощью шаблонов почтовых правил вы можете задать приём сообщения только от определённого отправителя ( например вашего босса), или сообщения, которое содержит определённую тему, и затем выбрать что делать, когда сообщения, удовлетворяющие этим условиям поступают в базу (копировать или переместить в папку, удалить, или повысить важность сообщения).
Итак, если вы используете все опции фильтрации в R5, выполнение этих опций должно быть в следующем порядке:
Router controls проверяет, что сообщение допущено трассировщиком в домен.
Pre-delivery агенты выполняют обработку почтового сообщения.
Выполняются действия, заданные в почтовых правилах
Рost-delivery агенты выполняют обработку почтового сообщения.
Настройки конфигурации:
Поскольку pre-delivery агенты выполняются роутером, установки Agent Manager не имеют влияние на эти агенты. Параметры этого типа агентов устанавливаются в отдельной закладке документа конфигурации. Первое, pre-delivery агенты имеют задаваемое максимальное время выполнения, определённое в поле "Pre-delivery agent timeout", на закладке Router/SMTP /Restrictions and Controls/Delivery Controls документа Configuration settings (см. картинку ниже). По умолчанию это время равно 30 секундам.
(Lotus Script и Java агенты, которые запускаются, для других триггеров используется время выполнения, определённое на закладке Server Tasks/Agent Manager в документе Server.)
Если время выполнения агента превышает максимальный таймаут, он аварийно завершается. Событие terminate позволяет вам, как писателю агента, сделать минимальное количество работы, что бы навести порядок. Если вы пишете в Lotus Script, любые файлы, которые агент откроет, закроются автоматически. Если вы пишете агент на Java JVM(Java Virtual Machine) учитывает все объекты, использованные в агенте, для очистки коллекции. Хотя это не может произойти немедленно, JVM закрывает все открытые файлы, только когда соответствующие объекты будут собраны.
Кроме того, вы можете управлять количеством параллельных pre-delivery агентов, это можно сделать, изменяя максимальное число потоков доставки роутером (в одном потоке- один агент), определённым на закладке "Router/SMTP" /Restrictions and Controls/Delivery Controls документа Configuration Settings. Число потоков доставки может варьироваться от 3 до 25. По умолчанию Domino определяет число потоков базируясь на исполнительских характеристиках сервера.
Разработка с pre-delivery почтовыми агентами
При проектировании вашего приложения для обработки почты, вы можете использовать как pre-delivery, так и post-delivery агенты. Если возможно, постарайтесь разделять обработку-до прихода почты делать наиболее критические операции, а все остальные операции выполнять после прихода новой почты. Для примера, вы можете иметь pre-delivery агент, который удаляет большие вложения и затем, устанавливает флаг, когда эта операция выполнена. Затем, post-delivery агент может уведомить почтового отправителя, что сообщение содержало слишком большое вложение, чтобы его можно было доставить. Посмотреть саммари ( краткий обзор) что могут делать pre-delivery и post-delivery агенты можно по этой ссылке: «Сравнение post-delivery и pre-delivery почтовых агентов»
Когда вы начинаете разрабатывать ваш pre-delivery агент, вы должны держать следующие вещи в уме:
· pre-delivery агенты имеют встроенные ограничения, гарантирующие их эффективность
· Есть некоторый ключ, кодирующий различия между pre-delivery и post-delivery агентами.
· Pre-delivery агенты могут запускаться автоматически, когда на сервере произошёл сбой и он перезагрузился (динамическое востановление после отказа).
· Операции с папками происходят иначе для pre-delivery агентов
· Отладка pre-delivery отлична от отладки других типов агентов.
Следующая секция описывает каждый из этих пунктов более детально.
Встроенные ограничения для pre-delivery агентов
Поскольку выполнение pre-delivery агентов производится роутером (трассировщиком почты), то для этих агентов жизненно важно быть как можно короче и эффективнее. В противном случае они могут замедлить работу роутера, что может быть очень нежелательным для работы сервера. Таким образом, чтобы помочь гарантировать эффективную работу pre-delivery агентов, мы установили следующие ограничения для этих типов агентов:
· Как упомянуто раньше, вы можете использовать лишь один pre-delivery агент в каждой базе данных. Это позволяет Domino извлекать агентов наиболее эффективным способом для любого числа пользователей.
· Вы не можете установить pre-delivery агент запускать другой агент. Это облегчает эффективное кэширование схемы.
· Вы не можете устанавливать pre-delivery агенты модифицировать почтовые вложения. Агенты могут только рассматривать вложения и отделять их от письма. К настоящему времени нет методов, которые могли бы модифицировать вложения; вы можете модифицировать их только использовав OLE операции. Следовательно, это ограничение значит, что методы Activate и DoVerb на объектах NotesEmbeddedObject не разрешены.
· Как упомянуто раньше, максимальное время выполнения для pre-delivery агентов выделяет их из других агентов, и мы рекомендуем вам ставить его значительно меньше, чем для других типов агентов. По умолчанию оно устанавливается в 30 секунд.
Кодирование различий для pre-delivery и post-delivery агентов
Запомните, что агенты pre-delivery выполняются перед тем, как новое письмо записано в почтовый ящик пользователя. Это означает, что как автор агента, вы можете не найти этот новый документ в любой коллекции, полученной из почтовой базы пользователя (ведь он может быть уже удалён). Новый документ доступен только через контекст документа. В общих чертах, вам понадобится немного модифицировать логику, которую вы использовали в агентах почты R 4.x, чтобы работать с новыми триггерами почты (это может понадобиться, когда вы захотите изменить документ, который вам поставляется).
Другие различия между post-delivery (R4.x) почтовыми агентами и новыми pre-delivery агентами заключается в том, что с новыми агентами вы знаете: эта операция будет действовать на единственном документе-новом письме, которое доставляет роутер.
В противоположность, post-delivery агенты могут выполнять операции над большим количеством документов, потому что агенты работают над всеми новыми документами, которые поступили в почтовую базу пользователя с того момента, как он был запущен.
Pre-delivery агенты при динамическом восстановлении сервера после отказа.
Роутер выполняет pre-delivery агенты на том же сервере, где он доставляет почту. Если доставка почты терпит неудачу на другом сервере, входящим в кластер, выполнение агента также прерывается (если второй сервер кластера так же R5). Роутер на втором сервере автоматически запускает pre-delivery агент на любой почте, которая приходит.
В противоположность, post-delivery агенты разрабатываются по умолчанию для работы на домашнем почтовом сервере подписавшего агент (персона, которая в последний раз модифицировала агент). Перед тем, как агенты запустятся, они выполняют проверку, является ли текущий домашний сервер сервером подписавшего агент. Домашний сервер определяется взятием имени подписавшего агент и выполнение поиска соответствующего имени в адресной книге и поиска почтового сервера из документа этой персоны (document Person). Если домашний сервер не такой же как сервер, на котором агент пытается запуститься, агент не запускается. Это означает, что агент pre-delivery не запускается, если он не находится на пользовательском почтовом сервере.
Почтовая база данных так же должна находиться на том же сервере, что и почтовый сервер, взятый из документа персоны. Вы можете изменить это установленное по умолчанию поведение, изменив в NOTES.INI значение переменной AMgr_DisableMailLookup в единицу. (в отсутствие этой переменной, считается что она установлена в ноль). Эта установка убирает проверку для домашнего почтового сервера и разрешает агенту выполняться на любом сервере. Вы должны знать, что в зависимости от логики вашего агента, разрешение ему работать на разных серверах может вызвать конфликт репликаций. (настройки в Agent Manager не имеют влияние на pre-delivery агентов, так как они выполняются роутером). Для большей информации с агентами почты смотри «Поиск неисправностей агентов»
Управление папками в pre-delivery почтовых агентах.
Pre-delivery агенты обрабатывают сообщения, пока они находятся в процессе доставки, т.е. прежде чем роутер доставит в почтовую базу пользователя. При операциях с папками это выражается в следующих специальных моментах:
· Когда роутер доставляет сообщение в почтовую базу пользователя, только одна (первая) операция PuthInFolder вступает в силу. Если ваш агент использует Java или LotusScript, следующее сообщение об ошибке появится, если будет обнаружена более, чем одна операция PuthInFolder:” Invalid sequence of operations in mail pre-delivery agent" (неправильная последовательность операций в почтовом pre-delivery агенте). Если вы спроектировали агент, основанный на простых действиях (simple action), имеющий множество операций move, то AgentLog сгенерирует предупреждение, уведомляющее вас, какие действия будут проигнорированны.
Поскольку только одна операция PuthInFolder может вступать в силу, любые вновь поставленные документы могут появиться максимум в двух папках (если не удалять из Inbox, то это Inbox и любая другая папка), но в любом количестве видов в одно и тоже время. Обратите внимание, что виды и папки - две разные вещи. Члены (документы) вида определяются селективной формулой для вида (All Documents selects all documents выбрать все документы из всех документов). Для примера вы можете создать вид, назвав его «All Mail From Julie», он выбирает все документы, которые имеют в поле отправитель (from) имя «Julie». Вы можете определить любое число таких видов, и один документ, который может соответствовать любому числу так, что он может появиться в любом количестве видов. Папки в отличие от видов заполняются явно. По умолчанию роутер доставляет документ в папку Inbox. Агент может решить не делать это, и может так же решить переместить документ в другую папку. Таким образом, когда вы используете pre-delivery агент, документ может появиться в нуле, одной или двух папках, но в любом количестве видов.
· Если pre-delivery почтовый агент удаляет сообщение из папки Inbox через операцию RemoveFromFolder ("($InBox)"), почтовое сообщение доставляется, но появляется лишь в виде All Documents view.
· Если вы хотите, чтобы почтовое сообщение появилось в строго определённой папке и не появлялось в папке Inbox, то вам надо выполнить две операции над папками: PutInFolder("Новая папка") и RemoveFromFolder("($InBox)").
Следующая таблица подытоживает последовательность и результат «фолдерных» операций:
Отладка pre-delivery почтовых агентов
Поскольку pre-delivery агенты выполняют операции над письмом в момент его доставки, то вы не можете тестировать логику агента так же эффективно, как у агента меню (запускается вручную). Если вы всё же захотите это сделать, то получите сообщение: ”Не выбрано никаких документов”, до тех пор, пока не поменяете контекст триггера.
Тем не менее, вы имеете следующие возможности, для отладки pre-delivery агентов:
Вы можете изменить триггер агента на другой тип, такой как «Выбранные документы» и проверить корректность логики работы агента, когда контекст агента есть документ, выбранный в виде. Когда вы будуте довольны работой логикой агента, переключите триггер на «Before new mail arrives».
Вы можете отлаживать логику агента, читая отладочную информацию в Agent Log.
Вы можете использовать MessageBox или Print методы для получения отладочной информации с консоли сервера или лога сервера.
С тех пор как роутер выполняет pre-delivery почтовые агенты, установки Agent Manager в NOTES.INI устанавливаемые для регистрации и отладки не имеют эффекта. Что бы контролировать ошибки, которые выводятся на консоль сервера для pre-delivery почтовых агентов, вы можете определить "Logging level" в настройках роутера на закладке "Router/SMTP" /Advanced/Controls в документа Configuration Settings сервера. Вы можете установить себе "Logging level" на минимальный уровень (Minimal), нормальный (Normal)(по умолчанию), информационный (Informational), или избыточный (Verbose). Если вы установите эту переменную как Verbose, ошибки вышего агента будут протоколироваться на консоли. Имейте ввиду, что вы так же получите очень избыточные операции роутера на выходе. Используя это разделение для контроля выхода pre-delivery почтовых агентов, вы можете настроить выполнение роутера, пока вы всё ещё имеете ваших других агентов, выводящих множество отладочной информации на консоль.
Вы обратите внимание, что выходная информация pre-delivery агента на консоли сервера отображается в виде "Addin:" как показано ниже.
"Addin: Agent message box: Message generated by mail pre-delivery agent."
Это происходит, потому что сообщения генерируются задачей роутера (которая выполняется через программу Agent Manager с помощью вызова API) и задача роутера есть серверное расширение. Этот же префикс появляется в сообщениях об ошибке сгенерированный агентом на консоли сервера. Для получения более детальной информации об отладке агентов смотри "Troubleshooting agents."
Примеры pre-delivery почтовых агентов
Теперь давайте рассмотрим всё, что мы узнали о pre-delivery агентах на примерах. Мы покажем в текущих примерах следующие типичные операции, которые могут выполняться почтовыми pre-delivery агентами:
Занесение почтового сообщения в папку иную, нежели Inbox по теме этого сообщения.
Отделение вложения, если его размер больше определённой границы.
Удаление письма или пересылка копии другой персоне
Разделение задачи на критическую и некритическую часть и использование обоих типов почтовых агентов для выполнения этой задачи.
Пожалуйста учтите, что в примерах агентов включено очень много отладочного кода для наглядной иллюстрации. Чтобы использовать этот код для промышленной системы, вы должны удалить этот отладочный код из (включая запись в NotesLog, выражения Print и MessageBox). После того, как вы закончили тестирование, сделайте код вашего агента как можно меньшим.
Пример первый: перемещение сообщения.
Этот агент, написанный на LotusScript перемещает сообщение в папку иную, нежели Inbox, если тема сообщения «Привет, я Вася»
Код:
Sub Initialize
Dim session As New NotesSession
Dim note As NotesDocument
Dim dbug As NotesLog
Dim db As NotesDatabase
Dim it As NotesItem
Set session = New NotesSession
Set sourcedb = session.CurrentDatabase
REM Log steps in our processing for debug purposes
Set dbug = New NotesLog("Router log")
dbug.LogActions = True
dbug.OpenAgentLog
dbug.LogAction("begin")
Set db = session.CurrentDatabase
REM Make sure we have the note set correctly
If db Is Nothing Then dbug.LogAction("db is not set") Else dbug.LogAction("db is set")
Set note = session.DocumentContext
If note Is Nothing Then dbug.LogAction("note is not set") Else dbug.LogAction("note is set")
REM Note the Subject of all messages
dbug.LogAction("Subject ->" + note.Subject(0))
REM Is this message has the special subject, store it in the special folder
If note.Subject(0) = ”Привет, я Вася” Then
Call note.PutInFolder( "Vacation" )
REM PutInFolder leaves a message in the Inbox view as well.
REM Since we want to have it only the Vacation Folder we need to remove it from Inbox
Call note.RemoveFromFolder("($InBox)")
dbug.LogAction("File into Vacation Folder")
End If
dbug.LogAction("done")
dbug.Close
End Sub
Пример второй: отделение вложения.
Этот агент, написанный на LotusScript, оделяет вложения, которые больше, чем установленный максимальный размер (MaxSize).
Код:
Sub Initialize
Dim session As New NotesSession
Dim db As NotesDatabase
Dim doc As NotesDocument
Dim dbug As NotesLog
Dim rtitem As Variant
Dim fileCount As Integer
Dim it As NotesItem
REM Specify the size limit for attachments
Const MaxSize = 5000
fileCount = 0
Set dbug = New NotesLog("Router log")
dbug.LogActions = True
dbug.OpenAgentLog
dbug.LogAction("begin")
REM get the incoming mail message
Set doc = session.documentcontext
REM Log the subject name of the message for debug purposes
Set it = doc.GetFirstItem("Subject")
dbug.LogAction("doc subject from context" + "-> " + it.Text)
Set rtitem = doc.GetFirstItem( "Body" )
If ( rtitem.Type = RICHTEXT ) Then
Forall o In rtitem.EmbeddedObjects
REM Note how many files we have processed
fileCount = fileCount + 1
dbug.LogAction("file count:"+Cstr(fileCount))
If ( o.Type = EMBED_ATTACHMENT ) And ( o.FileSize > MaxSize ) Then
Call o.ExtractFile( "c:\tmp\newfile" & Cstr( fileCount ) )
Call o.Remove
REM Note that we removed an attachment
dbug.LogAction("attachment removed")
REM Created a field noting that we removed an attachment
doc.stripped = "yes"
Call doc.Save( True, True )
End If
End Forall
End If
REM Finish up agent log processing
dbug.LogAction("Mail preprocessing agent is done")
dbug.Close
End Sub
Пример третий: удаление сообщений
Этот агент, написанный на LotusScript удаляет сообщения, который приходят от «Joe Spam», после пересылки их postmaster (администратору почтовой системы)
Код:
Sub Initialize
Dim session As New NotesSession
Dim note As NotesDocument
Dim dbug As NotesLog
Dim db As NotesDatabase
Dim it As NotesItem
Set session = New NotesSession
Set sourcedb = session.CurrentDatabase
Set dbug = New NotesLog("Router log")
dbug.LogActions = True
dbug.OpenAgentLog
dbug.LogAction("begin")
Set db = session.CurrentDatabase
Set note = session.DocumentContext
dbug.LogAction("Subject ->" + note.From(0))
If note.From(0) = "CN=Joe Spam/O=SpamFactory" Then
Call note.Send(False, "Administrator/Lily")
dbug.LogAction("Send memo")
Call note.Remove(True)
End If
dbug.Close
End Sub
Пример четвёртый: Совместное использование pre-delivery и post-delivery агентов.
Этот пример показывает, как выполняется критическая часть обработки почты pre-delivery агентами, а остальная часть выполняется post-delivery агентами. Наша цель удалить вложения больших размеров и уведомить отправителя, что его письмо не было доставлено из-за больших размеров. Pre-delivery агенты удаляют большие вложения, так как это уменьшает потери дискового пространства. Рost-delivery агенты уведомляют отправителя, поскольку эта часть задания по времени не критическая.
Для первой части задания мы используем pre-delivery агент, созданный во втором примере. Помните, что в том примере, когда мы удаляем вложение, мы устанавливаем флаг в поле «stripped» как «yes». В post-delivery агенте мы проверяем это поле и если оно установлено, мы генерируем ответ отправителю.
Код:
Sub Initialize
Dim session As New NotesSession
Dim db As NotesDatabase
Set session = New NotesSession
Set db = session.CurrentDatabase
Set docs = db.UnprocessedDocuments
Count = docs.Count
REM if we have new mail start processing
If docs.Count > 0 Then
For n = 1 To docs.Count
Set memo = docs.GetNthDocument(n)
If Not( memo.SentByAgent ) Then
REM if attachemetns were stripped, send a reply
If (memo.stripped(0) = "yes") Then
Set reply = memo.CreateReplyMessage( False )
reply.Subject = "Re: " & memo.Subject( 0 )
reply.Body = "The message you mailed contained attachments that were too large. They were removed before mail delivery."
Call reply.Send( False )
End If
End If
Call session.UpdateProcessedDoc(memo)
Next
End If
End Sub
Заключение
Эта статья вводит вас в новые pre-delivery агенты, и как вы можете использовать этот тип агента, чтобы обрабатывать почту прежде чем она достигла почтового ящика пользователя. Мы рассмотрели некоторые типичные проблемы, для которых вы начинали разрабатывать pre-delivery агенты, а так же рассмотрели некоторые типичные примеры. Я надеюсь, эта статья даст вам достаточно знаний, для использования этого типа агентов с доверием и сделает его простым и лёгким для вас, в вашей работе.
