Provider Configuration
Tip

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": "",
Important!

Leaving the ProviderType value empty will disable that specific provider


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.

Tip

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.
Tip

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.