For the best experience turn off the battery saving mode.

Back

BSG connector for Creatio (formerly BPM.Online)

Installation

Installation could be done either from Creatio (BPM) Marketplace or from archive file, since installation from marketplace could be completed in single click – it’s not covered in this manual.

Manual install

The archive with BSG connector can be downloaded from Creatio (BPM) Online install

To install BSG Connector from archive, go to “Installed application” section in “System designer” and choose “Install from file” from a dropdown:

On next screen, select the archive file and upload it:

Installation process will start automatically, if there will be errors – please keep installation log and forward to our support: support@bsg.world

Configuration

You need to configure BSG Connector before usage: specify API key and default sender name.

To reach configuration page for BSG Connector please go to “System Designer”:

Then in ‘Import and integration’ section click on ‘BSG Connector Settings’ link:

The modal dialog with BSG Connector settings:

If you don’t have API key for BSG service – please click on link ‘Get BSG Key’ and authenticate in BSG panel:

Press ‘Generate’ button and copy received API key:

live_1omLRXzXXXXXXXXXX – for production

or

test_1omLRXzXXXXXXXXXX – for testing

Put received key into ‘API Key’ input field:

and press ‘Save’ button.

On success you’ll see the confirmation window:

There is also the direct link to connector’s configuration page right from main form, but only if current user is administrator:

If connector was configured before – there will be a link to disconnect it from BSG Service instead:

Usage

Our BSG Connector is designed for commons use cases and has key features:

  • single SMS delivery,
  • mass delivery,
  • message templates,
  • template tags
  • balance check
  • count SMS messages

If your business require more specific features or you need advanced customization – feel fee to contact our support team support@bsg.world

Single SMS Delivery

Main form for SMS sending is on ‘BSG’ tab, top section of selected contact page:

Main form in details:

Control elements:

  • Selected contact and the phone that SMS message will be send to
  • Dropdown with allowed tags
  • Message text
  • Validation messages
  • Symbol counter with split for actual SMS messages
  • Select pre-defined message template
  • Check balance in BSG Service (if connected)
  • Link/Unlink BSG Account from connector
  • Send SMS action button
  • Encode message into translit

On successful delivery you will see notification window:

Mass SMS Delivery

Our BSG connector allows mass delivery of SMS messages to multiple selected contacts (or to all). To do that, you need to go to ‘Contacts’ section and in ‘Actions’ menu selects ‘Select multiple records’ or ‘Select all’:

Next, after finish selecting of required contacts, you’ll need to select ‘Send SMS (BSG) ’ option:

There will be a modal dialog with details for mass SMS delivery:

Control elements:

  • Number of selected contacts
  • SMS message text, supports tags input
  • Selection of pre-defined message template
  • Symbol counter with split for actual SMS messages
  • Action button to start mass delivery
  • Encode message to latin
  • Select tags for SMS message substitutions (see below)

Check balance

This option will be available only after successful linking with BSG Account. To see your balance in BSG, click on ‘Balance’ link in main connector form:

There will be modal window with balance details:

SMS Message Templates

Our connector allows to create, use and manage SMS message templates. To use this feature please click on ‘Template’ link from main connector form (or from mass delivery form):

Main screen for SMS message templates:

Control elements:

  • Select current template from list and back to delivery form
  • Add new template
  • Template search

On template select, there are common dictionary actions allowed:

And default control of current view:

Filter options for template search:

To create the new template, press ‘New’ button, there will be modal window:

Control elements:

  • Action button to Save template
  • Template name
  • SMS message text

SMS message also allows tags input.

Template tags

Our connector supports tags in SMS messages. To use them you need to put special keyword into message text and it will be automatically replaced to actual contact details.

Below is the list of supported tags:

Tag Description
#name# Full name of a contact
#GivenName# First name
#MiddleName# Middle name
#Surname# Surname
#JobTitle# Job Title
#BirthDate# Date of birth
#MobilePhone# Mobile phone
#Phone# Work phone
#HomePhone# Home phone
#Skype# Skype
#Email# Email
#Address# Address
#Zip# Zip

 

All tags are case insensitive, so all of them will work: #name# , #NAME# , #Name#

Override Sender name

Our connector allows to override default sender name for a value specified in associated Account.

There is specific field ‘Sender name (BSG)’ that our connector adds on install to Account entity, if this field is filled – the value will be used for all contacts associated with this Account entity.

To use this feature, go to Account page:

And fill ‘Sender Name (BSG)’ field, then press ‘Save’ button.

Usage in Creatio (formerly BPM) process

Our connector allows to use BSG service delivery as step in Creatio process. Below is step-by-step sample of how to add such step into new Creatio process.

Go to ‘Process library’:

Press ‘New process’ button:

From the list on left (titled ‘User actions’) select ‘Send SMS’ option and drag it to BPM diagram:

The line from start of process should be connected to our step, same as line from our step to ‘end of process’ point.

Now you’ll need to fill the step parameters from (on right):

These parameters are typically filled from previous steps of Creatio process, so delivery step will take them from environment of current process.

To check that we created process correctly, press ‘Run’ button:

Using connector fromCreatio BPM scripts

Our connector allows to been used from so-called ‘Script Task’ – the special step in Creatio process flow with custom script inside.

Below is step-by-step sample of how to use that for mass SMS delivery.

  1. Navigate to ‘Process library’ section and create new BPM process, add ‘Read data’ and ‘Script Task’ steps, as on screen below:
  2. Click on ‘Read data’ step and configure parameters like on screen below:

    Connector expects the collection of Ids from ‘Contact’ entity only, so all other fetched fields will not be used.
  3. lick on ‘Script Task’ step and paste the code below:

    var log = global::Common.Logging.LogManager.GetLogger("BSGConnector");
    var userConnection = this.Get<UserConnection>("UserConnection");
    log.Info("test process has been started " );
    try {
    var colSource = Get<ICompositeObjectList<ICompositeObject>>("ReadDataUserTask1.ResultCompositeObjectList");
    var listIds = new List<Guid>();
    foreach (var parameter in colSource)
    {
    Guid value;
    parameter.TryGetValue("Id",out value);
    listIds.Add(value);
    log.Info(string.Format("parameter {0}",value));
    }
    log.Info(string.Format("total number of records: {0}",listIds.Count));
    var p = new Terrasoft.Configuration.BSGConnector.BSGUserTaskParameters();
    p.ContactIds = listIds;
    p.SmsMessage = "test message for mass delivery check, for #name# !";
    p.SenderName = "Santa-Claus";
    var smsTask = new Terrasoft.Configuration.BSGConnector.BSGUserTask(userConnection);
    smsTask.SendSms(p);
    } catch(Exception e) {
    log.Info("process error: " +e.Message);
    }
    return true;

Should look like on screen below:

This test process will write log records to default log file (Common.log), also these records could be viewed in runtime with ‘Telemetry extension’ (see below ):

Troubleshooting

Our connector supports multiple levels of logging, so to investigate source of problem you can adjust connector’s log level to see more details of its internal work.

Logger name: BSGConnector

Detailed guide of how-to setup logging in Creatio Online offsite instance could be found in Creatio (formerly BPM Online) documentation.

For cloud instances, you can try this extension «Telemetry log for creatio»:

https://marketplace.creatio.com/app/telemetry-log-creatio

that will allow to observe connector logs in real-time:

For any questions related to connector please contact our tech support: support@bsg.world