Use Case: Server-Side Module Execution

Overview

This use case will help you better understand how to build Server-Side Execution Modules. In this example, you'll build a front-end module where you can craft an email message and choose where it's sent. That module will call a server-side API module that will actually send the email.

This use case uses 2 modules:

Name Description

Front-End Module

The front-end module includes fields where you can enter data concerning the email you'll send. There is also a Button component that triggers the Execute Remote Plug-In.

Send Email API Module

The front-end module includes fields where you can enter data concerning the email you'll send. There is also a Button component that triggers the Execute Remote Plug-In.

What You’ll Learn

In this article, you’ll learn how to:

  • Configure the Front-End Module.

  • Configure the Send Email API Module.

What You'll Need

To build out the Front-End Module, you'll need:

  • 1 Panel component

  • 1 Text Field component

  • 1 Text Area component

  • 1 Plug-In component

  • 1 Button component

  • 1 Hidden component

And to build out the Email API Module, you'll need:

  • 1 API Specification Snippet

  • 2 Initializer components

  • 1 Plug-In component

  • 3 Hidden components

Configuring the Front-End Module

The front-end module is where you'll remotely execute the API (application programming interface) module. This module is also where the end-user will enter the email information.

These instructions assume you have a new module saved with a name.

Configure the Panel Component

1. In the Module Builder, drag and drop a Panel component onto your canvas.
2. Enter panelExecuteModule in the Property ID.
3. Click Save.

Configure the Text Field Component

This is the field where your end-user will enter the recipient's email address.

1. Drag and drop a Text Field component onto your canvas, placing it inside panelExecuteModule.
2. Enter emailAddress in the Property ID.
3. Enter Email Address in the Label Text.
4. Click Save.

Configure the Text Area Component

In this Text Area, the end-user will enter the email message.

1. Drag and drop a Text Area component onto your canvas, placing it inside the panelExecuteModule, under the emailAddress Text Field.
2. Enter emailMessage in the Property ID.
3. Enter Email Message in the Label Text.
4. Click Save.

Configure the Plug-In Component

This is the Execute Remote Plug-In component. This Plug-In executes the server-side API module.

1. Drag and drop a Plug-In component onto your canvas. Place your Plug-In inside the panelExecuteModule Panel under the emailMessage Text Area.
2. Enter pluginRemoteExecuteSendEmail in the Property ID and Label Text.
3. In the Inputs table, enter the following:

Property ID

Mapping

emailAddress

data.emailAddress

emailMessage

data.emailMessage
4. In the Outputs table, enter the following:
a. Property ID: enter responseAPIError.
b. Mapping: enter data.resolved.responseError.
5. Select Execute Module from the Internal Services drop-down.
6. In the Data Source URL field, you'll see {moduleId}. You'll replace moduleID with the actual module ID of the Send Email API module.

This ID isn't available until you've created the Send Email API module. You'll return to this step once you have access to the module ID.

7. Click Save.

Configure the Button Component

This Button component is what triggers the Execute Module Plug-In.

1. Drag and drop a Button component onto your canvas, placing it inside the panelExecuteModule, below the Plug-In.
2. Enter btnExecuteEmailAPI in the Property ID.
3. Enter Execute Send Email API in the Label Text.
4. Select Event as the Button Action Type.
5. Enter pluginRemoteExecuteSendEmail in the Trigger on Click.
6. Click Save.

Configure the Hidden Component

This Hidden component houses the error response if the back-end API call fails.

1. Drag and drop a Hidden component onto your canvas, placing it inside the panelExecuteModule, below the Button.
2. Enter responseApiError as the Property ID and Label Text.
3. Click Save.

Configuring the Send Email API Module

This module is the star of the show. This is the API module that will send the actual email. Luckily, Unqork has an API Specification template that gets us pretty far along in the configuration.

Configure the API Specification Snippet

The API Specification snippet contains text and 3 Panel components to help with API setup. These 3 Panels and text live in a Panel called panelAPITemplate.

To add the API Specification snippet to your module:

1. Click Snippets in the left sidebar of the Module Builder.
2. Enter API Specification in the search bar.
3. Drag and drop the API Specification template onto your canvas.
4. Save your module.

NOTE  The API Specification template comes standard with some HTML text. You can keep or delete the text.

Configure the First Initializer Component

This Initializer component receives the Execute Module call from the front-end module. It then triggers the Plug-In component that you'll set up next.

1. Drag and drop an Initializer component onto your canvas. Place your Initializer inside the panelInfo Panel.
2. Enter initPluginSendEmail in the Property ID and Label Text.
3. Select New Submission from the Trigger Type.
4. In the Outputs table, enter the following:
a. Property ID: enter pluginSendEmail.
b. Type: enter trigger.
c. Value: enter GO.

5. Click Save.

Configure the Plug-In Component

The Plug-In component is what fires the SendGrid API. In the Inputs table, you'll reference the emailAddress and emailMessage Hidden components. These are the Hidden components storing the email data from the Front-End Module.

1. Drag and drop a Plug-In component onto your canvas. Place your Plug-In inside the panelInfo Panel, under initPluginSendEmail.
2. Enter pluginSendEmail in the Property ID and Label Text.
3. Enter initError in the Error Trigger.
4. In the Inputs table, enter the following (feel free to fill in your own email address and subject in those sections):

Property ID

Mapping

emailAddress

personalizations[0].to[0].email

emailMessage

content[0].value

'youremail@email.com'

from.email

'Hello Subject'

subject

'text/html'

content[0].type

5. Select the External choice chip under Service Type.
6. Select SendGrid from the External Services drop-down.
7. Add mail/send to the end of the pre-populated Data Source URL field.
8. Set the Assign values if they are null or empty string toggle to ON.

9. Click Save.

Configure the Second Initializer Component

This Initializer triggers the error message if the SendGrid API fails.

1. Drag and drop an Initializer component onto your canvas. Place your Initializer inside the panelInfo Panel, under pluginSendEmail.
2. Enter initPluginSendEmail in the Property ID and Label Text.
3. In the Outputs table, enter the following:
a. Property ID: enter sendGridResponseError.
b. Type: enter value.
c. Value: enter There was an error sending the sendgrid email.

4. Click Save.

Update the First Hidden Component

You'll use 3 Hidden components in this configuration. The first component houses emailAddress data. Instead of bringing in a new component, just edit the requestParameter Hidden component.

To configure the first Hidden component:

1. Hover over the requestParameter component.

A 5-button toolbar appears above the component on hover-over.

2. Click the (Settings) button to open the Configuration window.
3. Enter emailAddress in the Property ID and Label Text.
4. Click Save.

Configure the Second Hidden Component

Your second Hidden component houses the emailMessage data.

To configure the second Hidden component:

1. Drag and drop a Hidden component onto your canvas. Place your Hidden component inside the panelRequest Panel.
2. Enter emailMessage in the Property ID and Label Text.
3. Click Save.

Update the Third Hidden Component

This Hidden component houses the error response for the API call. When the API call fails, the initError Initializer fires. The Initializer then outputs an error response into this Hidden component.

To configure the third Hidden component:

1. Hover over the responseParametercomponent.

A 5-button toolbar appears above the component on hover-over.

2. Click the (Settings) button to open the Configuration window.
3. Enter sendGridResponseError in the Property ID and Label Text.
4. Click Save.

Updating the Front-End Module

Updating the Plug-In Component

Now, you're ready to return to the pluginRemoteExecuteSendEmail Plug-In component. There you'll change out the moduleID to point to the actual module ID of the Send Email API Module.

1. In the Module Builder hover over the pluginRemoteExecuteSendEmail Plug-In component.

A 5-button toolbar appears above the component on hover-over.

2. Using the toolbar, click the (Settings) button.
3. In the Data Source URL field, you'll see {moduleId}. Replace moduleID with the actual ID of the Send Email API Module.
4. Click Save.

Summary

Now you can view your use case. Your Send Email API module should look something like this now:

You can test your new server-side API by entering your email address and a message in the Front-End Module. On button-press of the Execute Send Email API button, you'll receive an email. If you don't receive the email, check your email's spam folder. If you still don't see an email, you'll move on to more advanced methods of troubleshooting.