Notifications in Jitterbit App Builder

Overview

Notifications are messages that App Builder sends to your application's users when an event occurs, such as a button click or a scheduled check. A notification can be delivered as an email, a text message, an in-app alert, or a push notification, and can optionally let the recipient respond by navigating to a page or triggering an event.

This page describes the three steps necessary to set up notifications in your applications:

1. Set up a notification server
   Configure the server used to deliver notifications.

2. Create a notification
   Define the message content and the object used to send it.

3. Add response options
   Optionally, let the recipients respond by navigating to a page or triggering an event.

This page also includes full walkthroughs of the entire process, with two examples: an in-app notification and an SMS message.

For messages sent by administrators to multiple users at once, rather than triggered by an application event, see System notifications.

Step 1: Set up a notification server

Before you can send a notification, you must configure at least one notification server for the delivery method you plan to use. App Builder supports the following delivery methods:

• Email, sent through an SMTP server.

• SMS (text message), sent through Twilio.

• In-app (App Builder alert), a popup shown to the recipient while they're logged in to the app.

• Push, sent through Jitterbit Blabber, for apps using the Jitterbit Wrapper or a branded wrapper, or through OneSignal, for native mobile apps using your own OneSignal account.

To view and manage notification servers, select IDE > Notification Servers:

The list of servers is made of the following columns:

• Name: The server's name.

• Type: The type of notification that can be set up with that server.

• Description: A brief description.

• URI: The URI (if applicable).

• Status: The server's current status.

Double click any row or click the icon at the end to see and edit details of a given server. Every server except In-app requires setup before use:

• SMTP (Email) requires the from address, URI, and Security sections to be populated.
• Blabber, OneSignal, and SMS require the Security section to be populated.

Step 2: Create a notification

Creating a notification means creating a business rule with its Purpose set to Notification, from the App Workbench's Notifications tab. The rule defines the notification's message content and selects the public data object (Delivery Method) used to send it, such as Email, Text Message, App Builder Alert, or Push Notification.

To create a notification:

1. Navigate to App Workbench > Notifications.
2. Click + Notification.
3. Assign it a Name.
4. Confirm Purpose is Notification.
5. Select the Delivery Method you want to use. Each delivery method sends a notification through a specific public data object, which determines the notification's details. If the data object you need isn't available, you may need to create a data source connection to App Builder (Sealed) for the app you're working in.
6. Click Create.

Clicking Create opens the Rule Builder in edit mode, where you define the columns the notification uses, the same way you would when editing any other business rule. For the columns available to each delivery method, see Public data objects by delivery method below.

Public data objects by delivery method

Each delivery method sends a notification through a specific public data object — a predefined set of columns that determines details like the recipient, sender, and delivery behavior. The Delivery Method you select when you create a notification determines which public data object your notification's columns must map to, in the Rule Builder's mvSQL definition.

The following sections describe the columns available for each public data object, plus the columns common to all of them.

Common columns

These columns are common to every public data object described below:

Email

The columns for the Email public data object are as follows:

Notifications sent by email can include file attachments of many file types, such as .pdf, .docx, .txt, or .xlsx, using the Attachment() and FileDataSourceId columns described below. App Builder attaches files from the data/pdf directory by default, or from the directory specified by FileDataSourceId.

If the notification contains options, the AppBuilderUrl column specifies the URL used when generating links to those options. If AppBuilderUrl is not provided, App Builder falls back to the server site's default URL, configured from IDE > Security Providers > More (from the Configuration panel) > Sites. For more information, see Sites and aliases.

Text Message

The Text Message public data object is used for sending SMS messages. The columns for the Text Message public data object are as follows:

App Builder Alert

The columns of the App Builder Alert public data object are as follows. This object is similar, but not identical, to the Notification_Create public data object.

Push Notification

The Push Notification public data object sends a push notification to a user. The columns of the Push Notification public data object are as follows:

Write the notification message

To write the notification's message, click the Notifications tab again and select your notification from the Notification Rules panel. Enter the message in the Body field of the Message panel; this field is mandatory, and the notification event fails with an error if it's left empty.

The message supports substitutions using the syntax {{fieldname}}, which App Builder replaces with the corresponding column value when the notification is sent. For example, the body may contain:

Hello {{CustomerName}},

In this example, CustomerName must be contained in the notification rule's columns along with the other required fields. Substitutions may add an optional url flag to indicate the value is a URL and requires url-encoding, e.g. {{fieldname|url}}. An optional HTML flag treats HTML markup in the value as plain text, e.g. {{fieldname|HTML}} substitutes a value of <b>Jitterbit</b> as Jitterbit.

For most messages, editing the plain-text Body field is enough. If you need custom formatting beyond plain text, click More > Edit HTML to edit the message's underlying HTML directly.

For emails, a Subject must also be specified, which also supports substitutions; like the Body field, leaving it empty causes the notification event to fail with an error.

Translations

If your application supports multiple languages, you can also translate a notification. Three fields support this: the notification's Body, its Subject (for emails), and the Name of each response option. Instead of entering literal text in these fields, enter a translation key; App Builder looks up the value for the recipient's language in the app's translation bundle when the notification is sent.

You must manually add these translation keys to the app's translation bundle; App Builder does not import them automatically.

If you edit the message using More > Edit HTML, add the translation key as a plain string rather than as HTML, or the lookup will fail.

For more information on setting up languages and translation bundles, see Translations.

Step 3: Add response options

A notification can optionally include one or more response options that let the recipient reply. A notification with no options is purely informational: App Builder doesn't track a response, and no links are added to the message.

When a notification has one or more options, App Builder tracks the recipient's response automatically. For emails and App Builder alerts, each option is a clickable link back into App Builder. For SMS, the recipient replies with the option's Name to select it.

Notification links expire after 7 days and cannot be configured to last longer.

To add a response option to a notification:

1. In the notification's Options panel, click the + Option button.
2. Set Index to determine the option's order relative to other options.
3. Set Name to identify the option. For an SMS Reply option, this is also the text the recipient must reply with.
4. Set Option Type to Link or SMS Reply.
5. For a Link option, select the page to link to in Link To Page. The page must be marked as Public in its Edge Case settings.
6. Click Save.

Navigating to the page selected in Link To Page completes the response for a Link option. If that page also has a business-logic event bound to it, the event runs before the page renders, and completing the response then also depends on that event running successfully. See Data object event binding below for the restrictions that apply to that event.

Data object event binding

When the page linked in a response option's Link To Page field also has a business-logic event bound to it, that event must belong to either the page's first panel (the panel with the lowest index, in the top-left position) or the page's own public data object, if one is defined. Events that belong to any other panel on the page cannot be bound to a response option.

For example, consider a stacked page with two side-by-side groups: the first, at index 10, contains the Customer and CustomerAddress panels, and the second, at index 20, contains the Employee and EmployeeAddress panels:

Customer is the page's first panel, so its events are eligible. CustomerAddress, Employee, and EmployeeAddress are not eligible, since none of them is the page's first panel.

App Builder also only allows binding to custom events, not to system events. For example, you cannot bind to the Save, Insert, Update, or Delete events.

When the bound event completes, App Builder redirects the recipient to the page, but any post message or validation result from the event is lost by then, since App Builder doesn't display those to the recipient for page-level events. You can work around this by displaying data in the page's panels that changes based on whether the event ran successfully. For the same reason, a validation warning simply prevents the event from running, because there are no mechanisms for the recipient to accept or reject it.

At this point, you have everything you need to build a notification: a server to deliver it, a rule that defines its message and data, and, optionally, one or more response options.

Full walkthroughs

The following examples walk through the entire process of creating a notification, from setting up a delivery method to adding a response option. The first example uses App Builder Alert as the delivery method; the second uses Text Message (SMS).

Example notification setup

This example adds a customer approval notification to the Customers page of a hypothetical application called Northwinds, using App Builder Alert as the delivery method.

1. Create the notification and set its delivery method:

   1. Navigate to App Workbench.
   2. Click Notifications.
   3. Click + Notification.
   4. Assign it a Name. For example: CustomersRequestApprovalAlert.
   5. Confirm Purpose is Notification.

   6. Select App Builder Alert as the Delivery Method.

      Note

      If you don't see this data object available, create a data source connection to App Builder (Sealed) for the app you're working in.

   7. Click Create.

2. Define the notification's mvSQL, mapping the Customers table to the columns the App Builder Alert object needs:

   1. Click the +Tables button.
   2. Add your Select From table, which in this case is Customers.

   3. Add the following columns and click on the Columns tab to define:

      Column	Alias	Target
      'all'	To	To
      "C".CustomerId	CustomerId	Binding()
      "C".CustomerName	CustomerName

      Note

      CustomerName is added here so it can be used later as a substitution parameter in the notification message.

3. Write the notification's message:

   1. Navigate to App Workbench.
   2. Click Notifications.
   3. Select the notification you created in step 1, which in our example is CustomerRequestApprovalAlert.

   4. Enter the message in the Body field, for example:

      Please review the following customer:
      Customer: {{CustomerName}}

   5. Click the icon and enter any Technical Help to help explain the notification to other developers.

4. (Optional) Add a response option that links to a page:

   1. From the App Workbench > Notifications page, select the notification.
   2. Click the + Option button.
   3. Create a new option:
      1. Set Index to 10.
      2. Set Name to Review.
      3. Select the Link To Page value. In this example, link to the Customers page. If the page you want to link to doesn't show up, ensure that it's been marked as Public in its Edge Case settings.
      4. Click Save.

5. This example assumes the Customers page is already marked Public, with an event named Request Approval defined on its first panel. Bind that event to the option's link, so it runs when the recipient follows it:

   1. Navigate to the event for the data object.
   2. Click the Business Logic icon.
   3. Click the Events button.
   4. Select the event. For example: Request Approval.
   5. Click on Register Existing from the Actions panel.
   6. Select Notification as the Action Type.
   7. Select the notification we created in the previous step. For example: CustomerRequestApprovalAlert.
   8. Click Save.
   9. Verify that the Explicit Bindings are correct. For example: CustomerId - CustomerId.

6. Test the notification. Navigate to your page and click the button that runs the notification event. All logged-in App Builder users should see a popup with the notification message.

Example SMS notification setup

This example adds the same customer approval notification to the same Customers page, using Text Message (SMS) as the delivery method.

1. Set up App Builder security, so App Builder can authenticate incoming SMS replies from Twilio:

   1. Navigate to IDE > Security Providers.
   2. Click + User Authentication on the User Authentication panel.
      1. Enter a Name (e.g. Http Basic Auth).
      2. Select HTTP Basic Authentication as the Type.
      3. Click Enabled to enable.
      4. Click Save.

   3. Navigate to IDE > User Management.

      1. In the Users panel, locate the user you want to authenticate as when an SMS reply comes in. Double click the user's row or click the icon at the end of it. The User dialog opens.

         Note

         This user must have access to the App Builder application, and to the event that will be executed on the notification itself.

      2. Click More > Keys. The Keys dialog opens.

      3. Click Create. The Generate Key dialog opens.
      4. Select the Http Basic Auth provider created earlier.
      5. Click Save.

   Note

   This provider creates a secret Key. The combination of the User Name and secret Key will be used when configuring Twilio.

2. Set up Twilio to send and receive the SMS messages:

   1. Create a messaging service:

      1. Log into your Twilio account.
      2. Navigate to Communications Cloud > Programmable SMS.
      3. Click Messaging Services.
      4. Create a new Messaging Service (Notifications, 2-way) and attach a Twilio phone number to it.
      5. Note down the MessagingServiceSid. This will be used for configuration later on.
      6. Enable the Process Inbound Message option.
      7. Enter the following Request URL, replacing <username>, <secret_key>, and <your_AppBuilder_Server> with your values: https://<username>:<secret_key>@<your_AppBuilder_Server>/webhook/v1/vinyl/bridge_inbound

   2. Gather Twilio credentials:

      1. Navigate to Console Dashboard > Settings.
      2. Note down the following live credentials:
         • Account Sid
         • Auth Token

3. Connect App Builder to Twilio, using the credentials gathered in the previous step:

   1. Navigate to IDE > Notification Servers.
   2. Double click the SMS row.
   3. Add the following configuration:
      • User Name: Enter your Twilio Account Sid.
      • Password: Enter your Twilio Auth Token.
      • MessagingServiceSid: Enter your Twilio MessagingServiceSid.

4. Set the website URL App Builder uses when generating links in the SMS message:

   1. Navigate to IDE > Security Providers.
   2. Under Configuration, click More > Sites.
   3. Click + Site.
   4. Set the URL value to your website URL. For example: https://vinyl.jitterbit.com.
   5. Click Save.

5. Now, create and configure the SMS notification itself, following the same overall process as the previous example, but this time, instead of App Builder Alert, select Text Message as the Delivery Method:

   1. Create the notification and set its delivery method:

      1. Navigate to App Workbench > Notifications.
      2. Click + Notification.
      3. Assign it a Name.
      4. Select Notification as the Purpose.

      5. Select Text Message as the Delivery Method.

         Note

         If you don't see this data object available, create a data source connection to App Builder (Sealed) for the app you're working in.

      6. Click Create.

   2. Define the notification's mvSQL, mapping the phone number and customer columns to the Text Message object:

      1. Click the +Table button and add the table the rule requires. E.g. Customers.

      2. Click the Columns tab and add the following columns:

         Column	Alias	Target
         '+15551112222' (replace with your phone number)	To()	To()
         "C".CustomerId	CustomerId	Binding()
         "C".CustomerName	CustomerName

         Note

         CustomerName is added here so it can be used later as a substitution parameter in the notification message.

   3. Write the message and add two response options: one the recipient can reply to by SMS, and one that links to a page:

      1. Click the Notifications tab.

      2. Enter the following message into the Body field:

         Reply {{1}} to approve {{CustomerName}}. Review {{Review}}
         

      3. Click the + Option button from the Options panel:

         1. Set Index to 10.
         2. Set Name to Review.
         3. Select the page to link to. In our example we'll link to the Northwinds Customer page. If the page you want to link to doesn't show up, ensure that it's been marked as Public in its Edge Case settings.
         4. Set the Option Type to Link.
         5. Click Save.

      4. Click the + Option button from the Options panel:

         1. Set Index to 20.
         2. Set Name to 1.
         3. Select the page to link to. In our example we'll link to the Northwinds Customer page and run the Approve event.
         4. Set the Option Type to SMS Reply.
         5. Click Save.

   4. This example assumes the Customers page is already marked Public, with an event named Request Approval defined on its first panel. Bind that event to the Link option, so it runs when the recipient follows it:

      1. Navigate to the event for the data object.
      2. Click the Business Logic icon.
      3. Click the Events button.
      4. Select the event. For example: Request Approval.
      5. Click on Register Existing from the Actions panel.
      6. Select Notification as the Action Type.
      7. Select the notification we created in the previous step. For example: Customer_RequestApprovalSms.
      8. Click Save.
      9. Verify that the Explicit Bindings are correct. For example: CustomerId - CustomerId.

   5. Test the notification. Navigate to your page and click the button that runs the notification event.

System notifications

Unlike the notifications described earlier on this page, which App Builder sends automatically to a specific recipient when a business event occurs, system notifications are broadcast messages that an administrator sends manually, or schedules to send later, to a group of users at once, for example, everyone with access to an application, or a specific security group or role. Administrators use system notifications for things like planned maintenance windows or application upgrades, which don't need to be tied to a specific record or triggered by an event.

System notifications are shown to active users, and remain in their Notification Center (under the hamburger menu) until dismissed or expired. System notifications are part of the Maintenance feature and only support in-app alerts. They are also environment-specific: unlike application notifications, which promote with your code between environments, a system notification must be re-created in each environment.

To set up a system notification, select IDE > Maintenance, then select the Notifications tab (available since App Builder 4.44), and follow these steps:

1. In the Scheduled Notifications panel, click the Schedule or Send Now button.

2. In the Notification dialog, enter values for the following fields:

   • To: Click the field, then select one of the following:

     • All

     • A group of users based on the following:

       • Their access to an application or data source granted by their groups or roles.

       • Security groups.

       • The data source's roles.

   • From: Defines who sent the notification (usually the service user).

   • Schedule For: (Optional) Schedule a notification to be sent later (for example, an hour before a planned application upgrade).

   • Expires On: A date/time when the notification expires and will no longer be shown to users. At this time, users who have seen and dismissed the message have the notification removed from their notification centers.

   • Body: The content of the message shown to users.

3. Click the Send or Schedule button.

A background service sends scheduled notifications. By default, the service is run by the Service User account. To change which user runs the service, follow these steps:

1. Select IDE > Maintenance, then select the Settings tab.

2. Click the Background Notification User menu, then select the user to run the service.