Sitecore Corner

Note: This post assumes you went throught Part 1 of the series where I talked about the basic building blocks, how to navigate Sitecore Connect etc. Which means I will skip showing some button locations (for example how the create a new connection/recipe and how to select a tool from the list). If you need a refresher or just stumbling upon this blog post – please navigate to Part 1 of the series.

Now that we have established the foundational concepts of Sitecore Connect, we can leverage this knowledge to build no-code integration with ease. The platform’s user-friendly interface and pre-built connectors, tools, and APIs make it simple for even non-technical users to configure and deploy integrations between Sitecore and other systems, using low-code and no-code approach. Overall, the learning curve for Sitecore Connect is relatively small, thanks to its intuitive design.

When building a no-code integration with Sitecore Connect, the most suitable Sitecore product currently available is Sitecore Send. Sitecore Send Connector offers a diverse range of pre-built triggers and app actions, that cover most of the typical integration points for e-mail marketing.

Sitecore Send Triggers

Sitecore Send App Actions

And now let’s put our knowledge of Sitecore Connect to use and build a no-code integration.

Building a No-Code Integration: OneDrive and Sitecore Send Email List Synchronization

Business Case

Despite living in 2023, there are still customers who have not fully automated their contact and location list management processes. Many businesses still rely on a semi-manual approach that involves exporting contacts from multiple subsystems, storing them in a CSV file, and uploading them to a file sharing solution like OneDrive, Dropbox, Google Drive, SharePoint, or an FTP server. This list is then picked up and synchronized with the existing email marketing tool to serve as the foundation for a new campaign that the marketing team is looking to launch.

This process is very suitable to automate with Sitecore Connect with absolutely zero coding knowledge required.

Step 1: Setting Up Connections

Note: In this example I will be using a connection to One Drive, but the same logic can be applied to SharePoint, Dropbox, GoogleDrive, FTP or even on-premises file location with pre-built connectors.

As part of the previous blog post we already had one connection available inside the Sitecore For Beginners Project with Sitecore CDP.

To demonstrate this integration, we just need 2 connections -Sitecore Send and OneDrive.

Sitecore Send Connection

Note: Sitecore documentation website already has an excellent article on how to create a Sitecore Send Connection for Sitecore Connect: https://doc.sitecore.com/send/en/users/sitecore-send/create-a-connection-from-sitecore-connect-to-sitecore-send.html, if you follow the steps there you can fast forward to the next part.

To create a Sitecore Send connection you need an API Key and Plugin Secret Key. You can see how to obtain them in the link already mentioned above.

The Sitecore Send connection requires 4 properties:

1. Connection Name – Let’s name it “Sitecore for Beginners -Sitecore Send”.
2. Location – I am going to use the existing “Sitecore Connect For Beginners” project.
3. API Key – Your Sitecore Send API Key
4. Plugin Secret Key – Your Sitecore Send Plugin Secret Key

After ensuring that the values are correct, clicking on the “Connect” button should lead to the screen appearing as follows, indicating that the connection has been successfully established.

OneDrive Connection

Note: As I already mentioned above – you can use a connection to any file sharing tool, it won’t change the flow of the entire integration. OneDrive here is used just for example purposes.

Setting up a OneDrive connection is a straightforward process as Workato provides a built-in integration with OneDrive using single sign-on (SSO). This same process applies to other file-sharing solutions such as Dropbox and Google Drive.

The OneDrive connection requires 3 properties (and requires a button press :)) :

1. Connection Name – Let’s name it “Sitecore for Beginners -OneDrive”.
2. Location – I am going to use the existing “Sitecore Connect For Beginners” project.
3. Account type – Either “Personal” or “Business”. I am going to use my Personal Account for this example.

Once the required settings have been configured, simply click on the “Sign in with Microsoft” button, which will prompt a login screen if you are not already authenticated. Then, Workato will request some permissions for your OneDrive account, allowing it to read files and subscribe to different webhooks.

If everything goes according to plan you should see a screen similar to this one.

Step 2: Creating the Recipe

If we head back to our project it now contains 3 Connections for Sitecore CDP, Sitecore Send and OneDrive.

So let’s head and create a new recipe that is going to use the “Trigger from an app” as starting point.

Game Plan

Let’s agree that our CSV format will be the following

firstname,lastname,email
Nikola,Gotsev,nsgocev@gmail.com
Test,Test,test@gmail.com

So let’s outline our gameplan on how we are going to handle this file type

1. The recipe should trigger when there is a new/updated csv file.
2. Parse the CSV into individual lines
3. Itterate over the lines and add them to a predefined mailing list in Sitecore Send
4. (Optional) – Make sure a proper error handling and logging is in place, so that the recipe can run properly even if a line in the CSV has been malformed.

With our game plan in place let’s get straight to setting up our first Recipe.

Recipe Setup

As we already mentioned we are building a reciple that will trigger on file upload, so the trigger for it is going to be “Trigger from an App”

Recipe Step 1: Trigger

To start building our recipe, we need to first select an action that will trigger it. On the recipe creation screen, we can choose the OneDrive application as the source of the trigger.

OneDrive offers four pre-built triggers, but the most fitting for our purposes is the New/Updated file trigger. With this trigger, our integration will be activated whenever a new file is uploaded/updated in a specific folder, without the need for any additional processes or requirements on our customers’ end, such as assigning specific file names or avoiding duplicate names.

After that we can accept our pre-existing connection that we created in the previous step, or create a new one

After this has been done we just need to pick the folder which Sitecore Connect is going to monitor for changes.

Note: There are some more advanced options that can be configured on any action, I am generally not going to cover them if we don’t actually need them, but most of the time they are self explanatory.

To ensure that only CSV files trigger our recipe, we can set up a validation using the “Set trigger conditions” option. By checking the file extension, we can ensure that only CSV files uploaded to the specific OneDrive folder will be processed, avoiding any mistakes from customers who might upload the wrong file type.

Recipe Step 2: Downloading the file

Note: I played with different file sharing solutions in Sitecore Connect and OneDrive seems to be the only connector that doesn’t automatically download the file and has to be promoted. If you are using something different, keep in mind the file will probably be downloaded already in previous step

So with our trigger in place, now we need to download the file from one drive whenever it passed the trigger conditions. So lets go ahead and add a new action following the screenshot trail bellow.

The OneDrive connector provides out of the box download file action, so we can just leverage this.

The FileID required by the action to run was actually provided by the initial state model, so we just need to fill it out in the promt:

With our file downloaded let’s move the next step of our game plan – Parsing the CSV.

Recipe Step 3: Parsing the CSV

Note: The parse CSV action only accepts a maximum of 50000 lines in one go. In case your CSV files are bigger you might have to do additional pre-processing of the file to split it into small chunks

Workato comes with a pre-built action for manipulating CSV files, so parsing it will be a breeze. Let’s add a new action and follow the trail:

For the CSV contents, we can use the contents from our downloaded file

Based on the format we already defined – our column delimiter is comma and our CSV contains a header line, so the following properties don’t have to be modified:

Now the only thing remaining for us is to define the header schema. We can do it by pressing “Add column name” and describing our column OR providing a sample CSV from which the column names will be infered (which I am going to do):

Clicking the “Use a sample CSV file” will open a wizard in which you can upload your sample CSV and will automatically defer the headers from it:

If the schema looks correct – just click Generate Schema and workato will take care of mapping the header field:

With our CSV file parsed, lets move to the next step – itterating over it.

Recipe Step 4: Itterate over the CSV lines

In Sitecore Connect it is very easy to itterate over a list of predefined steps which we covered in the previous article – Repeat Action. So let’s go and add a new repeat action

For the input list we can just select the Lines already parsed in the previous step:

And voilla ! We already have an intterator over all the CSV lines.

Recipe Step 5: Error Handling

Now is a good time to set up error handling in case any of our CSV lines are malformed or contain bad data, such as an email in the wrong format. Fortunately, this can be done easily using the “Handle Errors” action provided out of the box by Workato:

Adding the handle errors will give us two blocks – “Monitor ” and “On Error” (or try-catch :)).

Within the “On Error” block, we can handle any errors that may occur during the lines processing execution. For this purpose, I will be utilizing the Workato logger to log any errors and the line at which they occurred.

Recipe Step 6: Create new subscriber in Sitecore Send

Now that we have taken care of any potential issues with malformed lines, let’s move on to synchronizing our data with Sitecore Send.

Sitecore Send offers a variety of out-of-the-box actions, and fortunately, it includes the exact one that we need for our business case: “Create Subscriber”

We are going to utilize the connection to Sitecore Send we created in the previous steps:

To start our Journey we first need to pick a Email List to which the contacts will be synchronized. I have already prepared Sitecore For Begginers List which can be used for it:

After selecting the list – there is 3 properties we need to fill:

1. Subscriber email address – we can use the email in the line we are currently itterating over. Also at this point you will probably notice how smart the Workato platform is – it knows the field requires an email and provides a direct suggestion to the data ,that is named email, to be injected directly into the box.

2. Subscription Consent – I assume that all of the customers in your external system have given their consent to receive email campaigns, as failure to comply with email marketing regulations can lead to significant legal and reputational consequences for your organization. So let’s just select “Yes”

3. Subscriber name – We already have the first name and the last name of our contacts inside the CSV so lets just use both of them combined with space bar:

And with that the recipe is ready. Next step is to test if everything was properly set.

Step 3: Testing the Recipe

Testing recipes is a crucial step to ensure the successful execution of our job before it is deployed. Fortunately, both the Workato platform and Sitecore Connect offer a straightforward way to test recipes.

Sitecore Connect provides the ability to run full end-to-end testing of our recipe by using the “Test Recipe” function. This function runs the entire recipe with actual data and provides a detailed log of each step’s execution.

So let’s go ahead and click on test recipe located in the top right corner of the screen:

As there is currently no CSV files uploaded in the directory that we are monitoring the screen you are going to see is probably similar to this one:

So let’s upload our sample CSV in our File Share:

Then we can go back to the test screen and click the Check Now button (or we got lucky and it already fell into the 5 minute window in which new files are getting pulled out of OneDrvie).

If all the steps have been correctly set up, the user will be rewarded with a success screen displaying data about the individual steps + all the steps that have been executed (as you see we never went to the error block so it was not displayed on the run). However, if any errors are present, meaningful error messages will be displayed to guide the user in the correct direction to fix them. In my case, all steps were completed successfully, and everything was green (on the 5th attempt :))

You can also jump into your Sitecore Send subscription and confirm the contacts have been properly imported there.

Now that we have a fully functional recipe, it’s time to activate it and start automating our email marketing process.

Step 4: Starting the Recipe

Initiating the recipe is a simple process that can be done by navigating to the recipe screen and clicking on the “Start Recipe” button. Once the recipe is activated, a status screen is displayed, providing comprehensive information about the recipe executions, logs, and pool interval, among other useful details.

And that’s it ! We now have a working fully automated synchroization process between our File sharing solution (OneDrive) and Sitecore Send. And with the power of Sitecore Connect we achived this without writing a single line of code !

Conclusion

In this article we went through setting up a no-code integration by just using out of the box connectors and actions provided by Sitecore Connect and the Workato platform. Writing this blog post describing the process took considerably longer than building the recipe itself (5-10 minutes). This example highlights the incredible power that Sitecore Connect can bring to your organization by allowing non-technical users to easily create and automate complex workflows without any coding knowledge.

For my technical audience (which is probably the most of my readers), fear not the upcoming articles in this series will cater to more advanced topics. We’ll progress from building no-code connections to more complex scenarios, eventually reaching the point where we’ll be writing custom connectors in Ruby. So stay tuned and join me on this exciting journey to explore the full potential of Sitecore Connect!