NewsletterAdmin 2.4 Setup Manual

Transcription

1 NewsletterAdmin 2.4 Setup Manual Updated: 7/22/2011 Contact: Contents Overview... 2 What's New in NewsletterAdmin Before You Begin... 2 Testing and Production... 2 Creating Newsletter Templates... 2 Regular Newsletter Templates in Saxotech... 3 Best Practices... 3 Article Alert Templates in Saxotech... 5 Configure NewsletterAdmin... 6 /LocalData.INI... 6 Taxonomy-to-Cheetahmail Subscriber List Mapping... 7 /js/cci-newsletter-setup.js... 9 Syntax... 9 Configure Regular Newsletters Configure Articles (Custom News Alerts) Set up Mailings in Cheetah Add article sets to tool Set up Subscriber Lists Set up additional settings for article alerts /templates/macros/newsletteradminfunctions-custom.pbo (optional) Testing NewsletterAdmin... 19

2 Overview This document describes how to configure the NewsletterAdmin tool used to send newsletters and custom news alerts. The tool interfaces with the Cheetahmail API. What's New in NewsletterAdmin 2.4 Most of the functionality has been consolidated into global scripts Additional customization is possible using the setup file called cci-newsletter-setup.js. Support for individual article blasts, a.k.a. custom news alerts A server-side component has been introduced that prevents third-party cookie issues in Internet Explorer Progress bar and more detailed messaging in the log display Cleaned up user interface Before You Begin Before setting up NewsletterAdmin, you will need to collect a few pieces of information: Cheetahmail API credentials for each affiliate to be used by the tool. This information consists of a username and password (a.k.a "cleartext") used for the affiliate and may already be available to you in an older version of the newsletter tool, or you may need to request them from Cheetahmail. Access to the Saxotech Edit Interface. Login to the NewsletterTool piggy-backs on the Saxotech Edit Interface setup Testing and Production It is recommended you follow these steps on your DEV environment first. Once you are satisfied, you may then implement on your WEB environment. Once you are live with the tool, end users must access the tool from the EDIT environment, e.g. Creating Newsletter Templates NewsletterAdmin depends on pages generated by Saxotech Online templates. There are two main types of newsletter templates used with NewsletterAdmin: Regular newsletters use standard Saxotech sectionfront templates. Articles for use with custom news alerts use Saxotech alternate article templates. For both Regular newsletters and Articles, you can configure HTML, Plain-Text and Rich-Text versions of the given template.

3 Regular Newsletter Templates in Saxotech Most Web sites have existing newsletter templates in Saxotech. These are simply special "sectionfront" templates that are available at URLs known only to internal staff (for example, which would use the newsletter01_ovr.pbs template, could be your Daily Newsletter sectionfront). This document assumes you already know how to create a standard sectionfront, but here are some suggested practices you might find useful, as well as information about additional features you can use through macros you create and incorporate into your existing templates. Best Practices PBS template names Saxotech's &template= parameter can be useful when it comes to organizing your regular newsletter templates, especially considering you usually want to create a set of three templates for each newsletter product: HTML, Rich-Text and Plain-Text. In the past, sites would create three separate OVR templates for the set of three for example, the Daily newsletter may use newsletter01_ovr.pbs for the HTML version, newsletter11_ovr.pbs for the Plain-Text version, and newsletter21_ovr.pbs for the Rich-Text version. While this works, it may create confusion as products are added, changed and removed through the years. You can take advantage of Saxotech's template system to make it a little easier to identify which template is which at a glance: newsletter01_html.pbs == HTML version of Daily newsletter01_text.pbs == Plain-text version of Daily newsletter01_rich.pbs == Rich-text version of Daily This allows you to re-use "newsletter01" as the category for all Daily templates, and "newsletter" as the main category for all regular newsletter templates. You would access these from the URLs: /section/newsletter01?template=html /section/newsletter01?template=text /section/newsletter01?template=rich Organization of Object Files and Macros Most likely, your newsletters will use many object files and macros that aren't used in any other template on the site. This is a good use case for storing these files in special subdirectories only for the newsletters. If you follow the above advice, then your main category for all newsletter templates will be newsletter. This means you can create subdirectories under the /objects and /macros

4 directories called "newsletter." Saxotech will look in these folders first when building the template pages. In short, you are able keep all newsletter-specific files out of the way of the other files for your main Web site. Special parameters Some features available in the NewsletterAdmin interface can interact with your regular newsletter templates. This is done by appending query string parameters to requests for a given newsletter product URL. Date Override NewsletterAdmin has a feature that appends a query string parameter, &overridedate=<date> to template requests (where XXX is a date in YYYYMMDD format, or a daterange in YYYYMMDD- YYYYMMDD format). You can code your templates to use this parameter in different ways. One important use of overridedate is for purposes of Ad Operations. The AdOps group routinely uses NewsletterAdmin to preview newsletter advertisements set to appear on a future date. They enter the date they want in the NewsletterAdmin tool, and when they preview, the date sent with the request as detailed above. If you use the cci/cci-newsletter-ads.pbo macro or something similar on your templates, than that macro includes logic to pass the overridedate= parameter into the CCE call that retrieves the ads (setup of CCE ads in newsletters is covered in a separate document). You are free to use the overridedate feature for other purposes. For example, you may want your newslist to show only stories on the supplied date. You would then pass the parameter through to your newslist call via a macro. For example: /templates/newsletter01_ovr.pbs: <pbs:macro name="newsletternewslist"> /templates/macros/newsletternewslist.pbo: <pbs:newslist[%{overridedate} date=<%overridedate%>% % days="1"%]> If you add custom functionality for overridedate, please make sure to communicate it to the editors at your site, as well as Corporate Interactive Services. It is also important to keep in mind that the global ad serving macro as listed above depends on this parameter. News Days Override Similar to the Date Override, there is a feature in NewsletterAdmin that editors may use which appends &days= to the template requests. This allows you to code a macro to change the newslist based on the value the editors provide via the tool.

5 For example, your template may usually only show 1 day's worth of stories, but editors may want to pull 2 days' worth of stories sometimes, in order to pull in stories posted late yesterday. The editor could enter 2 in "News Days Override" field in the NewsletterAdmin interface. You would then pass the parameter through to your newslist call via a macro. For example: /templates/newsletter01_ovr.pbs: <pbs:macro name="newsletternewslist"> /templates/macros/newsletternewslist.pbo: <pbs:newslist days="[%<%days%>% %1%]"> If you add custom functionality for &days=, please make sure to communicate it to the editors at your site, as well as Corporate Interactive Services. Article Alert Templates in Saxotech If you want to use NewsletterAdmin to send individual story alerts, you must create alternative article templates. Whereas you typically have gen_art.pbs for articles on the site, or category-specific article templates such as news_art.pbs or blogs_art.pbs, the alternative template uses a name like: gen_alerthtml.pbs. Since this is a "gen" template it can apply to a story in any category. For an illustration of this approach, compare the output of a normal template (gen_art.pbs) of a Crain's Chicago Business article with the output of the alternate template (gen_alert-html.pbs) As you can see, the article ID is exactly the same, but the additional parameters drive the change in output in the second link. Besides leveraging &template=, the above link also includes &sectioncat=. This is one way to group object files together for all custom alerts, similar to the category subdirectories mentioned in the previous section. Since the category may change from story to story, you can use a special subdirectory for a sectioncat. In this case, the object files we want to use for custom alerts will be stored in /templates/objects/sectioncat/customalerts

6 Recently, Saxotech enabled the ability to store object files in directories based on template. So for the above alternative template we could have also stored object files in /templates/objects/template/alert-html Ultimately, it is up to you where to store your object files. As long you are able to keep track of them, you could even use object classes and store everything in the main objects folder. But if you are looking for ways to clean up the objects folder, the above methods may be useful. Configure NewsletterAdmin Once you have some templates to work with, you can configure NewsletterAdmin for your site. Configuration is managed using two required files, and one optional file: REQUIRED: /LocalData.INI /js/cci-newsletter-setup.js OPTIONAL: /templates/macros/newsletteradminfunctions-custom.pbo /LocalData.INI LocalData.INI is a Saxotech configuration file that allows you to add custom variables for use in templates. NewsletterAdmin uses this file to read in some settings related to your site. Add these settings to the [STATICVALUES] section in your existing LocalData.INI. [STATICVALUES] Cheetahmail=1 CheetahMailAPIUsers={"CCB":{username:"crain-API",cleartext:"c@fsdbs1d"}} Setting Description Cheetahmail Enables the Cheetahmail integration. Should be 1 CheetahMailAPIUsers A JSON-formatted string that contains the Cheetahmail API credentials. You can copy the above and change the bold text to the values for your site. The first bold value should be a short code for your site and match the "affiliatename" for your regular newsletters and sets. The second value is the username for the

7 Cheetahmail API login for your site. The third value is the password. If you use mailings across different affiliates, your string will be more complicated. Contact for more info. Taxonomy-to-Cheetahmail Subscriber List Mapping If you use article alerts in NewsletterAdmin, the tool can automatically select subscriber lists based on the Taxonomy Keywords attached to the Saxotech article. To map taxonomy words to Cheetahmail subscriber lists, create a new section in LocalData.INI called [TaxIdToCheetahId_Keys] This section will contain one line for each Taxonomy Word. You can map multiple taxonomy words to the same list, but you must create a new line for each taxonomy word. A finished section may look something like this: [TaxIdToCheetahId_Keys] 3677= = = = = = = = = = = = = = = = = The number on the left side of the equals sign is the numerical ID of the Saxotech Taxonomy Word. The number on the right side of the equals sign is the numerical ID of the Cheetahmail subscriber list. How to find the Saxotech Taxonomy Word ID 1. In the Saxotech Edit Interface, navigate to Admin > Taxonomy. 2. Find the taxonomy word on the left side by navigating the Taxonomy tree or searching in the search box

8 3. Click on the Taxonomy Word that you want the ID for. 4. The ID appears on the right side of the screen atop the other Taxonomy settings: How to Find the Cheetahmail Subscriber List ID 1. In the Cheetahmail Admin area, click on "Admin" from the top-most menu 2. On the next page, click "Subscriber Lists" 3. On the next page, click the name of the Subscriber List you want. 4. On the Edit Subscriber List page, the ID of the list is seen in the URL of the page. Check the address bar for the value of the &pid= parameter: For the above example, the line in LocalData.INI to map the "Arts & Entertainment" taxonomy to the "Culture and the Arts" subscriber list would be as shown in the highlighted section below:

9 [TaxIdToCheetahId_Keys] 3677= = = = = = = = = = = = = = = = = NOTE: There is another step to configuring the auto-mapping feature, which is covered in the next section. /js/cci-newsletter-setup.js Most settings are kept in a client-side JavaScript file on your site. By default, NewsletterAdmin expects to find this file at /js/cci-newsletter-setup.js. You can specify an alternate path by adding the following setting to LocalData.INI. Do not include a trailing slash: CCISetupJSPath=/my/alternate/path Syntax The file is JavaScript, and you should use JavaScript object literal syntax to enter the information. Each major section in the file is an object that is defined starting with CCI["newsletter"]["sectionname"]. The object is enclosed in curly brackets, so the "shell" of the section looks like this: CCI["newsletter"]["newsletters"]["DAILY"] = { } // settings for the "DAILY" regular newsletter section go in here... Inside the curly brackets, there will be multiple variables you define. Inside the object, lines must be terminated with commas (not semi-colons). The final line before the outer curly bracket should not have a comma:

10 CCI["newsletter"]["newsletters"]["DAILY"] = { // settings for the "examplesectionname" section go in here... "aid": 1234, "mid": 6789, "urlh": " } open curly bracket comma-terminated line Last line before close curly bracket does not have comma close curly bracket Configure Regular Newsletters CCI["newsletter"]["newsletters"]["newsletterID"] "Regular" newsletters are the newsletters you typically send at regular intervals, such as a Daily Alert, Weekly Issue Alert, and other special products that go out at specific times. These are treated separately than individual article alerts, which are covered in a later section. Here is an example completed section for a regular newsletter we will call "DAILY." Notes: The newsletter ID you use (this example uses DAILY) can be anything, so long as you do not use it for other newsletters. The value can have any letters, numbers, underscores ( _ ) or dashes ( - ). No other special characters or spaces. If a setting is not required and you are not using the setting, you should omit the line. Do not supply empty strings ("") for values. Notice that the main "DAILY" section includes a subsection called "fields." This is an object as well (surrounded by its own set of curly brackets { }), and it follows the same syntax rules as the outer object: the final line before its close curly bracket does not have a comma, but the others do. The pieces of this block that you can change for each newsletter are in boldface. Do not change the other names. See below for information about valid values for each setting. // START REGULAR NEWSLETTERS SETTINGS CCI["newsletter"]["newsletters"]["DAILY"] = { "name" : "Example Daily Newsletter", "subject": "The default subject for example daily newsletter", "fields" : { "affiliatename" : "CCI", "aid" : , "mid" : ,

11 "urlh" : " "urlt" : " "urla" : " } }; // END REGULAR NEWSLETTERS SETTINGS For each additional newsletter, you would create a similar section, using a common identifier that is something other than "DAILY" Setting Quotes in Value? Required? Possible values Description name YES YES Any string The label that will appear in the dropdown Product Selector in NewsletterAdmin subject YES NO Any string The default subject line that will prepopulate in the E- mail Subject field in NewsletterAdmin for this product. hide NO NO true false Prevents the newsletter from appearing in the Product Selector of NewslettrAdmin. Useful for hiding a newsletter without having to comment out the entire section in the configuration. Possible values are true or false. Default if not supplied is false. fields > affiliatename YES NO Matching string from affiliate setup Needed when multiple affiliates are used by the same tool fields > aid NO YES Any number This must be the Affiliate ID in Cheetahmail associated with the mailing fields > mid NO YES Any number This must be the Mailing ID for the mailing in

12 Cheetahmail fields > urlh YES YES Any URL This is the full URL to the HTML template for the product fields > urlt YES YES Any URL This is the full URL to the Text template for the product fields > urla YES NO* (see description) Any URL This is the full URL to the Rich-Text template for the product. *If you do not supply this, you should at least make sure to configure a "urlt" (Text template) as above, and enable aolgen (see below). fields > aolgen NO NO* (see description) 1 0 Specifies whether to automatically generate a rich-text mailing based on the plain-text (urlt) template (must be set to 0 or leave out this line if you supply a urla setting). Default if not supplied is 0. Configure Articles (Custom News Alerts) CCI["newsletter"]["articles"]["sets"]["SETID"] The tool can retrieve lists of articles from Saxotech Online in order to send out individual news alerts. This feature relies on the use of alternate article templates, usually using the &template= parameter. (See Article Alert Templates in Saxotech for more information about creating the templates) Set up Mailings in Cheetah Before you begin, you must create at least 5 mailings to be used in Cheetahmail for your production article blasts, as well as a separate mailing to be used for tests. Because several blasts may be sent in close proximity with one another, the tool rotates through a list of mailings you define to avoid conflicts. If you use more than one "set" as shown below, it is suggested to create another 5 mailings for that set only.

13 We recommend you keep these mailings in a folder separate from other mailings for easier troubleshooting, but it is not necessary. Take care to note the Affiliate ID and Mailing ID as you will need these for the configuration. How to find the Cheetahmail mailing ID and affiliate ID 1. Find the mailing after it is created and go any one of the edit screens for the mailing ("Main", "Envelope", "Content", etc. 2. On these edit pages for the mailing, the ID of the mailing is seen in the URL of the page. Check the address bar for the value of the &mid= parameter and the &desired_aid= parameter Add article sets to tool You must configure at least one "set" of articles for blasts. For each set, you may specify the criteria for the articles to pull into the product selector, the parameters to use to pull in the correct article template, the mailing IDs to use for article blasts, and more. You must name the set of articles that loads initially in the tool "default". The other sets can use any other identifier (only use letters and numbers for the identifiers). Any other sets you add will be made available for NewsletterAdmin users to toggle between Here is an example setup using two sets: the "default" and another set called "alt". The pieces that you can change are in boldface. CCI.newsletter["articles"]["sets"]["default"] = { "defaultarticlelistparams": { "days": 4, "count": 10, "excludecategories":"issue%,hold%" }, "affilliatename": "CCI", "testmid": " ", "mids": [" "," "," "," "," "], "baseuri": " "urlhparam": "?template=customalerts&sectioncat=custom-html", "urltparam": "?template=customalerts&sectioncat=custom-text",

14 }; "urlaparam": "?template=customalerts&sectioncat=custom-rich", "aolgen": 0 CCI["newsletter"]["articles"]["sets"]["alt"] = { "defaultarticlelistparams": { "days": 10, "count": 20, "categories": "ISSUE%" }, "affilliatename": "CCI", "testmid": " ", "mids": [" "," "," "," "," "], "baseuri": " "urlhparam": "?template=customalerts&sectioncat=custom-html", "urltparam": "?template=customalerts&sectioncat=custom-text", "urlaparam": "?template=customalerts&sectioncat=custom-rich", "aolgen": 0 }; For each additional set, you would create a similar section, using a common identifier that is something other than "default" and "alt" Setting Quotes in Value? Required? Possible values Description defaultarticleparams Sometimes No Object This is an object that contains any pbs:newslist settings. For example, "days", "count", "categories" can all be used like in a Saxotech tag (of course, the syntax is JavaScript object literal syntax). Wildcards are supported as in Saxotech, e.g. "categories": "ISSUE%" You may use quotes around numbers or leave them off. affiliatename YES NO Matching string from affiliate setup Needed when multiple affiliates are used by the same tool testmid YES YES Number The mailing ID used for test article blasts (don't use an MID that you use for

15 production blasts) mids YES YES Array An array of the 5 or more mailing IDs to rotate through for production blasts baseuri YES YES String The main domain of your edit site including but without the trailing slash, e.g. " urlhparam YES YES String The query string to append to the article for HTML template urltparam YES YES String The query string to append to the article for text template urlaparam YES NO* (see description) Any URL This is the full URL to the Rich-Text template for the product. *If you do not supply this, you should at least make sure to configure a "urltparam" (Text template) as above, and enable aolgen (see below). aolgen NO NO* (see description) 1 0 Specifies whether to automatically generate a rich-text mailing based on the plain-text template (must be set to 0 or leave out this line if you supply a urla setting). Default if not supplied is 0.

16 Set up Subscriber Lists For you to be able to send article alerts to subscriber lists, you must configure the subscriber list IDs in Newsletter Admin. You can add as many SIDS sections as you like. These sections will be grouped in the left side of the subscriber list selector in NewsletterAdmin. The pieces that you can change are in boldface. // START CUSTOM NEWS ALERT SIDS // you may group SIDs under different headings (Industries, Companies, Topics, etc.) as shown // you must have at least one group if using this feature CCI.newsletter["sids"]["Industries"] = { " ":"Accounting and Consulting", " ":"Advertising and Marketing", " ":"Aerospace" }; CCI.newsletter["sids"]["Companies"] = { " ":"Acme Corp.", " ":"ABC Inc.", " ":"Initech" }; CCI.newsletter["sids"]["Topics"] = { " ":"The Environment", " ":"People on the Move", " ":"Natural Disasters" }; // END CUSTOM NEWS ALERT SIDS Note each "sids" block uses opening and closing curly brackets { } terminated with a semi-colon ( ; ). Inside the object curly brackets, settings are separated with commas (, ). The ID/Label pairs are quoted and separated with colons ( : ) The section name. This can be anything you like and only applies to grouping the lists in the interface of NewsetterAdmin The Cheetahmail subscriber list ID. A label for the subscriber list. This does not need to be exactly the same as the list name in Cheetah, but it is useful to use that list name for clarity The tool can automatically select subscriber lists based on the Taxonomy Keywords attached to the Saxotech article. For more information, see Taxonomy-to-Cheetahmail Subscriber List Mapping Set up additional settings for article alerts The tool supports some additional customizations:

17 Attach common fields to all API calls Cheetahmail supports additional parameters in the API calls sent by NewsletterAdmin. Currently, the only field sent is called "track", and is used with link tracking. Additional "common fields" may be added in the future. To specify common fields including track, create the following section in cci-newsletter-setup.js. The pieces you can change are in boldface. // START COMMON FIELDS CCI["newsletter"]["commonFields"] = { "track": "ccb" }; // END COMMON FIELDS Setting Quotes in Value? Required? Possible values Description track Yes No String (4 characters maximum) This is the prefix added to links when link tracking is enabled. You must specify a prefix in order to use link tracking. Link tracking is strongly encouraged as it allows you to get detailed analytics for clickthroughs. Position of articles list in Product Selector By default, the article list appears above the list of regular newsletters. To make it appear below the list of regular newsletters, include this line in cci-newsletter-setup.js: CCI["newsletter"]["articles"]["articlesPosition"] = "bottom"; /templates/macros/newsletteradminfunctions-custom.pbo (optional) Once you complete the steps above, your tool will be functional at However, you can further customize the functionality of the tool by creating a macro on your local site called newsletteradminfunctions-custom.pbo

18 This file gives you the ability to show the specific actions you want in the tool. The defaults are as follows: CCI["newsletter"]["loadOptions"]["features"] = [ "showsettings", "preview_html", "preview_text", "preview_rich", "authenticate", "setmail1", "mailgo1_test", "mailgo1_approve", "mailgo1_approverecurring", "mailgo1_unapprove", "mailgo1_send", "set_test", "set_send" ]; Note the use of square brackets [ ] for these section, rather than curly brackets { } CCI["newsletter"]["loadOptions"]["overrides"] = [ "subject", "dateoverride", "newsdaysoverride", "subscriberlist", "forcebackupads" ]; Say for example, that you did not want to show the "Approve Recurring" action ("mailgo1_approverecurring") or the "Force House Ads" checkbox ("forcebackupads"). In that case, the contents of your newsletteradminfunctions-custom.pbo would look like this: CCI["newsletter"]["loadOptions"]["features"] = [ "showsettings", "preview_html", "preview_text", "preview_rich", "authenticate", "setmail1", "mailgo1_test", "mailgo1_approve", "mailgo1_unapprove", "mailgo1_send", "set_test", "set_send" ]; CCI["newsletter"]["loadOptions"]["overrides"] = [ "subject", "dateoverride", "newsdaysoverride",

19 ]; "subscriberlist" The reason these settings are in a macro rather than the cci-newsletter-setup.js file, is that putting the settings in a macro allows you to build different versions of the tool based on a query string parameter. For example, if you wanted a certain set of users to be able to preview newsletters only, you could make the logic in the macro conditional on a parameter called tooltype: CCI["newsletter"]["loadOptions"]["features"] = [ "showsettings", "preview_html", "preview_text", "preview_rich"[%{tooltype!preview}, "authenticate", "setmail1", "mailgo1_test", "mailgo1_approve", "mailgo1_approverecurring", "mailgo1_unapprove", "mailgo1_send", "set_test", "set_send"%] ]; CCI["newsletter"]["loadOptions"]["overrides"] = [ "subject", "dateoverride", "newsdaysoverride", "subscriberlist", "forcebackupads" ]; The object script above will result in only the preview actions being available if the URL of the tool contains &tooltype=preview. SPECIAL NOTE: Ad Ops uses a version of the tool that uses &tooltype=adops in the URL. Do not use this parameter for your own custom tool types. If you want all functionality, you do not need to create a newsletteradminfunctions-custom.pbo macro. Testing NewsletterAdmin Once you have added the necessary configuration settings above on your Dev site, you are ready to test NewsletterAdmin at REMEMBER THAT IF YOU HAVE TARGETED ANY MAILINGS TO LIVE SUBSCRIBER LISTS, THE TOOL WILL SEND TO THOSE SUBSCRIBER LISTS IF YOU USE THE "SEND NOW" OR "SET & SEND" ACTIONS! BEFORE TESTING THOSE ACTIONS, MAKE SURE YOUR MAILINGS ARE

20 TARGETED AT LISTS THAT ONLY CONTAIN TEST ADDRESSES. CONTACT CORPORATE INTERACTIVE SERVICES IF YOU HAVE QUESTIONS ABOUT THIS. When you are satisfied with your testing, you should contact Corporate Interactive Services for a final approval and to schedule training with editors on any new features of NewsletterAdmin. Following this review and training, you can push the templates and configuration files to Web. Your users should then use the tool from