Marketing campaign diagrams are created in a visual campaign designer in the Campaigns section. The campaign diagram consists of campaign elements and transitions (flows).
Once the campaign is launched, the flow-schema of the campaign is created. The campaign elements are converted to a campaign execution chain and the start time is calculated for each element. The flow-schema can be significantly different from the visual campaign diagram in the designer.
Campaign elements can be synchronous and asynchronous.
Synchronous elements are executed according to the order specified in the flow-schema. The transition to the subsequent elements is performed once the synchronous element is executed. The execution flow is blocked and waits for the operation to complete.
Asynchronous elements wait for the finished execution of certain external systems, resources, asynchronous services, or user reactions (e.g., clicking a link in an email).
Their position in the flow-schema is determined by their element type. The Add from folder and Exit according to folder conditions elements are executed first. These elements are used to add or remove participants from the campaign audience. Campaign participants are moving from one element to the other through the flows. If the flow has certain configured conditions, the system filters the participants based on these conditions and determines the execution time of the subsequent element.
The mechanism for planning the next campaign launch
The following is the algorithm for for planning the next campaign launch:
-
The time of the next launch of an element is determined by the configured delay:
-
The “In a day” option is selected. The date and time of the next execution of this element is calculated with the help of the following formula:
Date and time of execution = current date and time + N minutes / hour,
where N is the value of the Number of days field, populated by the user.
-
The “Few days” option is selected. The next execution of this element is performed with the help of the following formula:
Date = current date+ N days,
where N is the value of the Number of days field, populated by the user.
Execution time = time specified by the user.
- The “No, execute after the previous one” option is selected. The next execution of this element is performed at the time of the next launch of the campaign.
-
- According to the variant described in paragraph 1, the launch time for each element of the campaign scheme is calculated.
- Upon comparing all values, the closest launch time selected and set as the campaign launch time.
- Forming a list of elements, which will be executed upon next launch. The list contains all elements, the launch time of which is the same as the campaign launch time.
Main campaign element classes
JavaScript classes
The base element schema class is ProcessFlowElementSchema. The CampaignBaseCommunicationSchema is the parent class for all elements in the Communications group. The CampaignBaseAudienceSchemaAudience group of elements.
When creating an element in a new group of elements, it is recommended to implement the base schema of the element first, and then inherit each element from it.
Each schema corresponds to the schema of the element properties edit page. The base edit page schema is span class= "filled">BaseCampaignSchemaElementPage. Each new element page extends the base page.
The CampaignSchemaManager class manages the schemas of elements available in the system. It inherits the main functionality of the BaseSchemaManager class.
C# classes
Simple element classes
CampaignSchemaElement – base class. All other elements are inherited from this class.
SequenceFlowElement – base class for the Sequence flow element.
ConditionSequenceFlowElement – base class for the Condition flow element.
EmailConditionalTransitionElement – transition element class by response.
AddCampaignParticipantElement – add audience (participants) element class.
ExitFromCampaignElement – the class of the audience exit element.
MarketingEmailElement – the class of the Email element.
Executable element classes
CampaignProcessFlowElement – base class. All other executable elements are inherited from this class.
AddCampaignAudienceElement – audience element class.
ExcludeCampaignAudienceElement – the class of the audience exit element.
BulkEmailCampaignElement – the class of the Email element.
Use the Campaign designer to set up marketing campaigns. Using this designer, you can create a campaign diagram that consists of interconnected elements. In addition to default campaign elements you can create custom ones.
Algorithm for adding a custom campaign element
- Create a new element for the Campaign designer.
- Create the element’s edit page.
- Expand the Campaign designer menu with a new element.
- Create the element’s server part.
- Create executable element for the new campaign element.
- Add custom logic for processing campaign events.
Example. Create a new campaign element for sending text messages (SMS) for users.
Example implementation algorithm
1. Creating a new element for the Campaign designer
To display the element in the Campaign designer UI, add a new module schema for the campaign element. The procedure for creating a module schema is covered in the “Create a client schema” article. Set the following properties for the created schema:
- Title – "Test SMS Element Schema".
- Name – "TestSmsElementSchema".
Attention. The schema names in the case below do not contain the Usr prefix. You can change the default prefix in the Prefix for object name (SchemaNamePrefix) system setting.
Add a localized string to the schema:
- Name – "Caption".
- Value – "Test SMS".
Add images that will represent the campaign element in the Campaign designer. Use the SmallImage, LargeImage and TitleImage properties to add the images.
In this example we used a scalable vector graphics (SVG) image available here.
Add following source code on the Source Code section of the schema":
Specifics:
- The managerItemUId property value must be unique for the new element and not repeat the value of the other elements.
- The typeName property contains the name of the C# class that corresponds to the campaign element name. This class will be saving and reading the element’s properties from the schema metadata.
Save the schema to apply changes.
Adding a group of elements
If a new group of elements, such as Scripts must be created for the campaign element, the schema source code must be supplemented with the following code:
Also, add a localized string with the following properties:
- Name – "ScriptsElementGroupCaption".
- Value – "Scripts".
Save the schema to apply changes.
2. Creating the element’s edit page
Create the campaign element’s edit page in the custom package to enable the users to view and edit the element’s properties. To do this, create a schema that expands BaseCampaignSchemaElementPage (CampaignDesigner package). The procedure for creating a replacing client schema is covered in the “Create a client schema” article.
Set the following properties for the created schema:
- Title – "TestSmsElementPropertiesPage".
- Name – "TestSmsElementPropertiesPage".
- Parent object – "BaseCampaignSchemaElementPage".
Add localized strings to the created schema with properties given in the table.
Localized string properties
| Name | Value |
|---|---|
| PhoneNumberCaption | Sender phone number |
| SmsTextCaption | Message |
| TestSmsText | Which text message should be sent? (Which SMS text to send?) |
Add following source code on the Source Code section of the schema":
Save the schema to apply changes.
3. Expanding the Campaign designer menu with a new element
To display the new element in the Campaign designer menu, expand the campaign element base schema manager. Add a schema that expands CampaignElementSchemaManagerEx (the CampaignDesigner package) to the custom package. The procedure for creating a replacing client schema is covered in the “Create a client schema” article.
Set the following properties for the created schema:
- Title – "TestSmsCampaignElementSchemaManagerEx".
- Name – "CampaignElementSchemaManagerEx".
- Parent object – "CampaignElementSchemaManagerEx".
Add following source code on the Source Code section of the schema":
Save the schema to apply changes.
4. Creating server part of the custom campaign element
To implement saving the campaign element properties, create a class that interacts with the application server part. The class must inherit CampaignSchemaElement and override the ApplyMetaDataValue() and WriteMetaData() methods.
Create a source code schema with the following properties:
- Title – "TestSmsElement".
- Name – "TestSmsElement".
For more information on creating source code schemas, please see the Create the Source code schema article.
Add the following source code on the Source Code section of the schema":
Publish the source code schema.
5. Creating executable element for the new campaign element
For the custom campaign element to execute the needed logic, add an executable element. It is a class that inherits the CampaignProcessFlowElement class, where the SafeExecute() method is implemented.
To create an executable element, add a source code schema element with the following properties in the custom package:
- Title – "TestSmsCampaignProcessElement".
- Name – "TestSmsCampaignProcessElement".
Add following source code on the Source Code section of the schema":
Publish the source code schema.
6. Adding custom logic for processing campaign events
Use the event handler mechanism to implement custom logic on saving, copying, deleting, running and stopping campaigns. Create a public sealed handler class that inherits CampaignEventHandlerBase. Implement interfaces that describe specific event handler signatures. This class must not be generic. It must have a constructor available by default.
The following interfaces are supported in the current version:
- IOnCampaignBeforeSave – contains method that will be called before saving the campaign.
- IOnCampaignAfterSave – contains method that will be called after saving the campaign.
- IOnCampaignDelete – contains method that will be called before deleting the campaign.
- IOnCampaignStart – contains method that will be called before running the campaign.
- IOnCampaignStop – contains method that will be called before stopping the campaign.
- IOnCampaignValidate – contains method that will be called on validating the campaign.
- IOnCampaignCopy – contains method that will be called after copying the campaign.
If an exception occurs during the event processing, the call chain is stopped, and campaign status is reverted to the previous one in DB.
Note. When implementing the IOnCampaignValidate interface, save errors in the campaign schema using the AddValidationInfo(string) method.
Additional case conditions
In order for the new custom campaign element to work, SMS gateway connection is required. The connection, account status and other parameters must be checked during campaign validation. The messages must be sent when campaign starts.
To implement these conditions, add a source code schema element with the following properties in the custom package:
- Title – "TestSmsEventHandler".
- Name – "TestSmsEventHandler".
Add following source code on the Source Code section of the schema":
After making the changes, publish the schema. Compile the application and clear the cache.
As a result, a new TestSMS element will be added in the campaign element menu (1) that the users can add to the campaign diagram (2). When an added element is selected, its edit page will be displayed (3).
Attention. When saving the campaign, the “Parameter ‘type’ cannot be null” may occur. The error indicates that the configuration library was not updated after the compilation and therefor does not contain the new types.
Recompile the project and clear all possible storages with cached data. You may also need to clear the application pool and restart the website in IIS on the application server.
Starting from version 7.12.4, a new Triggered adding campaign element has been added to Creatio. The way the element works with campaign audience has been changed: as soon as the trigger is run, the synchronous campaign element is launched.
Thus, new and existing campaign elements must be configured for working with this element.
To include the custom element into the synchronous fragment and make sure it works correctly both for the scheduled execution and triggers, make the following changes on the server side:
- Specify the additional CampaignSchemaElementType.Sessioned type for the element.
- The executed element for the campaign custom element (the inheritor of the CampaignProcessFlowElement class) must work using the CampaignAudience base property. Perform all operations (specifying the audience, selecting the Step complete checkbox) via the object in the CampaignAudience property of the ICampaignAudience type.
Example. Configure the marketing campaign element for sending SMS messages to users. Learn how to create this element in the “Add a custom campaign element” article.
Example implementation algorithm
1. Modifying the class that interacts with the server side of the application
Attention. Perform steps 1-6 from the “Add a custom campaign element” article before you implement the case.
Change the TestSmsElement source code schema class (the inheritor of the CampaignSchemaElement class). Specify additional ElementType — CampaignSchemaElementType.Sessioned in the class constructor.
2. Modifying the executed element for the new campaign element
Modify the TestSmsCampaignProcessElement source code schema class (the inheritor of the CampaignProcessFlowElement class). Add the audience reading operation to the SafeExecute() method implementation via the object in the CampaignAudience property of the ICampaignAudience type.
Use Campaign designer to set up your marketing campaigns. You can create a visual campaign diagram that would consist of interconnected pre-configured elements. You can also add custom campaign elements.
Algorithm of adding a custom flow (an arrow)
- Create a new schema for the Flow element.
- Create the edit page for the Flow element properties.
- Create the server part for the Flow element.
- Create the executed element for the flow transition.
- Create the CampaignConnectorManager replacing module for adding the flow operation logic.
- Connect the CampaignConnectorManager replacing module.
Example. Create a custom flow (an arrow) from the new campaign element for sending SMS-messages to a user and add a possibility to select the bulk sms response condition. On the setup page, a user can select an option to either ignore the responses or take them into consideration based on the list of possible bulk sms response types. If no response type is selected, the flow is enabled for any response.
Attention. In this case, the Usr prefix is not used in schema names. You can change the prefix used by default in the Prefix for object name system setting (the SchemaNamePrefix code).
Attention. Perform steps 1-6 from the “Add a custom campaign element” article before you implement the case.
Example implementation algorithm
1. Creating the TestSmsTarget and TestSmsResponseType objects
Create schemas for the TestSmsTarget and TestSmsResponseType objects in the development package.
Learn more about creating object schemas in the “Create the entity schema” article.
Add a column with the following properties to the TestSmsResponseType schema:
- Title – “Name”
- Name – “Name”
- Data type – “Text (50 characters)”
Add columns with the following properties to the TestSmsTarget schema:
Primary column properties of the TestSmsTarget object schema
| Title | Name | Data type |
|---|---|---|
| Phone number | PhoneNumber | “Text (50 characters)” |
| SMS text | SmsText | “Text (50 characters)” |
| Contact | Contact | “Lookup” – “Contact” |
| Test SMS response | TestSmsResponse | “Lookup” – “TestSmsResponseType” |
Learn more about adding object schema columns in the “Create the entity schema” article.
Save and publish the objects.
Create a lookup for the TestSmsResponseType object and populate it with the “Sms delivered”, “Canceled”, “Error while receiving”, etc. values. The response identifiers (Ids) will be used in the edit page code of the condition flow properties from the bulk SMS.
2. Creating a new schema for the flow element
To display the element in the Campaign designer user interface, create a new module schema in the development package. The procedure for creating a module schema is covered in the “Create a client schema” article. Set the following properties for the created schema:
- Title – “ProcessTestSmsConditionalTransitionSchema”.
- Name – “ProcessTestSmsConditionalTransitionSchema”.
Attention. The schema name for the arrow must contain the “Process” prefix
Add the following source code to the Source code section of the schema:
Save the created schema.
3. Creating the edit page of the flow element properties
To display and modify campaign element properties, create its edit page in the development package. Create the schema replacing CampaignConditionalSequenceFlowPropertiesPage (the CampaignDesigner package). The procedure for creating a replacing schema is covered in the “Create a client schema” article.
Set the following properties for the created schema:
- Title – “TestSmsConditionalTransitionPropertiesPage”.
- Name – “TestSmsConditionalTransitionPropertiesPage”.
- Parent object – “CampaignConditionalSequenceFlowPropertiesPage”.
Add localizable strings, whose properties are listed in table to the created schema.
Primary properties of the localizable strings
| Name | Value |
|---|---|
| ReactionModeCaption | What is the result of the {0} step? |
| ReactionModeDefault | Transfer participants regardless of their response |
| ReactionModeWithCondition | Set up responses for transferring participants |
| IsTestSmsDelivered | Test SMS delivered |
| IsErrorWhileReceiving | Error while receiving |
Add the following source code to the Source code section of the schema:
Save the created schema.
4. Creating the server part of the flow element from the Bulk SMS element
To implement saving the base and user campaign element properties, create a class interacting with the server part of the application. The class should inherit CampaignSchemaElement and override the ApplyMetaDataValue() and WriteMetaData() methods.
Create the source code schema with the following properties:
- Title – “TestSmsConditionalTransitionElement”;
- Name – “TestSmsConditionalTransitionElement”.
Creating the source code schema is covered in the “Create the Source code schema” article.
Add the following source code to the Source code section of the schema:
Save and publish the created schema.
5. Creating the executed element for the flow from the Bulk SMS element
To add a functionality that would take into consideration the response type as per the sent bulk sms, create the executed element. It is a class, the inheritor of the ConditionalTransitionFlowElement class.
To create the executed element, add the source code schema with the following properties in the development package:
- Title – “TestSmsConditionalTransitionElement”.
- Name – “TestSmsConditionalTransitionElement”.
Add the following source code to the Source code section of the schema:
Save and publish the created schema.
6. Creating the CampaignConnectorManager replacing module for adding the flow operation logic
To add specific logic of the flow operation upon changing the source (i.e. the element that the outgoing arrow is generated from), create a new module schema replacing the CampaignConnectorManager module in the development package. The procedure for creating a module schema is covered in the “Create a client schema” article. Set the following properties for the created schema:
- Title – “TestSmsCampaignConnectorManager”.
- Name – “TestSmsCampaignConnectorManager”.
Add the following source code to the Source code section of the schema:
Save the created schema.
7. Connecting the CampaignConnectorManager replacing module
To connect the module created on the previous step, create a replacing client module and specify BootstrapModulesV2 from the NUI package as the parent object. The procedure of creating a replacing client module is covered in the “Create a client schema“ article.
Add the following source code to the Source code section of the schema:
Save the created schema.
Note. During an actual implementation of this case, we recommend creating a separate Bulk SMS object schema. The TestSmsElement and TestSmsConditionalTransitionElement objects will contain the Id of this object and not the SmsText, PhoneNumber … fields. The TestSmsCampaignProcessElement executed element in the Execute() method must contain the logic of adding contacts to the bulk sms audience. A separate mechanism (or several mechanisms) must perform sending of the bulk sms and afterwards record the participants’ responses. Based on these responses, the arrow will transfer the campaign audience to the following campaign step.