Provider Configuration
The list of all available providers in Bulksign is available here
Parts of the Bulksign functionality is exposed ( and can be extended / changed) using a generic provider model. The configuration for each provider is done in 2 parts :
- the provider type and assembly is done in the provider type key :
SMSProviderType: "Bulksign.Integrations.TwilioProvider,Bulksign.Integrations.dll"
- the parameters specific to each provider are configured under the generic "ProviderConfiguration" node :
"SMSProviderType.Twilio.Token": "", "SMSProviderType.Twilio.SenderPhoneNumber": "",
Here is the list providers that are required to be configured :
MailSenderType
Description : The provider is used to send emails. The default configured provider is the SMTP one. "MailSenderType" : "Bulksign.Integrations.SmtpEmailSender,Bulksign.Integrations.dll" "ProviderConfiguration": { "MailSenderType.SmtpProvider.Host" : "", "MailSenderType.SmtpProvider.Password": "", "MailSenderType.SmtpProvider.UserName": "", "MailSenderType.SmtpProvider.Port": 465, "MailSenderType.SmtpProvider.UseSSL": true, "MailSenderType.SmtpProvider.DeliveryMethod": 1, "MailSenderType.SmtpProvider.UseDefaultCredentials": false, "MailSenderType.SmtpProvider.TimeoutSeconds" : 60, }
Here are the details for each value :
SmtpProvider.Host
Description : The name of the email server host Type : string Example : smtp.gmail.com
SmtpProvider.UserName
Description : User name used to connect to SMTP server type : string
SmtpProvider.Password
Description: Password used to connect to SMTP server Type : string
SmtpProvider.Port
Description : The SMTP server port Type : integer
SmtpProvider.UseSSL
Description : Flag used to determine if the server connection is using SSL/TSL Type : boolean
SmtpProvider.DeliveryMethod
Description : Set the SMTP server delivery method Type : integer Allowed Values : 1 - Network 2 - SpecifiedPickupDirectory 3 - PickupDirectoryFromIis
SmtpProvider.UseDefaultCredentials
Description : Flag to determine if default credentials are used when connecting to SMTP server Type : boolean
SmtpProvider.TimeoutSeconds
Description : The connection timeout value in seconds Type : integer
Bulksign also ships providers for Sendgrid and Sparkpost
To use the Sendgrid provider, just configure it like this :
"MailSenderType" : "Bulksign.Providers.SendGridProvider,Bulksign.Providers.SendGrid.dll" "ProviderConfiguration": { "MailSenderType.SendGrid.ApiKey" : "YourSendGridAPIKey", "MailSenderType.SendGrid.TimeoutSeconds" : "60", }
To use the Sparkpost provider, just configure it like this :
"MailSenderType" : "Bulksign.Providers.SparkPostProvider,Bulksign.Providers.Sparkpost.dll" "ProviderConfiguration": { "MailSenderType.SparkPost.ApiKey" : "YourSparkpostAPIKey" }
SMSProviderType
Bulksign ships out of the box with Twilio provider.
Description : The provider used to send SMSes, is required for the SMS OTP authentication and SM-OTP signature feature. If the feature is not used, value can be empty array. Multiple providers can be configured and each provider can handle one or multiple phone number prefixes (so, for example, a provider can be used to send OTPs for Swedish and Denmark phone numbers, another one for sending OTPs to Germany and Switzerland and another one to handling the rest). "SMSProviderType" : ["Bulksign.Integrations.TwilioProvider, Bulksign.Integrations.dll", "CustomSecondSmsProvider, second.dll "] "ProviderConfiguration": { "SMSProviderType.Twilio.AccountSid": "", "SMSProviderType.Twilio.Token": "", "SMSProviderType.Twilio.SenderPhoneNumber" : "", "SMSProviderType.Twilio.NumberFilter" : "*" }
Here are the configuration details for Twilio :
Twilio.AccountSid
Description : The Twilio account identifier Type : string
Twilio.Token
Description : The Twilio token Type : string
Twilio.SenderPhoneNumber
Description : The Twilio sender phone number Type : string
Here is a sample configuration which illustrates number filtering. Assuming we have 3 providers (P1, P2 and P3) configured like this :
"ProviderConfiguration": { "SMSProviderType.P1.NumberFilter": "+34;+44;+456", "SMSProviderType.P2.NumberFilter": "+80", "SMSProviderType.P3.NumberFilter": "*", }
provider P3 will handle all phone numbers not handled by the other 2.
For development purposes we also ship a SMS log provider (which simply logs the SMS text), you can use the following value for the provider :
"Bulksign.Integrations.SmsLogProvider,Bulksign.Integrations.dll"
EnvelopeStatusChangedNotificationType
Description : The provider used to send callbacks/webhooks for envelope status events. We ship 3 providers for sending callbacks : HTTP, MSMQ and named pipes.
The default configured provider is the HTTP one.
Configuration:
"EnvelopeStatusChangedNotificationType": "Bulksign.Integrations.HttpEnvelopeStatusNotification, Bulksign.Integrations.dll" "ProviderConfiguration": { "EnvelopeStatusChangedNotificationType.HttpEnvelopeStatusNotification.RequestType" : 1, "EnvelopeStatusChangedNotificationType.HttpEnvelopeStatusNotification.IgnoreHttpsCertificateError" : false }
HttpEnvelopeStatusNotification.RequestType
RequestType allows you to configure which HTTP verb will be used to trigger the callback/webhook. The following values are allowed : "1" - use HTTP GET request to send the callback "3" - use HTTP POST request to send the callback
HttpEnvelopeStatusNotification.IgnoreHttpsCertificateError
If set to true, this boolean flag allows you to ignore invalid HTTPS certificates when the callback is triggered. Useful for testing scenarios when receiving the callback to website with self signed certificate.
The second supported provider allows to trigger the callback over MSMQ
Configuration:
"EnvelopeStatusChangedNotificationType": "Bulksign.Integrations.MsmqEnvelopeStatusNotification, Bulksign.Integrations.dll" "ProviderConfiguration": { EnvelopeStatusChangedNotificationType.MsmqEnvelopeStatusNotification.QueueName : "" }
MsmqEnvelopeStatusNotification.QueueName
This allows you to configure the name of the queue to which the callback/webhook info will be written
The data written to the queue is a JSON formatted string with the following structure
<?xml version="1.0"?> <string> { "Url":"", "Email":"", "Status": "", "EnvelopeId":"" } </string>
The third supported provider allows to trigger the callback using named pipes (if you have a integration which is running on the same server as Bulksign).
Configuration:
"EnvelopeStatusChangedNotificationType": "Bulksign.Integrations.NamedPipeEnvelopeStatusNotification, Bulksign.Integrations.dll" "ProviderConfiguration": { EnvelopeStatusChangedNotificationType.NamedPipeEnvelopeStatusNotification.PipeName : "", EnvelopeStatusChangedNotificationType.NamedPipeEnvelopeStatusNotification.MachineName : "", EnvelopeStatusChangedNotificationType.NamedPipeEnvelopeStatusNotification.TimeoutInSeconds : "", }
NamedPipeEnvelopeStatusNotification.PipeName
The name of the pipe over which the data is exchanged
NamedPipeEnvelopeStatusNotification.MachineName
The name of the machine , use "." for local machine
NamedPipeEnvelopeStatusNotification.TimeoutInSeconds
Timeout value
Just like the MSMQ provider, the data is sent as a JSON string with this schema
{ Url :"" Status : "" EnvelopeId : "" SenderEmail : "" }
RecipientActionNotificationType
Description : The provider used to send callbacks/webhooks for recipient action events. We ship 3 providers for sending callbacks : HTTP, MSMQ and named pipes.
The default configured provider is the HTTP one.
Configuration:
"RecipientActionNotificationType": "Bulksign.Integrations.HttpRecipientActionNotification, Bulksign.Integrations.dll" "ProviderConfiguration": { "RecipientActionNotificationType.HttpRecipientActionNotification.RequestType" : 1, "RecipientActionNotificationType.HttpRecipientActionNotification.IgnoreHttpsCertificateError" : false }
HttpRecipientActionNotification.RequestType
RequestType allows you to configure which HTTP verb will be used to trigger the callback/webhook. The following values are allowed : "1" - use HTTP GET request to send the callback "3" - use HTTP POST request to send the callback
HttpRecipientActionNotification.IgnoreHttpsCertificateError
If set to true, this boolean flag allows you to ignore invalid HTTPS certificates when the callback is triggered. Useful for testing scenarios when receiving the callback to website with self signed certificate.
The second supported provider allows to trigger the callback over MSMQ
Configuration:
"RecipientActionNotificationType": "Bulksign.Integrations.MsmqRecipientActionNotification, Bulksign.Integrations.dll" "ProviderConfiguration": { RecipientActionNotificationType.MsmqRecipientActionNotification.QueueName : "" }
MsmqRecipientActionNotification.QueueName
This allows you to configure the name of the queue to which the callback/webhook info will be written
The data written to the queue is a JSON formatted string with the following structure
<?xml version="1.0"?> <string> { "Url":"", "Action":"", "RecipientEmailAddress":"", "SenderEmailAddress":"", "EnvelopeId":"" } </string>
The third supported provider allows to trigger the callback using named pipes (if you have a integration which is running on the same server as Bulksign).
Configuration:
"RecipientActionNotificationType": "Bulksign.Integrations.NamedPipeRecipientActionNotification, Bulksign.Integrations.dll" "ProviderConfiguration": { RecipientActionNotificationType.NamedPipeRecipientActionNotification.PipeName : "", RecipientActionNotificationType.NamedPipeRecipientActionNotification.MachineName : "", RecipientActionNotificationType.NamedPipeRecipientActionNotification.TimeoutInSeconds : "", }
NamedPipeRecipientActionNotification.PipeName
The name of the pipe over which the data is exchanged
NamedPipeRecipientActionNotification.MachineName
The name of the machine , use "." for local machine
NamedPipeRecipientActionNotification.TimeoutInSeconds
Timeout value
Just like the MSMQ provider, the data is sent as a JSON string with this schema
{ "Url":"", "Action":"", "RecipientEmailAddress":"", "SenderEmailAddress":"", "EnvelopeId":"" }
CertificateProviderType
Description : The provider used to load the signing certificate
Default Value : empty which means the built-in signing certificate will be used
Bulksign ships with 2 providers for this purpose :
-
provider which loads a certificate file (pfx, p12) from the filesystem
-
provider which loads a certificate from Windows Certificate Store
Filesystem provider
"CertificateProviderType" : "Bulksign.Integrations.CertificatePathProvider, Bulksign.Integrations.dll" "ProviderConfiguration": { "Certificate.CertificatePathProvider.Path": "", "Certificate.CertificatePathProvider.Password": "" }
CertificatePathProvider.Path
The path to the certificate pfx/p12 file.
CertificatePathProvider.Password
The certificate password
Windows Certificate Store provider
This provider will load the certificate directly from the Windows Certificate Store.
The requirements for this provider are :
-
the certificate must have a private key
-
the private key of the certificate must be marked as exportable.
-
the user under which Bulksign is configured to run must have access to that certificate.
If these requirements are met, the following data needs to be configured :
"CertificateProviderType" : "Bulksign.Integrations.CertificateStoreProvider, Bulksign.Integrations.dll" "ProviderConfiguration": { "Certificate.CertificateStoreProvider.StoreName": "", "Certificate.CertificateStoreProvider.Thumbprint": "", "Certificate.CertificateStoreProvider.Password": "" }
Certificate.CertificateStoreProvider.StoreName
This is the name of the certificate store category, the following values can be used : "My" -> The X.509 certificate store for personal certificates "AddressBook" -> The X.509 certificate store for other users. "AuthRoot" -> The X.509 certificate store for third-party certificate authorities (CAs). "CertificateAuthority" -> The X.509 certificate store for intermediate certificate authorities (CAs). "Root" -> The X.509 certificate store for trusted root certificate authorities (CAs). "TrustedPeople" -> The X.509 certificate store for directly trusted people and resources. "TrustedPublisher" -> The X.509 certificate store for directly trusted publishers.
Certificate.CertificateStoreProvider.Thumbprint
This is the thumbprint that identifies the certificate
Certificate.CertificateStoreProvider.Password
The password of the certificate, leave empty if it doesn't have one.
GeolocationProviderType
Description : Provider which retrieves geo-location data using the signer IP address. By default this provider is NOT activated. If this is left disabled, the signers geolocation data will not be added to the envelope audit trail.
By default, we are shipping a provider which is using the FREE ip-api service to retrieve the geo-location information. To use this provider please configure it like this :
"GeolocationProviderType": "Bulksign.Integrations.IPGeolocation,Bulksign.Integrations.dll"
If you want to use the commercial ip-api service , please configure your key in :
"GeolocationProviderType.IpApi.ApiKey": ""
ReverseGeolocationProviderType
Description : Provider which retrieves location data based on signer latitude/longitude data read from browser.
By default this provider is NOT activated. If this is left disabled, the signers location data will not be added to the envelope audit trail.
By default, we are shipping a provider which is using Google Maps API to retrieve this data. This requires a valid Google Maps API key to be used. To use this provider please configure it like this :
"ReverseGeolocationProviderType": "Bulksign.Integrations.ReverseGeolocation,Bulksign.Integrations.dll", "ReverseGeolocationProviderType.GoogleMaps.Key": "GoogleMapsKey"
and replace "GoogleMapsKey" with your own key.
PdfConversionProviderType
Description : provider used to convert files to PDF. The default provider is enabled and requires LibreOffice version 4.2.4.2 to be installed on the server.
"PdfConversionProviderType" :"Bulksign.Integrations.LibreOfficePdfConverter, Bulksign.Integrations.dll", "ProviderConfiguration": { "PdfConversionProviderType.LibreOfficePdfConverter.ConverterPath" : "C:\\Program Files (x86)\\LibreOffice 4\\program\\soffice.exe", "PdfConversionProviderType.LibreOfficePdfConverter.ConverterRetries" : "95000",
LibreOfficePdfConverter.ConverterPath
The path to the LibreOffice's "soffice.exe" executable
LibreOfficePdfConverter.ConverterRetries
The max number of conversion checks to do before timing out.
Please note that this requires to update the app pool setting to load the user's profile. Without this change the LibreOffice conversion will fail
CompletedEnvelopeBackupProviderType
Description : provider used to back up envelope files immediately after they are completed. By default, this provider is not enabled. To enable it, please configure Bulksign like this :
"CertificateProviderType" : "Bulksign.Integrations.CompletedEnvelopeBackupToFileSystem, Bulksign.Integrations.dll" "ProviderConfiguration": { "CompletedEnvelopeBackupProviderType.CompletedEnvelopeBackupToFileSystem.OutputPath": "", "CompletedEnvelopeBackupProviderType.CompletedEnvelopeBackupToFileSystem.CreateSubFolder": ""
CompletedEnvelopeBackupToFileSystem.OutputPath
The root path where to copy the completed envelope files
CompletedEnvelopeBackupToFileSystem.CreateSubFolder
Boolean flag to determine if a sub-folder is created before the file is copied. If enabled a sub-folder with the envelope id is created and the envelope file placed in it. If this is disabled ALL envelope files will be copied in the root of the folder.