since v10.0.46The extension point allows you to implement message retrieval from different external sources as well as the delivery of answers back to the original source.
The interface MessageConnector cannot be implemented directly.
You can choose between the two sub interfaces of MessageConnector:
deprecated MailMessageConnector - extended variant - useful to process RFC-822 messages since v11.32 ExtendedMessageConnector - extended variant - useful to process RFC-822 messagesThe SimpleMessageConnector can be used if the underlying message source provides messages as structured objects or simple text messages e.g. social media messages.
The MailMessageConnector (deprecated) can be used if the underlying message source provides RFC-822 conform messages of the type javax.mail.Message, e.g. POP3 or IMAP mail servers. It was deprecated in v.11.32 and replaced with the ExtendedMessageConnector
The ExtendedMessageConnector (since v11.32) can be used if the underlying message source provides RFC-822 conform messages of the type javax.mail.Message, e.g. POP3 or IMAP mail servers. The ExtendedMessageConnector also allows to apply additional information like a ContactIdentifier.
Please annotate your implementation of either SimpleMessageConnector or ExtendedMessageConnector with the runtime annotation MessageConnectorPlugin to ensure, that your plugin will be loaded during runtime within the novomind iAGENT core process and be assigned to any Account configured with the protocol specified by the 'protocol' parameter of the annotation @MessageConnectorPlugin.
Plugin classes annotated with the MessageConnectorPlugin annotation need to define the required annotation parameters.
protocol: The unique name of the protocol to be implemented by your plugin. It is strongly recommended to use a specific application or vendor id as prefix to avoid conflicts with other app's containing an @MessageConnectorPlugin with the same protocol. Please note that you can only install either a SimpleMessageConnector or a MailMessageConnector or an ExtendedMessageConnector defining the same protocol at runtime. Installing more than one MessageConnector with the same protocol will not work, even if they are provided by different app's.
channelNames: The list of channel names that are supported by this plugin. For a complete list of valid channel names, please refer to the constants defined in Channel.
canSend: If true your plugin needs to implement the functionality to send messages back to the external source as well.
customChannels: (Since v10.0.102) The optional list of custom channel definitions supported by this plugin. The plugin may define one or more custom channels that can be set as the channel of the account running the protocol of your plugin. The custom channels defined by the plugin will be created as soon as the plugin is installed and the iAGENT core process has been started. If the custom channel definition is changed e.g. by an app update, it will be updated automatically. Please note that the name of a custom channel must be a unique identifier that should not be changed. A change of the custom channel's name will result in the creation of a new custom channel. For further information about the definition of custom channels please refer to the definition of the annotation CustomChannel.
Example 1:
@MessageConnectorPlugin(protocol = "myvendor.file",
channelNames = { "EMAIL","LETTER","FAX","SMS","SOCIAL_MEDIA" },
canSend = false
)
public class MyFileConnector implements ExtendedMessageConnector {
@Override
public MessageIterator<ExtendedMessage> iterator() {
// to be implemented
}
@Override
public Message sendMessage(Message message, PreSendMessageInfo preSendMessageInfo,
OutgoingMessageInfo outgoingMessageInfo,
AnswerType answerType, Optional<Ticket> ticket)
throws PermanentMessagingException,
TemporaryMessagingException {
throw new PermanentMessagingException("Send messages not support by FileConnector");
}
}
Example 2:
@MessageConnectorPlugin(
protocol = "myvendor.mySocialMediaProtocol",
channelNames = {},
canSend = true,
customChannels = {
@CustomChannel(name = "MY_SOCIAL_MEDIA_CHANNEL",
displayName = "MySocialMediaChannel",
messageFormatNames = { MessageFormat.NAME_TEXT },
pngIconResourcePath = "/META-INF/resources/images/myLogo.png"
)
}
)
public class MySocialMediaConnector implements SimpleMessageConnector {
@Override
public MessageIterator<SimpleMessage> iterator() {
// to be implemented
}
@Override
public Message sendMessage(Message message, PreSendMessageInfo preSendMessageInfo,
OutgoingMessageInfo outgoingMessageInfo,
AnswerType answerType, Optional<Ticket> ticket)
throws PermanentMessagingException,
TemporaryMessagingException {
// to be implemented
}
}
Your plugin has to provide a MessageIterator as return value of the method iterator() that allows to iterate through recent messages available on an external source.
As long as the MessageConnector is running, this method will be called periodically to fetch and retrieve messages from the external source.
The next() method of the iterator implementation may also be overloaded with a parameter next(NextMessageInfo).
The NextMessageInfo object provides access to the ticket storage if a ticket is created for the current message and also provides the IncomingBindings object which is used to pass any transient data to other Apps or to the knowledge base.
The SimpleMessage and the ExtendedMessage can optionally return a ContactIdentifier by the getContactIdentifier() method that can be used to provide additional information about the sender of the current message. This information will be used as secondary search criterion for searching existing contacts.
The MessageIterator may not be iterated completely during the fetch period. It has to implement the MessageIterator.remove() method, that will usually be called during iteration to permanently remove a message from the source after it has been processed successfully. Finally, the MessageIterator.close() method will be called to indicate the end of the fetch period and therefore also the end of the iterator's life cycle. Messages, that haven't been processed up to this point, will be processed during the next fetch period.
The extension point SimpleMessageConnector extends the base interface MessageConnector.
This variant should be preferred, if the underlying mail source does not provide RFC-822 messages.
Implementations of this interface need to provide the externally retrieved mails as objects of the type SimpleMessage.
Implementations of the interface SimpleMessageConnector need to provide an iterator that returns mails as objects of type SimpleMessage during each iteration. The interface SimpleMessage contains some methods, which have to be implemented by your plugin.
Deprecated The extension point MailMessageConnector extends the base interface MessageConnector.
This variant is useful, if the underlying mail source delivers RFC-822 messages like POP3 or IMAP mail servers.
Implementations of this interface have to provide the externally retrieved messages as objects of the type javax.mail.Message
since v11.32 The extension point ExtendedMessageConnector extends the base interface MessageConnector.
This variant is useful, if the underlying mail source delivers RFC-822 messages like POP3 or IMAP mail servers and there is also additional information to be applied to the message.
Implementations of this interface have to provide the externally retrieved messages as objects of the type javax.mail.Message and wrap them into an ExtendedMessage object that also allows to apply a ContactIdentifier.
To provide configuration options for your custom MessageConnector you can use the extension point AccountConnectorTabProvider.