Build Your First Solution

Now that you know the basic concepts behind Tonkean™ and how to get around, you're ready to dig in and build your first solution.

This guide walks you through building a very simple solution that connects to an email system, monitors that email inbox, and sends a notification in response to received mail. This is the kind of solution you might build if you're monitoring an email inbox for a certain kind of request and making sure that request is sent to the right person—only in a simplified form.

The main purpose of this walkthrough is not to build a complex solution or one that perfectly mirrors a real-world scenario, but rather to give you some experience with the various parts of the build process and to help you feel more comfortable navigating Tonkean. However, the solution you build following this walkthrough will be something you can continue working on.

This walkthrough covers the following concepts:

  • How to create and deploy a module

  • How to add a data source

  • How to create a basic workflow

  • How to publish a solution

When just starting out as a maker, it can feel challenging to bring your workflow to life in Tonkean. Process orchestration can seem complex but is quickly learned! If you're feeling stuck or lost at any point, it can be helpful to slow down, make sure understand your process, how data flows from one place to another, and where people interact with that data. The more you experiment with the various features in Tonkean, the more comfortable you'll feel!

Create a New Solution

For the purposes of this exercise, we'll create a new solution to house our module, but you can also use an existing solution. If you choose to create a new module in an existing solution, skip to step 6 below.

  1. From any screen, select the grid icon, grid.png, in the top left and select Solutions Studio. The Solutions Studio screen displays.

  2. Select + New Solution. The Create New Solution window displays.

    create_new_solution.png
  3. Enter a descriptive name for your solution, keeping in mind that this solution should also house any related modules. Generally, it is recommended to maintain one solution per overall process or business problem (for example, a Legal Operations team might have one solution that contains several modules that automate a complex legal document request process).

    create_new_solution_name.png

    Select Create.

  4. Now that we have a new solution, we should detail the target business outcome of that solution. In the Business Outcome field, write out the expected impact the solution will have on your business process.

    new_solution_add_business_outcome.png
  5. Similarly, we need to add a description that lays out the general workflow of the solution and what apps it uses.

    new_solution_add_description.png
  6. Now, we can create the module that will contain the workflow logic. Hover over the New module tile and select Create New. The Create A New Ops Module window displays.

    new_module_create_new.png
  7. Enter a descriptive name for the module and select Create. The module builder screen displays.

    create_new_ops_module.png

    Notice the Input Source in the upper left, which is currently empty. Before we can use data in our new module, we must first add a data source on the Enterprise Component screen, so we'll set that up now.

    The module builder screen looks and behaves much like a flowchart, reading from left to right. The Input Source is always the starting point.

    module_builder_start_here_tile.png

Connect and Configure an Enterprise Component

  1. From any screen, select the grid icon, grid.png, in the top left corner and select Enterprise Components.

  2. On the Enterprise Components screen, select the + Add Data Source button to add a new data source.

    click_add_data_source.png
  3. In the dropdown, select Email Inbox. The Add New Data Source window displays.

    add_data_source_dropdown.png
  4. Select Email Inbox Intake. The New Email Inbox Intake Connection window displays.

    add_new_data_source_window.png
  5. Select Create a new connection. The New Email Data Source window displays.

    create_new_connection_window.png
  6. Enter a descriptive name for the new Email Inbox data source and leave the value for Attachment Storage set to None. Select Create.

    new_email_data_source_window.png
  7. The window displays your newly-created data source name. You have successfully created a new email inbox in Tonkean that you can send mail to.

    Inbox1_email_inbox_data_source_window.png
  8. Select Copy to save the email address. Paste this address into a separate document—we'll need this address later. Then, select Close.

    If you need to access the email address later, navigate to the Enterprise Components screen and select the data source from the list. The data source configuration panel displays.

    data_source_config_panel.png

    Select Connections to open the Connections screen, then select Edit.

    data_source_config_panel_connections_edit.png
  9. Before our solution is able to use the data from our new data source, we must grant it access. To grant access to the solution, return to the Enterprise Components screen by selecting the grid icon, grid.png, in the top left and selecting Enterprise Components. The Connected Data Sources screen displays.

  10. Select your new data source from the list. The data source configuration panel displays.

    data_source_config_panel.png
  11. Select Allow Solution access to this data source. The Solutions Access screen displays.

    data_source_config_allow_solution_access.png
  12. Select the toggle that corresponds with the solution that contains the module you want to give access to.

    data_source_config_allow_access_toggle.png

    Now we're ready to use this data source in any module within the selected solution. Continue on to the next section to begin building a workflow in our new module.

Build the Module Workflow

At this point, we have a connected data source and a new module to pull in data from that data source. Now, it's time to use triggers and actions to create a complete workflow to automate a process—in this case, a notification that we've received an email in our monitored inbox.

First, we must set the module Input Source to the email inbox data source we created earlier.

Connect Your Data Source

  1. In the module builder , select the Input Source tile, labeled Start here. The Configure Input Source panel displays.

    module_builder_start_here_tile.png
  2. On the Configure Input Source panel, select both the Accessible and Inaccessible checkboxes to display all available input sources. Alternatively, you can enter the name of the data source in the provided field.

    configure_input_source_inbox.png

    Locate the data source you created. For this walkthrough, we named our data source "Inbox1". Options for providing a custom filter or monitoring all emails from the data source display.

  3. Select All Emails to monitor all emails from this data source.

    configure_input_source_all_emails.png

    When building actual workflows, the best practice is to filter incoming emails so there's a smaller amount of data to monitor and respond to, but for the purposes of this walkthrough, we're choosing to monitor all emails. This syncs all emails from this inbox with Tonkean, though the module will not process all existing emails when it runs—only the newly-received emails.

  4. Select Preview Items & Save. The Input source items preview window displays.

    configure_input_source_preview_and_save.png
  5. In the Input source items preview window, leave the conditions as default and select Save. The module builder screen displays.

    input_source_items_preview.png

    Our module is now monitoring the email inbox, "Inbox1" that we created previously. Notice that the name of the data source has been added as the label to the Input Source tile.

    data_source_tile_with_new_data_source.png

Add Fields

Our data source is connected and we've configured Tonkean to monitor all emails received in our inbox. In order to use the information in the emails we receive, we need to configure our module to extract key pieces of information, or fields.

Fields are the individual pieces of information in the data sources, the source data and metadata that we want to manipulate or pass through to other parts of a workflow. For our module, we will extract the sender (both their name and email address), the email's subject line, and the body of the email.

  1. From the module builder screen, select the Fields button on the module builder toolbar. The Fields panel displays.

    module_builder_fields_button.png
  2. In the Matched Entities section, select + Add Field. A list of available fields displays in a new window.

    fields_panel_add_field.png
  3. Select the following fields from the list: Subject (Plain), From (Email), From (Name), and Body. Then, select Add Selected.

    select_fields_window.png

    Notice that the selected fields have been added in the Matched Entities section:

    fields_added_to_matched_entities.png

    Now these fields are available for us to use in our module. It's time to add the triggers and actions that configure the module to respond to specific emails coming in from our data source, "Inbox1".

Add Logic

By default, a module contains the Item is Added trigger as the first piece of logic after the Input Source. This is the most common starting point for most makers.

Remember that the name of the Item is Added trigger, like many of the triggers, should be understood in a general sense. The item this trigger is expecting to be added is dependent on the data source it's coming from and can be anything from a new email in an inbox to a new opportunity being added in Salesforce. Here, "item" means "object" or "thing."

For the purposes of this walkthrough, we will also use the Item is Added trigger because we are monitoring an email inbox and want to take an action when we receive an email in that inbox, so part of our work is already done.

Now, we must configure the module to take an action when we receive an email—we must tell it to do something when that email is received.

  1. To add an action block, select the plus icon, add_block.png, to the right of the Do arrow. A new Action Block is created and the Action Block panel displays.

    add_action_block_select_plus_icon.png
  2. Select Send Notification in the People Coordination section. The Send Notification panel displays.

    action_block_send_notification.png
  3. In the Who should Tonkean module ask? section, open the Communication Source dropdown and select Email.

    send_notification_comm_source.png
  4. To define where to send this notification email, select Email from field. Two options display:

    1. Add a "Creator Email" field to send the notification to our Tonkean email address.

    2. Add an "Emails - From (Email)" field to reply directly to the original sender.

    For the purposes of this walkthrough, we'll choose to add a "Creator Email" field so we know exactly where we can expect to receive the notification.

    send_notification_creator_email.png
  5. In the Email Subject field, enter a subject for all emails triggered by the receipt of a message in Inbox1.

    send_notification_email_subject.png
  6. In the Email Body section, write the content of the email by using free text and selecting the insert field icon, insert_field.png, to insert the fields we added from our data source. Enter text as you would normally to define how the notification email will display the information, including paragraph breaks to organize the information.

    send_notification_add_fields_to_body.png

    The end result uses both free text and fields from our "Inbox1" data source to essentially send a copy of the received email to our preferred inbox. Notice the free-text labels and paragraph breaks to separate each field:

    send_notification_email_body.png

    Now the action is complete and the module is almost ready. Next, we will prepare our module to go live by moving it from the Build environment to the Production environment and publishing it.

Publish the Module

The basic workflow we built for the module is complete and ready to start sending notification emails to our designated address (our Tonkean email address, in this case), but first we must take a few steps to enable and publish the module.

  1. At the top of the module builder screen, select Mark for Publish. The Mark Module as Ready for publish window displays.

    mark_for_publish.png
  2. Select Next. The Test Workflow prompt displays.

    mark_module_as_ready_for_publish.png
  3. For now, we will skip testing the module. Select Next. The change description field displays.

    mark_module_as_ready_for_publish_test_workflow.png
  4. Enter a brief description of the changes to the module and select Mark for Publish.

    mark_module_as_ready_for_publish_describe_change.png

    A confirmation message displays in the top right of the module builder screen:

    module_marked_for_publish_confirmation.png
  5. Select the solution in the upper left of the module builder screen or select the grid icon, grid.png and then Solutions Studio to navigate to the Solutions Studio screen. Find the solution that contains the new module and select Publish Version. The Publish to Environment window displays.

    solutions_studio_publish_version.png
  6. Confirm the status of the module is Ready to Publish and select Continue. The Publish window displays.

    publish_to_environment.png
  7. Enter a description of the changes to publish and select Publish Now.

    publish_window.png
  8. Select the module to navigate to the module builder screen. In the upper right corner, select the environment picker and select PRODUCTION to move the module from Build to Production.

    move_module_to_prod.png
  9. Beside the environment picker, select the On/Off toggle to turn the module on.

    turn_module_on.png

That's it—our module is officially live!

Test the Module

Now that our module is published, we can send an email to our "Inbox1" input source and see if our module sends a notification email to the email address we specified in our Send Notification action.

  1. Locate the document you used to store the Tonkean-generated email address we saved in the Connect and Configure an Enterprise Component section.

  2. In your email application of choice, compose an email that contains a subject and a body, addressed to the Tonkean-generated address for "Inbox1".

    test_email_to_new_module.png
  3. After a few moments, check the Tonkean email address you specified as the recipient of the notification email in the Send Notification action. If everything has worked as expected, you should have received an email from Tonkean that looks like the one below:

    email_received_from_module.png

    Our module worked! We can see the free text we included in our Send Notification action, as well as the fields we extracted from our "Inbox1" data source.

    While this is obviously as very simple example of a module, this same structure can be easily expanded on to add nuance and complexity.

    For example, instead of sending the email notification to your own email address, you could reply back to the sender with the key pieces of information they're asking for. Better yet, you could filter the incoming emails, looking for only the emails that contain a certain word or phrase to ensure you're sending the right information where it's needed.

    The more you experiment with workflows and actions, the more possibilities open up—all from a simple email inbox listener.

Check the Module History

If your module did not successfully send the notification email to the email address you provided, there are a couple ways to troubleshoot the problem and figure out what happened. The easiest place to check is the module history:

  1. On the module builder screen, confirm that the correct environment is selected. For this walkthrough, ensure the Production environent is selected. Then, select History in the upper right. The Module Events History screen displays.

    module_builder_history.png
  2. On the Module Events History screen, view the Flow Investigation section to see a log of the actions and triggers in the module. If the module failed at some point in the workflow, that failure will be documented here.

    module_events_history.png

    Notice also how the left panel displays each time the "Inbox1" input source was triggered by the receipt of a new email. There are several triggers that resulted in an error before the successful workflow run at the top.

  3. When done, select Close at the top right to return to the module builder screen.

    module_events_history_close.png

Alternatively, you can check the status of a module on the Business Reports screen. See What are Business Reports? for an overview of this screen or Business Reports and Metrics for more detailed information.

Next Steps

Congratulations! You have successfully created your first Tonkean module and can now call yourself a fledgling maker. The road to building complex modules certainly has its challenges, but everyone starts here—by building their very first module.

Now, it's time to continue building and adding to your module, or to try building another module from scratch. We recommend that most new makers attempt to customize this walkthrough module before moving on. There is much you can learn through experimentation.

When you're ready, explore more topics in the Maker Playbook for detailed information about specific Tonkean features or dig into the Resources section for reference material to help you as you build.

And, as always, keep making!