Table of Contents

Class MessagingServiceProvider

Namespace
ArcanaDevelopment.adTempus.Client
Assembly
ArcanaDevelopment.adTempus.Client.dll

Contains settings for a Messaging Service Provider (e.g., email server).

public sealed class MessagingServiceProvider : ADTIndependentObject
Inheritance
object
MessagingServiceProvider

Properties

ApiKey

The OAuth2 API key for the provider.

public string ApiKey { get; set; }

Property Value

string

Remarks

This is needed only when using a custom app registration for OAuth2 authentication.

ApiSecretSet

Indicates whether an API secret has been set for the provider

public bool ApiSecretSet { get; }

Property Value

bool
See Also

AuthenticationType

Specifies the type of authentication to use for this provider.

public int AuthenticationType { get; set; }

Property Value

int

Remarks

The range of valid values depend on the type of provider.

<ul><li>For SMTP notification, use the values from <xref href="ArcanaDevelopment.adTempus.Shared.SMTPAuthenticationType" data-throw-if-not-resolved="false"></xref></li></ul>
See Also

ClassID

The Class ID for the object

[IgnoreDataMember]
public override ClassID ClassID { get; }

Property Value

ClassID

ClassKeyName

The key name for the class.

public override string ClassKeyName { get; }

Property Value

string

Remarks

This name the name used by adTempus to identify the class and is intended for programmatic use only. Use the ClassName for a user-friendly name.

Enabled

Determines whether this provider is enabled

public bool Enabled { get; set; }

Property Value

bool

Remarks

When a provider is disabled any operations that target it will be failed

IsDependent

Indicates whether the object is a dependent of (owned by) another object

[IgnoreDataMember]
public override bool IsDependent { get; }

Property Value

bool

Remarks

An independent object (IsDependent is false) is an object that can exist on its own without being part of another object. For example, Jobs, Job Groups, etc.

A dependent object (IsDependent is true) is a part of another object. For example, a JobStep cannot exist independently of a Job, so the JobStep is dependent.

Dependent objects cannot be directly fetched from the server: they are only fetched as part of the object they belong to. They also cannot be saved or deleted independently: they are automatically saved or deleted when the owning object is saved or deleted.

MailFetchProtocol

The protocol used when MessagingServiceType is IncomingEmail

public MailFetchProtocol? MailFetchProtocol { get; set; }

Property Value

MailFetchProtocol?

MaxMessageLength

The maximum length for a message

public int MaxMessageLength { get; set; }

Property Value

int

Remarks

The behavior depends on the MessagingServiceType:

Messages longer than MaxMessageLength are truncated
Messages longer than MaxMessageLength are truncated if SplitLongMessages is false, or split into up to MaxMessages if SplitLongMessages is true.

MaxMessages

The maximum number of message parts to send when an SMPP message is broken into parts based on MaxMessageLength

public int MaxMessages { get; set; }

Property Value

int

MessageValidityStamp

Message tracking validity stamp for IMAP message filtering

[RequiredVersion(6, 0, 0, 0)]
public int MessageValidityStamp { get; set; }

Property Value

int

Remarks

If this provider represents an IMAP mail server connection, each trigger or task that uses the provider keeps track of which messages on the server it has already seen. This information used to track this is server-specific, so if the provider is changed to point to a different server, the tracking information will be incorrect, which could cause messages to be missed or incorrectly reprocessed. To avoid this, increment the MessageValidityStamp. This signals the triggers and tasks to discard their message tracking information and read state information from the new server.

This value is only supported for server version 6 and later; setting it for an older server has no effect.

MessagingServiceType

The type of messaging service this service provides

public MessagingServiceType MessagingServiceType { get; set; }

Property Value

MessagingServiceType

Name

The display name for the provider

public string Name { get; set; }

Property Value

string

OAuth2Provider

The service that OAuth2 authentication is being performed against. Must be set to one of the ArcanaDevelopment.OAuthConnector.OAuth2ProviderNames values.

public string OAuth2Provider { get; set; }

Property Value

string

Remarks

Requires ServerVersion 5 or higher.

OAuth2TokenSet 

public bool OAuth2TokenSet { get; }

Property Value

bool

OAuthAuthorizationParameters

Additional parameters to include in the authorization request to a custom OAuth2 provider, in query string form (for example "access_type=offline&prompt=consent").

public string OAuthAuthorizationParameters { get; set; }

Property Value

string

Remarks

Used only when OAuth2Provider is "custom".

OAuthAuthorizationUrl

The authorization endpoint URL for a custom OAuth2 provider.

public string OAuthAuthorizationUrl { get; set; }

Property Value

string

Remarks

Used only when OAuth2Provider is "custom".

OAuthScopes

The scopes to request from a custom OAuth2 provider, separated by spaces or line breaks.

public string OAuthScopes { get; set; }

Property Value

string

Remarks

Used only when OAuth2Provider is "custom".

OAuthTokenUrl

The token endpoint URL for a custom OAuth2 provider.

public string OAuthTokenUrl { get; set; }

Property Value

string

Remarks

Used only when OAuth2Provider is "custom".

PasswordSet

Indicates whether a password has been set for the provider

public bool PasswordSet { get; }

Property Value

bool
See Also

Priority

The priority for this provider

public int Priority { get; set; }

Property Value

int

Remarks

Use the Priority to set the order in which providers are tried when multiple providers can be used for an operation. For example, if there are several SMTP servers defined, adTempus will try them in order of Priority until the message can be sent successfully.

Protocol

The protocol to use

public string Protocol { get; set; }

Property Value

string

Remarks

Values provider-type dependent.

No Protocol values are currently defined.

ReturnAddress

The return address to use when sending SMTP messages

[CanBeNull]
public string ReturnAddress { get; set; }

Property Value

string

Remarks

This must be a valid email address and most mail servers will validate it to ensure it is a valid email address for the account you are attempting to send mail from.

SenderName

The display name to use for the message sender

[CanBeNull]
public string SenderName { get; set; }

Property Value

string

Remarks

If this is not specified a default value of "adTempus on computername" is used.

ServerAddress

The name or IP address of the server

public string ServerAddress { get; set; }

Property Value

string

Remarks

<p>If this server is an IMAP mail server and you are changing it to point to a different mail server, you must also update the <xref href="ArcanaDevelopment.adTempus.Client.MessagingServiceProvider.MessageValidityStamp" data-throw-if-not-resolved="false"></xref> so that
message tracking data for the server is reset. See the discussion under <xref href="ArcanaDevelopment.adTempus.Client.MessagingServiceProvider.MessageValidityStamp" data-throw-if-not-resolved="false"></xref>. If you are changing the name or address but it is still the
same mail server, the MessageValidityStamp should not be changed.</p>

ServerPort

The port number to connect to

public int ServerPort { get; set; }

Property Value

int

Remarks

Set to 0 to use the default for the service type

SplitLongMessages

Determines whether messages that exceed MaxMessageLength are split into shorter messages

public bool SplitLongMessages { get; set; }

Property Value

bool

Remarks

See Remarks under MaxMessageLength

Tenant

The tenant to use for OAuth2 authorization.

public string Tenant { get; set; }

Property Value

string

Remarks

This is used only for Microsoft, when using a custom app registration that is limited to a single tenant.

UserID

The user ID for connecting to this service

[CanBeNull]
public string UserID { get; set; }

Property Value

string

Methods

BeginOAuth2Authorization(string)

Begins OAuth2 authorization using the provider's current settings.

public OAuth2AuthorizationRequest BeginOAuth2Authorization(string redirectUri)

Parameters

NameTypeDescription
redirectUri string

The loopback redirect URI the client is listening on for the authorization code.

Returns

OAuth2AuthorizationRequest

The authorization URL to open in the browser, and the values needed to complete the authorization.

Remarks

Requires server version 6 or later. After the user authorizes access, call CompleteOAuth2Authorization(OAuth2AuthorizationRequest, string).

CompleteOAuth2Authorization(OAuth2AuthorizationRequest, string)

Completes OAuth2 authorization and stores the resulting token in the provider.

public void CompleteOAuth2Authorization(OAuth2AuthorizationRequest request, string authorizationCode)

Parameters

NameTypeDescription
request OAuth2AuthorizationRequest

The request returned by BeginOAuth2Authorization(string).
authorizationCode string

The authorization code returned to the redirect URI.

Remarks

The server exchanges the code for a token, so the app registration's client secret is never sent to the client. The token is saved when the provider is saved.

GetObjectDescription()

Gets a description of the object's key settings.

protected override string GetObjectDescription()

Returns

string

Remarks

This method is called by GetDescription to get a user-friendly description of the object (such as its key settings) for display to the user. The description should contain enough information to distinguish this object from others of the same class.

SetApiSecret(string)

Sets the OAuth2 API secret for the provider

public void SetApiSecret(string value)

Parameters

NameTypeDescription
value string

The new secret

Remarks

The secret can only be set; it cannot be retrieved. Use ApiSecretSet to determine whether a secret has been set.

SetOAuth2Token(string) 

public void SetOAuth2Token(string value)

Parameters

NameTypeDescription
value string

SetPassword(string)

Sets the password for the provider

public void SetPassword(string value)

Parameters

NameTypeDescription
value string

The new password

Remarks

The password can only be set; it cannot be retrieved. Use PasswordSet to determine whether a password has been set.

Test(string)

Tests the settings to determine whether a connection can be made

public MessageCollection Test(string testData)

Parameters

NameTypeDescription
testData string

The test data to use. See Remarks

Returns

MessageCollection

A collection of Messages indicating the results of the test. If the test succeeds, the collection will contain a single message with severity Informational and HighestSeverity will return MessageType.Informational. If the test fails the collection will contain one or more messages with MessageType.Error describing the error(s).

Remarks

For outgoing providers (providers that send messages) Test will attempt to connect to the server and send a test message using the testData as the message body.

For inbound providers (providers that fetch email) Test attempts to connect to the server and list the messages.

WriteToConfigurationReport(IADTObjectConfigurationReportWriter)

Writes the object and any contained objects to a configuration report

public override void WriteToConfigurationReport(IADTObjectConfigurationReportWriter reportBuilder)

Parameters

NameTypeDescription
reportBuilder IADTObjectConfigurationReportWriter

The report builder to write the object to.

Inherited Members