Skip to main content

Orchestrate Multiple Modules

While individual modules are flexible enough to handle complex workflows with various branches of logic, it's helpful, or even necessary, for some processes to use separate, coordinated modules.

Processes that include multiple entry points to the same core workflow commonly separate that process across multiple modules. For example, if your legal team accepts requests for legal documents from email, Slack, and online forms, and processes all these requests using the same core workflow, partitioning off that core workflow in a separate module may be the best way to build the solution.

Similarly, for processes that include a hand-off to a separate business unit for something like review or translation, separating out that part of the workflow using a stand-alone module can make the overall solution much neater and easier to maintain.

Separating a complex workflow into multiple modules has several benefits:

  • Simpler maintenance and upkeep

  • Improved clarity and transparency

  • Fewer dependencies on other aspects of the module logic

  • Reduced duplication of work

In general, if you can separate parts of a complex process, it's worth considering using separate modules to benefit from the decreased maintenance and added simplicity. Additionally, as items move between these related modules, automatically-created matched items allow you to maintain visibility and track field changes across the entire process, where relevant.

To demonstrate the value of splitting up a workflow into several connected modules, let's walk through a common use case.

Create Connected Modules

For this walkthrough, we'll create a basic legal request and coordination solution designed to automate requests for legal documents, specifically nondisclosure agreements (NDAs) and offer letters. We want to enable process contributors to submit legal requests through multiple channels, but we don't want to duplicate the logic of handling those requests for each channel, so we'll create several connected modules that separate the request intake and the request coordination. Below are the modules we'll build:

  1. Email Request (intake) - Process contributors submit a legal request to an email inbox.

  2. Slack Request (intake) - Process contributors submit a legal request using a Slack channel.

  3. Request Coordination - This module contains all the core logic to analyze the request, determine whether it's for an "NDA" or an "Offer" (our two most popular requests), and create a Zendesk ticket for the request.

This walkthrough requires some basic knowledge of building workflows: creating modules, connecting data sources, and adding actions. If you're a new maker, check out Tonkean 101 or explore any new concepts in Build Module Workflows. The relevant topics are also linked in the procedure below for reference.

Build the Target Module

In our example, the Request Coordination module is the core of our workflow and will do all the heavy lifting, so we build this module first. When working on a request coordination workflow, it can be helpful to work backward—start with the end state, understand what information you need to reach that end state, and then build the intake modules to provide that information.

request_coordination_overview.png

In your specific workflow, this module could be any module that contains a self-contained business process whose intake comes from another process.

  1. Create a new solution.

  2. Add a new module to your solution.

  3. Build the module workflow that's specific to your business process, setting the intake source to manual:

    1. Select the Items button. the Items panel displays.

      items_button_select.png
    2. Select Configure to select the intake source. The Configure Intake Source panel displays.

      items_panel_configure.png
    3. Select Manual intake source.

      input_source_manual.png
  4. Add custom manual fields for the content you want the target module to receive from the sending modules. For our example that's receiving requests, we create Request and Requestor fields that we'll use to pass in the name of the person submitting the request and the body of their message.

    request_custom_fields.png

Build the Intake Modules

With our core module complete and ready to receive items, we can build our request intake modules: Email Request and Slack Request. Our example workflow includes just two modules that handle user requests, but you can connect any number of similar intake modules that send an item to a central module.

Build the Email Request Module

The first way we want process contributors to be able to submit requests is through email, so we build the Email Request module and configure it to send the necessary information to our target Request Coordination module.

  1. Create an email inbox data source where process contributors can submit email requests. We name ours "Legal Request".

  2. Add a new module to your solution for the email intake.

  3. Set the intake source to your newly created email inbox data source:

    1. Select the Item tile in the top left corner of the module builder screen. The Item Details panel displays.

      item_tile_select.png
    2. Select the Email intake data source.

      email_intake_source_select.png
    3. Select your email inbox data source. The connection configuration screen displays.

      email_inbox_data_source.png
  4. Select the EMAIL entity to collect. The entity conditions group displays.

    email_data_source_email_entity.png
  5. You can set a Custom Filter to monitor only emails that contain certain keywords in the email subject line or body, but since we're leveraging a training set to listen for "NDA" and "offer" phrases in emails and handling them accordingly in our core module, we choose to not add a condition and collect all emails from the inbox. When finished, select Save.

    email_req_input_source_all_emails.png
  6. In the module builder select the Fields button, scroll down to the Matched Entities section, and select + Add Field to map the relevant matched entity fields from the intake source you want to use in the intake module and the target module. For our use case, we mapped fields for the email sender, the email body, and some other fields to track the timeline of the request.

    email_matched_ent_fields.png
  7. Next, we need to add logic to send the module item to our Request Coordination module when we receive a new email. Select the add block button, add_block.png. The Action Block panel displays. Select the Module Actions action. The Module Actions options display.

    email_req_add_module_actions_block.png
  8. In the Module actions options, select Add Item To Module. The Module actions panel displays.

    module_actions_add_items_to_module.png
  9. In the Select a module dropdown, select the module you want to send the item to. In our case, it's the Request Coordination module.

    module_actions_where_to_send.png
  10. Using the matched entity fields you mapped earlier in the process, enter a Title and Description for the item, ensuring the Title is a unique value to each item.

    module_actions_email_title___desc.png
  11. Lastly, we must pass in values for the two custom fields we created in the core module, Request and Requestor.

    In the Custom Fields section, select the Field Name dropdown and choose the first custom field. In our case, we choose Requestor.

    Then, in the Value field, select the insert field button, insert_field.png, and choose the relevant matched entity field to pass in the value for the Requestor.

    module_actions_email_custom_field_requestor.png
  12. To add the value for the second custom field, select + Add field to update. Then, follow the same process described in step #10 for the second value. When finished, you should have values for each custom field in your target module. In our case, we pass in values for Requestor and Request:

    module_actions_email_custom_fields.png

Your first intake module is ready to start sending items to the target module!

Build the Slack Request Module

The other way we want process contributors to submit a request is through Slack, so we build the Slack Request module and configure it to send the necessary information to our target Request Coordination module.

  1. Create a Slack data source where process contributors can submit requests through a Slack channel.

    Make sure you connect Slack as a data source, not a communication tool.

  2. Add a new module to your solution for the Slack intake.

  3. Set the Input Source to your newly-created Slack App data source:

    1. Select the Item tile in the top left corner of the module builder screen. The Item Details panel displays.

      slack_req_item_tile_select.png
    2. Select the External Data Source intake data source. Available data sources display.

      slack_req_ext_data_source.png
    3. Select the desired Slack App data source. The connection configuration screen displays.

      slack_req_slack_data_source_select.png
    4. Select the Messages entity to collect. The entity conditions group displays.

      slack_req_message_entity_select.png
    5. You can set a configure a custom conditions groups to filter only messages that contain certain keywords, but since we're leveraging a training set to listen for "NDA" and "offer" phrases and handling them accordingly in our core module, we choose to not add a condition and collect all messages. When finished, select Save.

      For Slack intake sources, we recommend setting up a condition to specify the Channel_ID, ensuring you only collect messages from a specific channel.

      slack_req_conditions_group.png
  4. In the module builder, select the Fields button, scroll down to the Matched Entities section, and select + Add Field to map the relevant matched entity fields from the intake source you want to use in the intake module and the target module. For our use case, we mapped fields for the channel name, the message text, and the user ID.

    If you want a human-readable field in place of the user ID, you can create a matched entity between the user ID and the username in Slack.

    slack_matched_entity_fields.png
  5. Next, we need to add logic to send the module item to our Request Coordination module when we receive a new Slack message. Select the add block button, add_block.png. The Action Block panel displays. Select the Module actions action. The Module actions options display.

    slack_add_module_actions_block.png
  6. In the Module actions options, select Add Item To Module. The Module actions panel displays.

    module_actions_add_items_to_module.png
  7. In the Select a module dropdown, select the module you want to send the item to. In our case, it's the Request Coordination module.

    module_actions_where_to_send.png
  8. Using the matched entity fields you mapped earlier in the process, enter a Title and, if desired, a Description for the item, ensuring the Title is a unique value to each item.

    slack_module_actions_title.png
  9. Lastly, we must pass in values for the two custom fields we created in the core module, Request and Requestor.

    In the Custom Fields section, select the Field Name dropdown and choose the first custom field. In our case, we choose Requestor.

    Then, in the Value field, select the insert field button, insert_field.png, and choose the relevant matched entity field to pass in the value for the Requestor.

    slack_module_actions_requestor.png
  10. To add the value for the second custom field, select + Add field to update. Then, follow the same process described in step #10 for the second value. When finished, you should have values for each custom field in your target module. In our case, we pass in values for Requestor and Request:

    slack_module_actions_custom_fields.png

Your second intake module is ready to start sending items to the target module!

Test the Solution

Now that you've created the various modules you built to work together, you can test the workflow. For our example use case, we can send an email to our email inbox or send a message in our connected Slack channel. Since both intake modules are nearly identical, we send a test email:Test a Solution

  1. Compose an email using one or more keywords your target module is looking for. In our case, we have a training set listening for mentions of an "NDA" or "offer" letter.

  2. Navigate to the Email Intake module and select Test in the upper right. The Test {Module Name} window displays.

    email_request_test_select.png
  3. Select the Create test item dropdown and select the test email you sent.

    email_test_select_email.png
  4. Select Test Now. The test runs and the Module Events History screen displays.

  5. Confirm the new flow run displays the email inbox item. Our module successfully received the test email and has processed it using the Module actions action, passing it off to the Request Coordination module.

    email_test_module_history.png
  6. Close the Module Events History screen and navigate to the Request Coordination module.

  7. Select History in the upper right. The Module Events History screen displays.

    request_coordination_history_select.png
  8. Confirm the item was successfully added to the target module and your module workflow ran as expected. In our module history, we can see the Email Request module passed the item to our Request Coordination module, which successfully triaged the request and created a new Zendesk ticket.

    request_coordination_history_success.png
  9. With the tests of both the sending and target modules successful, we're ready to publish the solution.

    Our request coordination workflow is now ready to start serving our process contributors!

Learn More

There are many ways to build request coordination modules like the one we built in this walkthrough. We recommend iterating and experimenting to find the best way to orchestrate your unique process.

As you do, check out these related topics that cover some features we leveraged above and some additional content on module orchestration and best practices for building complex workflows: