Bronto Integration. Version

Transcription

1 Bronto Integration Version

2 Table of Contents 1. Summary Component Overview Functional Overview Use Cases Limitations, Constraints Compatibility Privacy, Payment Implementation Guide Setup Configuration Import the int_bronto cartridge Add int_bronto to the effective path of all sites Install metadata Register with the Bronto Demandware Connector Custom Code Insert pipelets for transactional messages Insert pipelets for opt-in Insert Bronto footer ISML Insert custom application url Insert custom js code External Interfaces Testing Operations, Maintenance Data Storage Availability Support User Guide Roles, Responsibilities Business Manager Storefront Functionality Known Issues Release History Bronto Demandware Integration Page 1-2

3 1. Summary The Bronto Demandware integration provides a rich set of functionality that allows the import of data from Demandware into Bronto, contact opt-in, sending transactional messages through the Bronto Platform, as well as integrations with some of the popular Bronto apps found in the Bronto AppCenter ( This cartridge is a replacement for previous versions of the Bronto Integration cartridge. It is recommended that any existing Bronto Integration cartridges be removed before proceeding to install this version. All settings for this cartridge are configured within Bronto and do not transfer automatically. You may safely remove any configuration settings and metadata from the previous cartridge install. Bronto Demandware Integration Page 1-3

4 2. Component Overview 2.1 Functional Overview Customer import into the Bronto Platform. Order import into the Bronto Platform. opt-in/out with custom fields synchronized to Bronto. Transactional message pipelets for the following messages: - Order Confirmation - Reset Password - Password Changed - Account Locked - Gift Certificate Received - Contact Us - Send-to-friend (Product) - Send-to-friend (Gift Registry) - Send-to-friend (Wish list) - Send-to-friend (Product list) - Custom Transactional message conversion tracking Product recommendations - Sent as API tags during a transactional message send - Imported into a Bronto Content Tag on a regular interval Auto-application of coupon codes Bronto App integrations - Cart Recovery - Coupon Manager - Pop-Up Manager Bronto Demandware Integration Page 1-4

5 2.2 Use Cases Import of contact and order data into Bronto via jobs. Delete order data from Bronto via job. Storefront opt-in with custom fields. Transactional message integration in various storefront pipelines. Auto-apply of coupon codes. Bronto App integrations. 2.3 Limitations, Constraints All transactional messages and opt-ins are queued for asynchronous delivery. In order to provide a responsive storefront, these actions are designed to be processed via the jobs provided by this cartridge. It is recommended that the jobs provided will be run on frequent intervals in order to guarantee the interaction with the Bronto platform is in near real time. WARNING: When running tests in a sandbox/development instance in Demandware where you cannot have recurring job schedules, you will have to manually run the three jobs at the appropriate times for testing purposes. The following is a list of when to run the jobs: Bronto Settings Sync This job should be run anytime settings are modified in the Bronto Demandware Connector. Bronto Process Deliveries This job should be run anytime you run a pipeline that would have a caused a transactional message to be scheduled for delivery (Order confirmation, password reset, contact us, etc.). This will process the queue of deliveries. Bronto Jobs Runner This job should be run anytime you want one of the automated jobs to be run. The jobs that actually run are dependent on the schedule settings defined in the Bronto Demandware Connector. This includes jobs like the Contact Import, Order Import, Opt-In Import, and Content Tag Recommendations import. In addition, this also controls when the Advanced executions get run from the Bronto Demandware Connector. 2.4 Compatibility Available since Demandware and storefront integrations tested against SiteGenesis. 2.5 Privacy, Payment The cartridge uses customer profile and order data and transfers it into the Bronto Platform. All data us transferred over a secure HTTPS connection. Credit card data is transferred for order-based transactional messages. The following credit card information is transferred: Masked credit card number Bronto Demandware Integration Page 1-5

6 Card holder name Credit card type Credit card expiration date Bronto Demandware Integration Page 1-6

7 3. Implementation Guide 3.1 Setup Setup requires the following steps be performed. Details of these steps, including relevant screenshots, are provided under the Configuration and Custom Code section below. 1. Import the int_bronto cartridge into the Demandware Studio and upload to your Demandware Server instance. 2. Add the int_bronto cartridge to the effective path of all sites that require integration with Bronto as well as the Business Manager site. 3. Install the job, object and services metadata from the metadata folder. 4. Register the cartridge from the Business Manager with the Bronto Demandware Connector app for all sites that have the cartridge installed. 5. Insert pipelets for sending transactional messages. 6. Insert pipelets for providing opt-in integration. 7. Insert Bronto footer ISML in storefront footer. 3.2 Configuration Import the int_bronto cartridge In the Demandware UX Studio, select Import Existing Projects into Workspace and find the int_bronto cartridge folder and import the project into your workspace: Bronto Demandware Integration Page 1-7

8 Add the cartridge to your configured Demandware Server Configuration and enable Auto-Upload to verify it is installed on the server instance Add int_bronto to the effective path of all sites In the Demandware Business Manager, go to Administration > Sites > Manage Sites. Select the Manage the Business Manager site option and in the cartridges section, be sure to add int_bronto so that the cartridge is on the effective path for the business manager. Repeat this step for every site you want the cartridge installed on Install metadata Bronto Demandware Integration Page 1-8

9 In the Demandware Business Manager, go to Administration > Site Development > Import & Export. Select Upload under the Import & Export Files section and upload the bronto_metadata.xml file available in the metadata folder of this cartridge. After upload is complete, go to the Meta Data section and select Import. Select the previously uploaded bronto_metadata.xml file and import it. In the Demandware Business Manager, go to Administration > Operations > Import & Export. Select Upload under the Import & Export Files section and upload the bronto_jobs.xml file available in the metadata folder of this cartridge. After upload is complete, go to the Job Schedules section and select Import. Select the previously uploaded bronto_jobs.xml file and import it. In the Demandware Business Manager, go to Administration > Operations > Job Schedules. For each of the three Bronto jobs defined (Bronto Jobs Runner, Bronto Process Deliveries, and Bronto Settings Sync), make sure the jobs are running on a recurring interval at all times. It is recommended that all three jobs run every 1-5 minutes Register with the Bronto Demandware Connector For all users who need to configure the Bronto cartridge, go to Administrator > Organization > Roles & Permissions and select the roles that you want to have access to configure the cartridge. In the role configuration page, select the Business Manager Modules tab. For each site that has the int_bronto cartridge installed, select the site under the Select Context section. Find the Bronto Manage Registration module and check it to enable it for the site. Click Update once you are done. Bronto Demandware Integration Page 1-9

10 Once the sites have the Bronto Business Manager extension available, click on the Bronto section under the site and then select Manage Registration. You will be prompted for a Bronto Demandware Connector Account ID. Provide the ID given to you by Bronto and click Register. NOTE: You will need to disable the Password Protection on the site before registering the cartridge if you have it on. You may turn it back on afterwards, if desired. This is needed in order to establish secure communication with Demandware instance the Bronto Connector application. Returning to this page after having registered this site with Bronto will give you the option to Deregister. WARNING: Deregistering your site will cause all of your settings for the Bronto integration to be lost for that site. Only do this if instructed by a Bronto support or client services representative. 3.3 Custom Code Storefront integrations described below are based on the Demandware SiteGenesis demo. While these are provided as a working example in SiteGenesis, some modifications may need to be done in order for them to function correctly in your modified storefront. It is recommended that you do NOT modify any code in the int_bronto cartridge, as that will make future upgrades difficult. All modifications should be done in your storefront cartridge and only reference portions of the int_bronto cartridge. Please contact Bronto support, client services, or your account manager for additional help. Bronto Demandware Integration Page 1-10

11 3.3.1 Insert pipelets for transactional messages The int_bronto cartridge provides several built-in script node pipelets that may be inserted in various pipelines in order to schedule transactional messages for delivery. These messages are queued in a custom object and sent to Bronto as part of the Bronto Process Deliveries job. It is recommended that this job run on a frequent recurring interval so that the delivery of messages is not delayed significantly. A recommended interval is between 1 and 5 minutes. The following sections describe how to install each of the built-in messages as well as an example of hooking up the custom message. For each of these messages, if there is a corresponding SendMail pipelet in its place, you can attach the error transition of the Bronto message to the old SendMail pipelet and configure the cartridge to use the SendMail pipelet if you desire. This is the recommended approach for all messages. In addition to this, all message script nodes must be declared as Transactional nodes. Order Confirmation In the COPlaceOrder-Start pipeline, there is a SendMail pipelet after COPlaceOrder-CreateGiftCertificates. Add the int_bronto:/scripts/messages/orderconfirmationmessage script pipelet where the Assign and Mail-SecureSend pipelet was hooked in. Select the OrderConfirmationMessage script node and set it to Transactional and provide the Demandware order object for the Order input parameter. Usually, this is simply Order: Bronto Demandware Integration Page 1-11

12 Reset Password In the Account-PasswordResetDialog pipeline, there is a SendMail pipelet after GenerateResetPasswordToken pipelet. Add the int_bronto:/scripts/messages/resetpasswordmessage script pipelet where the Assign and Mail- SecureSend pipelet was hooked in. Configure the message as shown below. Note, this should be placed in a similar location for the Account-PasswordReset pipeline. Password Changed In the Account-SetNewPassword pipeline, there is a SendMail pipelet after ResetCustomerPasswordWithToken pipelet. Add the int_bronto:/scripts/messages/passwordchangedmessage script pipelet where the Assign and Mail-SecureSend pipelet was hooked in. Configure the message as shown below. Account Locked In the Login-Process pipeline, there is an Assign and Mail-SecureSend pipelet after LoginCustomer pipelet and a decision node checking for account locked status. Bronto Demandware Integration Page 1-12

13 Add the int_bronto:/scripts/messages/accountlockedmessage script pipelet where the Assign and Mail- SecureSend pipelet was hooked in. Configure the message as shown below. Gift Certificate Received In the COPlaceOrder-CreateGiftCertificates pipeline, there is a SendMail pipelet after CreateGiftCertificate pipelet. Add the int_bronto:/scripts/messages/giftcertificatemessage script pipelet where the Assign and Mail- SecureSend pipelet was hooked in. Configure the message as shown below. Bronto Demandware Integration Page 1-13

14 Contact Us In the CustomerService-ContactUs pipeline, there is a SendMail pipelet after Assign pipelet after the submission continue node. Add the int_bronto:/scripts/messages/contactusmessage script pipelet where the Assign and Mail-SecureSend pipelet was hooked in. Configure the message as shown below. Bronto Demandware Integration Page 1-14

15 Send-to-friend (Product) Since the SG 15.9 doesn't contain the SendToFriend pipeline, this feature is optional. In the SendToFriend-Start pipeline, there is a SendMail pipelet after Assign pipelet after the SendToFriend- GetProduct call node. Add the int_bronto:/scripts/messages/sendtofriendproductmessage script pipelet where the Assign and Mail-SecureSend pipelet was hooked in. Configure the message as shown below. Optionally, you may provide a From , FromName, or ReplyTo override if you want the send-to-friend to appear to come from the person submitting the send-to-friend form. Send-to-friend (Gift Registry and Wish List) Since the SG 15.9 doesn't contain the SendToFriend pipeline, this feature is optional. In the SendToFriend-Start pipeline, there is an Assign and Mail-SecureSend pipelet after Assign pipelet after the decision node checking if a product list is in the pipeline. Bronto Demandware Integration Page 1-15

16 Add the int_bronto:/scripts/messages/sendtofriendproductlistmessage script pipelet where the Assign and Mail-SecureSend pipelet was hooked in. Configure the message as shown below. Optionally, you may provide a From , FromName, or ReplyTo override if you want the send-to-friend to appear to come from the person submitting the send-to-friend form. Custom Messages Custom messages can be configured in the Bronto Demandware Connector inside of Bronto. Once you ve created a message, you will be provided an ID that will be used when configure the CustomMessage pipelet. You may insert this pipelet in any pipeline where you want to send a message through Bronto. The following example is an account created message inserted in the Account-CreateAccount pipeline right. The pipelet used is int_bronto:/scripts/messages/custommessage. The configuration for this specific message is: Bronto Demandware Integration Page 1-16

17 There are a few required inputs for the CustomMessage and a few optional parameters that will provide API message tags of their data if provided. Required - MessageID: This is the message ID provided by the Bronto Demandware Connector. It must be a string in the input. - Recipients: An array of strings containing the addresses of the recipients. Optional - Customer: A Demandware Customer object - Form: A Demandware Form object - GiftCertificate: A Demandware GiftCertificate object - Order: A Demandware Order object - Product: A Demandware product object - ProductList : A Demandware product list object - From Overrides the defined from for the message (Defined in Connector) - FromName: Overrides the defined from name for the message (Defined in Connector) - ReplyTo: Overrides the defined reply-to for the message (Defined in Connector) Insert pipelets for opt-in The OptIn pipelet provided by the Bronto cartridge is located in int_bronto:/scripts/pipelets/ optin. This can be inserted anywhere you have a pipeline that you want to use for registering or unregistering a contact s status in Bronto. An example of utilizing this pipelet is in the Account-CreateAccount pipeline. After the LoginCustomer pipelet is called, you can add a decision node and determine if the addto list form value is set and if so, call the OptIn pipelet. The example below defines a new private start node that will accomplish this. You can then add a call node to this private start node after the LoginCustomer pipelet. Bronto Demandware Integration Page 1-17

18 The decision node will skip the OptIn if the addto list checkbox is unchecked. If it is checked, the OptIn will be called with the following parameters (Note, it is marked as a Transactional pipelet). The OptIn takes in a few parameters that are useful depending on how it is configured in the Bronto Demandware Connector. By including the CurrentForms, the opt-in script can parse additional values from the forms and include those in the contact object that is created in Bronto. You may also specify a source for where the opt-in happened. In the Connector, you can specify different list memberships based on the source. Bronto Demandware Integration Page 1-18

19 The two required inputs are and Subscribed. determines which is opting in or out and Subscribed determines whether it is an opt-in (true) or opt-out (false). Provided in the cartridge are two example implementations of the opt-in pipeline above for Account creation and order checkout. These pipelines are in the int_bronto:/pipelines/brontooptin.xml pipeline. You can use a call node in the Account SiteGenesis pipeline right after the LoginCustomer pipelet in the CreateAccount pipeline. The pipeline to call is BrontoOptIn-Account. Bronto Demandware Integration Page 1-19

20 You can use the BrontoOptIn-Billing pipeline in the COBilling pipeline in SiteGensis near the end of the Start pipeline. Simply add a call node after COBilling-SaveAddress to it as shown below Insert Bronto footer ISML The Bronto footer ISML, located in int_bronto:/templates/default/footer/brontofooter.isml is used to enable several features: - Transactional message conversion tracking - Cart Recovery integration - Coupon Manager integration - Pop-Up Manager integration - Auto-apply coupon codes This template is smart enough to only utilize what is configured in the Bronto Demandware Connector. It is recommended to always install this snippet and never cache its contents. The recommended location in SiteGenesis is to install it in app_storefront_core:/templates/default/components/footer/footer.isml. See the Bronto Demandware Integration Page 1-20

21 following screenshot for the recommended install location: The snippet to use is: <isinclude template="footer/brontofooter"/> For SG v15.9 use the snippet <isinclude template="footer/brontofooter"/> after <iscontentasset aid="footercopy "/> row Insert custom application url Insert line brontocartrecovery : URLUtils.url('BrontoViews-CartRecovery').toString() into the app_storefront_richui:/templates/default/resources/appresources.isml inside the application urls For SG v15.9 insert line brontocartrecovery : URLUtils.url('BrontoViews-CartRecovery').toString() into the app_storefront_core:/scripts/util/resource.ds inside the application urls Bronto Demandware Integration Page 1-21

22 3.3.5 Insert custom js code 1. Insert lines if ( $('div#bronto-cart-recovery-shadow').length > 0 ) { var ordedno = $( "#bronto-cart-recovery-order-id" ).text()? $( "#bronto-cart-recovery-order-id" ).text() : ""; ajax.load({ url: Urls.brontoCartRecovery, data: {orderno: ordedno}, callback: function (response) { $( "div#bronto-cart-recovery-shadow" ).replacewith( response ); } }); } into addtocart and addalltocart event handlers inside the app_storefront_richui:/js /pages/product/addtocart.js Bronto Demandware Integration Page 1-22

23 2. Insert line ajax = require('../../ajax'), before dialog = require('../../dialog'). Recompile the app.js after changes. 3.4 External Interfaces All Bronto platform external interface communication is done via the scheduled jobs. This includes the delivery of transactional messages, importing of contact and order data, as well as submission of opt-in. The built-in Bronto app integrations may communicate directly from the storefront via Javascript in order to provide more real-time integrations, however they should not affect the performance of your storefront load times significantly. 3.5 Testing Demandware sandbox and staging instances may be registered with the same Bronto account as your production Demandware instance. They will not share their settings however any data you import from the Demandware sandbox could end up on your Bronto production account. It is recommended that any registered Demandware sandbox instances be set to Test Mode in the Bronto Demandware Connector. If a more thorough test is required via a separate Bronto sandbox account, please contact your Bronto Account Manager for more information. Bronto Demandware Integration Page 1-23

24 4. Operations, Maintenance 4.1 Data Storage There are a few custom objects that this cartridge utilizes in order to provide its functionality. BrontoExtensionSetting The synchronized settings from the Bronto Demandware Connector (Lifetime of install) BrontoJobSetting The last job run information for the jobs defined in the cartridge (Lifetime of install) BrontoMessageDelivery The transactional message queue. (Cleaned up after every run of the BrontoProcessDeliveries job) BrontoNewsletterSubscription The queue of opt-in/outs. (Cleaned up after every run of the BrontoRunner job that caused the opt-in job to run) BrontoPendingExecutions The queue of pending scripts to run from the Advanced settings in the Bronto Demandware Connector (Cleaned up after every run of the BrontoRunner job) BrontoRegistration The list of registrations for each site that is registered with the Bronto Demandware Connector (Lifetime of install) Data is stored in Bronto relating to the description of metadata for the registered Demandware instance. This data is stored for the lifetime of the install of the cartridge. In addition to that, any data synchronized via the jobs to Bronto is stored for the lifetime of the Bronto account. 4.2 Availability The expected availability of the Bronto SOAP API and the Bronto Demandware Connector is 100% uptime with scheduled maintenance. All jobs and data synchronization that occurs to these platforms are designed to retry if these services are unavailable and cause no availability issues with the Demandware instances or sites configured to use the cartridge. 4.3 Support Bronto support may be contacted at any time by visited and contacting us via our online chat system or telephone during the posted customer support hours. In addition to normal support, any support for this cartridge may be requested by talking with your account manager. Bronto Demandware Integration Page 1-24

25 5. User Guide 5.1 Roles, Responsibilities It is recommended to run the three jobs defined by this cartridge s metadata on a frequent, regular interval. It is recommended that all three jobs run on an interval between 1 and 5 minutes for the most real-time response of functionality. All settings should be configured in the Bronto Demandware Connector inside of the Bronto Marketing Platform. 5.2 Business Manager The Bronto cartridge provides a Business Manager Module for registering the cartridge with the Bronto Demandware Connector. This module must be enabled for all roles and sites that require access to registering the cartridge before the cartridge can be configured appropriately. 5.3 Storefront Functionality New storefront functionality includes integration with Bronto s Pop-Up Manager app which will display a modal dialog allowing another form of opt-in, auto-application of coupon codes with built-in URL redirector, which can be used in combination with Bronto s Coupon Manager for applying coupon codes directly from links in a message, and finally integration with Bronto s cart recovery application to track cart abandonments and trigger workflows in Bronto based on those abandoned carts. Bronto Demandware Integration Page 1-25

26 6. Known Issues None 7. Release History Version Date Changes Initial release (Rewrite of original cartridge) Bug fixes, added custom objects and additional recipients for messages Bug fixes Added Dynamic Imaging Service support, added ability to delete orders with selected status, added browse recovery integration, updated cart recovery integration. Bug fixes. Bronto Demandware Integration Page 1-26