Notifications in Jitterbit App Builder

A Notification is an application level concept which enables a developer to send a notification or message to a User. This message may have multiple options which define how the User can respond to the message. When options are present in a Notification, the User's response is automatically tracked by App Builder. Notifications support file attachments of any file type (e.g., .PDF, .DOCX, .TXT, .XLSX, etc.). If you are using file attachments, Notification will use the data/pdf directory if no other directory is specified. Alternatively if you do specify a FileDataSourceId, this is the location App Builder will look for the attachment(s).

To use the public data objects required for Notification your application requires App Builder (Sealed) to be configured as an available Data Source for the app. As well as being an available Data Source for the application, you need to establish or configure a link between the Data Sources.

In terms of what URL is used for sending Notifications, App Builder will use URL information specified in the Notification Rule, if it is available. If not found, App Builder will fall back and use the Server Site default URL. The Server Site default value is configured from the IDE > Security Providers > More (from the Configuration panel) > Sites. For more information on sites and URL see the Sites and aliases article.

Message types

A Notification can use one of the following message types:

• Email - Not surprisingly, an email.
• SMS - An SMS message sent and received by the Twilio service.
• App Builder Alert - A popup which shows up in the User's browser when they are logged into App Builder. Formerly called a Notification.

All message types support adding options which provide ways to for the User to respond to a message. For Emails and App Builder Alerts, URLs are included in the message that link back to App Builder. In the case of the SMS delivery type, you can also reply to an SMS with the name of the option to run the associated event.

Future releases of App Builder will likely support sending messages to REST servers.

Options

Notifications can have 0 or more options. When a Notification contains no options, there is no expected User response and consequently, no tracking of the User's response is provided. No links will be added to the outgoing message. This is considered an Informational notification.

When a Notification contains 1 or more options, a message is sent with URL links back into App Builder that allow the User to respond in some way. The User's response to the message (i.e. which option they selected) is tracked by the notification.

Configuration

Notification options can be configured in two ways:

1. Link to page - A link is provided which allows the User to navigate to a page. Successfully navigating to the page is considering a complete response to the option.
2. Run page event - A link is provided which sends the User to a page and runs a specified event before the page is rendered. Again, the User's response is considered complete once the event is triggered.

For a page to be eligible for either option above, the page must be marked as Shared.

As an example, an Administrator may execute an event that causes an email to be sent to an end User. The email has some text and three buttons in it:

1. Review - Clicking Review can bring the User to a specific page in App Builder.
2. Approve - Clicking Approve can bring the User to a different page AND execute an event against some data objects in the page.
3. Reject - Clicking Reject can bring the User to a different page AND execute an event against the same page or a different pages's data objects.

The event must be executed before the page is rendered as it may affect data that is contained in the panels on the page. To execute an event, the developer must:

• Configure the Link To page as Shared.
• Include the event in either the Data Object for the page or as one of the single row panel data sources on the page. Further illustration of this point is available in the Data Object Event Binding section below.

Data object event binding

App Builder limits the events that can be bound to a link. Specifically this limitation only allows for events that belong to a Data Object / Table that is bound to an unbound single row panel on the target page. For example, let's consider a page that has 6 single row panels:

• Customer -> CustomerAddress -> CustomerMap
• Employee -> EmployeeAddress -> EmployeeMap

In this example, Customer and Employee panels are not bound to any other panels on the page. Therefore, a developer can choose events from those two panels data sources (along with a page data object if one is specified).

App Builder also limits the events that can be bound to non-system events. For example, the developer can not link back to the Save, Insert, Update or Delete events.

Notification registration

Linking to a notification

The Notification Registration page in App Builder allows the developer to link a Notification to an application. This is a 1 to 1 relationship. Additional information about the notification message can be configured within the notification registration.

Message creation

The notification message can be defined in the Template section of the Notification Registration page. This is the main content of the notification itself.

Substitutions are performed on the Template and use the {{fieldname}} syntax. Substitutions may add an optional url flag to indicate the value is an url and requires url-encoding e.g. {{fieldname|url}}.

In regards to substitution, the body may contain:

Hello {{CustomerName}},

In which case CustomerName must be contained in the notification rule's columns along with the other required fields.

For emails, a Subject can be specified in the Notification Registration page. The Subject field also supports substitutions.

Translations

Notifications support rudimentary translations. There are three fields which are used for translations:

1. Notification Option Name
2. Notification Registration Message
3. Notification Registration Subject (for Emails)

When creating the notification message, App Builder will attempt to find translations for each of these fields, assuming that their content specifies the corresponding translation key. The developer also needs to add the keys to the translation bundle for the app manually (they are currently not imported automatically for an app). Care must be taken with the Template field to add the translation key as a raw string and not as HTML. There is a "code" icon at the bottom right of the Notification Registration Template field which allows you to directly edit the string.

Limitations

1. The event executed in the option link belongs to the Page Data or a Single Row Panel Data Object. Currently, we do not display any validation results or post messages for page level events. In other words, the event runs first, when it completes, the User is redirected to their page. By the time they arrive at their page, the event results are lost. Therefore, if the event has a post message or fails validation, the system will not show those results to the end User. The developer can easily workaround this by displaying data in their panels that changes based on the successful execution of an event.

   Because of the above limitation, validation warnings will cause an event to not execute. We do not have a UI in place that allows for the User to accept or reject the warning.

2. The File table from an Amazon S3 data source cannot be pulled in by a Notification rule.

Notification public data objects

The public data objects used as Notification targets are defined below.

Common columns

These columns are common across the Notification public data objects:

Email

The Email public data object is similar but not entirely consistent with the SMTP Email Plugin functionality. The columns for the Email public data object are as follows:

Text message

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

App Builder alert

The notification App Builder Alert public data object is similar but not entirely consistent with the Create_Notification public data object. The columns of the App Builder Alert public data object are as follows:

Push notification

The Push Notification public data object allows the notification to send a push notification to a User. The columns of the Push Notification public data object are as follows:

Notification setup

Example notification setup

Steps to setting up a notification. We'll assume that we're adding a Customer Approval Notification to the Northwinds Customers page.

Create notification

Create a rule that targets a notification public data object.

Steps to create notification

• Navigate to App Workbench
• Click Notifications
• Click + Notification
• Assign a Name. For example CustomersRequestApprovalAlert
• Confirm Purpose is Notification
• Select App Builder Alert as the Target. If you do not see this data object available, create a Data Source connection to App Builder (Sealed) for the app you're working in.
• Click Save

Define notification mvSQL

• Click the +Tables button
• Add your 'select from' Table. For example Customers
• Add the following columns and click on the Columns tab to define:

Define notification options

• Navigate to App Workbench
• Click Notifications
• Select the Notification Business Rule. For example: CustomerRequestApprovalAlert
• Enter the Message information for the Notification into the Body field
  • For example: Please review the following customer:
  • Customer: {{CustomerName}}
• Click the pencil icon and enter any Technical Help to help explain the Notification to other developers

Optionally define a landing page and prelaunch event to run

• From the App Workbench > Notfications page, select the Notification
• Click the + Option button
• Create a new option.
  • Set Index to 10
  • Set Name to Review
  • Select the Link to Page value. 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 "Shared" in Edge Case Settings.
• Click the checkmark to save the record

Register notification with an event

Register Notification as an Action with an Event. In this case, we're assuming the Event is associated with a button on the launching page. We'll also assume the event is called 'Request Approval'.

• Navigate to the Event for the Data Object
• Click the Business Logic icon
• Click the Events button
• Select the Event. For example: Request Approval
• Click on Register Existing from the Actions panel
• Select Notification as the Action Type
• Select the Notification we created in the previous step. For example: CustomerRequestApprovalAlert
• Click Save
• Verify that the Explicit Bindings are correct. For example: CustomerId - CustomerId

Test it!

At this point, the Notification is completely set up. Navigate to your page, and click the button that runs the notification event. All App Builder users on the system should see a pop up with the notification message.

SMS notification setup

Steps to setting up an SMS notification. We'll assume that we're adding a Customer Approval Notification to the Northwinds Customers page.

You will need access to a Twilio account to complete setup.

Setup App Builder security

• Navigate to IDE > Security Providers
• Click + User Authentication on User Authentication panel.
  • Enter a Name (e.g. "Http Basic Auth")
  • Select "HTTP Basic Authentication" as the Type
  • Click "Enabled" to enable
  • Click Save
• Navigate to IDE > User Management
  • Double click the User record you want to authenticate as when a SMS reply comes in
  • Note that this User must have access to the following:
    • App Builder application
    • The Event that will be executed on the notification itself
• Click the Keys icon from Authentication
• Click Create
• Select the "Http Basic Auth" provider created earlier
• Click Save

Setup Twilio

Create messaging service

• Log into your Twilio account
• Navigate to Communications Cloud > Programmable SMS
• Click Messaging Services
• Create a new Messaging Service (Notifications, 2-way) and attach a Twilio phone number to it
• Note down the MessagingServiceSid. This will be used for configuration later on
• Enable the "Process Inbound Message" option
• Enter the following Request URL:
  • https://<username>:<secret_key>@<your_vinyl_server>/webhook/v1/vinyl/bridge_inbound
  • E.g. https://admin:P124asfgOmkA@vinyl.zudy.com/webhook/v1/vinyl/bridge_inbound

Gather Twilio credentials

• Navigate to Console Dashboard > Settings
• Note down the LIVE credentials:
  • Account Sid
  • Auth Token

Configure SMS endpoint

• Navigate to IDE > Notification Servers
• Double click the 'SMS' record
• Add the following configuration:
  • User Name -> Twilio Account Sid
  • Password -> Twilio Auth Token
  • MessagingServiceSid -> Twilio Messaging Service Sid

Configure website URL

• Navigate to IDE > Security Providers
• Under Configuration click More > Sites
• Click + Site
• Set the URL value to your website URL. For example: https://vinyl.zudy.com
• Click Save

Configure SMS notification

Create notification

Create a rule that targets a notification public data object.

Steps to create notification

• Navigate to App Workbench > Notifications
• Click + Notification
• Assign a Name
• Select Notification as the Purpose
• Select Text Message as the Target. If you do not see this data object available, create a Data Source connection to App Builder (Sealed) for the app you're working in.
• Click Save

Define notification mvSQL

• Click the +Table button and add the Table the Rule requires

  • E.g. Customers

• Click the Columns tab and add the following columns:

Define notification options

In addition to defining the Message information, we will define two options for this Notification example. One which is activated by replying to the SMS, another which is a link to a page.

• Click the Notification navigation tab
• Enter the following message into the Message Body:

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

• Click the +Option button from the Options panel
  • Set Index to 10
  • Set Name to Review
  • 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 "Shared" in Edge Case Settings.
  • Set the Option Type to 'Link'
• Click the +Option button from the Options panel
  • Set Index to 20
  • Set Name to 1
  • Select the page to link to. In our example we'll link to the Northwinds 'Customer' page and run the 'Approve' event.
  • Set the Option Type to 'SMS Reply'

Register notification with an event

Register Notification as an Action with an Event. In this case, we're assuming the Event is associated with a button on the launching page. We'll also assume the event is called 'Request Approval'.

• Navigate to the Event for the data object
• Click the Business Logic icon
• Click the Events button
• Select the Event. For example: Request Approval
• Click on Register Existing from the Actions panel
• Select Notification as the Action Type
• Select the Notification we created in the previous step. For example: Customer_RequestApprovalSms
• Click Save
• Verify that the Explicit Bindings are correct. For example: E.g. CustomerId - CustomerId

Configure push notification

Push notifications are configured similarly to other notifications in App Builder. The App Builder server Administrator must configure the Push Notification endpoint correctly in order for them to work as expected.

If you are configuring Push Notifications with Blabber API, you must download the iOS companion app, sign into the corresponding server with proper credentials, and enable push notifications on the app itself. In addition, an API key is required to complete the configuration.

Test it!

At this point, the Notification is completely set up. Navigate to your page, and click the button that runs the notification event.