putting it where they need it: how to populate a salesforce knowledge base with framemaker content

Putting it Where They Need ItPublishing FrameMaker-Sourced Content

into a SalesForce Knowledgebase

I’m John Sgammato

• Documentation architect at Actifio, previously Imprivata, CoreChange, and Genetic MicroSystems/Affymetrix

• You might see me in: STC New England Chapter, STC Lone Writers SIG, the Framers list, and some LinkedIn

• I specialize in hi-tech start-ups

• That means I have to build everything myself…

• …and adapt to whatever other systems are put in place without my consultation.

Support Doesn’t Use My Doc!

I see this a lot:

• Support MUST use Salesforce for customer issue tracking

• Salesforce provides a “knowledgebase tool”, so they work with that, building it themselves.

• But they don’t do a good job. They end up with a knowledge base with no knowledge in it, baffling users.

• What they really need is my hundreds of ENG-reviewed procedures in their knowledgebase.

So I’ll Put My Doc into Salesforce!

• Well, that’s easier said than done…

• The tool is Salesforce Knowledge (plus Chatter if you can get it)

• There’s no “Salesforce” or “Knowledge” file format

• RoboHelp is no help – actually, nothing is

• Salesforce erects its own hurdles, like the 10MB limit

• With good reason; it’s a complex tool

About Salesforce

• Salesforce is Huge, and there are major stakeholders in your company with no interest in your worthy project.

• They have new knowledgebase: Salesforce Knowledge.

• It’s in the Cloud. They upgrade you on their schedule.

• You must have help from your Salesforce Admin.

• This requires resources, and brings benefits.

• You can pitch this vision:

We can make our good Engineering-reviewed content available to customers and support, with role-based access and proper version control. Chatter enables crowdsourcing.

What You Need

• FrameMaker: I used FM11 (unstructured), other versions should work, structure may work

• FrameScript + a small suite of scripts

• Mif2Go + config files

• Salesforce Knowledge

• Documentation

FrameMaker Gotchas

By clean, well-formed, and HTML-friendly, I mean:

• No index, ToC, title page and other unneeded files

• Consistent para, char, and x-ref styles

• No unresolved x-refs or text insets

• X-refs without page numbers or chapter numbers

• Consistent conditional text

• No multiple images sharing an image frame

• No two identical titles

FrameScript & the Scripts

Rick Quatro’s script suite:

• _RunMe.fsl

• _RunMe.ini

• Fix-lists.xsl

• GetCsvInfo.fsl

• MakeHtmlMap.fsl

• MakeProjectFolderStructure.fsl

• MakeZipArchive.fsl

• ProcessHtmlFiles.fsl

Two FrameScript scripts:

• TidyImport.fso

• ArchiveFm.fso

The Incredible Mif2Go

Mif2Go makes export-quality XHTML, HTML, RTF, etc

• Do not use the FM export – it is essentially deprecated

• Mif2Go has great support on the Framers email list

• Mif2Go uses a few config files that you must edit

• It has almost no error-checking – do it right or fail

• Experience is your only teacher

• You can use my config files

Here We Go!

Here’s the Procedure:

1. Set Up the Folder Structure

2. Prepare the FM Files

3. Run Mif2Go

4. Run the FrameScripts

5. Import into Salesforce Knowledge

6. Publish to Users

1. Set Up the Folder Structure

Mif2Go relies on config files that point to specific folders. They can be confusing, so you must set them up right.

• Unzip Project.ZIP at C:\

• C:\Project\ _m2xhtml.ini, and the .prj project file\_config – html_doc.ini\images – referenced images from the FM book\scripts – the FrameScript scripts

Geography and Naming are Important

Use this structure with these names:

C:\Project

_config

html_doc.ini………....Do nothing here

images ……………………..images for the FM docs

ReadyForImport …………Your finished files go here

scripts……………………….Do nothing here

ToBeProcessed …………..Your working files go here

OnlineTemplate.fm

<FM doc that you are processing>

2. Prepare the FM Files

This makes your content HTML-friendly and robust.

1. Install and run the ArchiveFM script on your source FM project and use the files from the ZIP. This deletes unused images.

2. Delete the TOC and the IX from the book, and the Title Page if there is one. Update the book.

3. Search for unresolved X-Refs and resolve them. Make sure all images are in the same images folder.

4. Select all files in the book and run the TidyImport script to import para, char, x-ref, condition formats & page layouts from OnlineTemplate.fm. NOT Variables! Update and resolve issues. Don’t worry about inconsistent page numbering. Save and close.

5. Copy the FM files to C:\Project and the referenced images to C:\Project\images. Reopen the book to update the links.

3. Use Mif2Go to Generate Good XHTML

1. In the FrameMaker book file menu, click Set Up Mif2Go Export and select XHTML. This opens up _m2xhtml.ini.

2. In _m2xhtml.ini [Setup], change FileSuffix=xhtml to =html.

3. In _m2xhtml.ini [Setup], make 3 edits: PrjFileName, ProjectName, and FrameBook with the name of the book file. Then edit [HTMLOptions] Title= with the human name for this content. Save _m2xhtml.ini.

4. Select the book file. In the FM File menu, select Save Using Mif2Go. The Choose Project dialog appears. Click OK. The Mif2Go Export dialog appears. Click OK to run the XHTML project. This will take a few minutes. Wait for the chime and the little Mif2Go finished creating files dialog.

4. FrameScript: Build the CSV and the ZIP

1. Open the FrameMaker book. You do not need to open the chapters. From the FrameScript menu, run the _RunMescript.

2. Enter your Project name (the book file name) a Data Category (typically the version) and the Component (a keyword that Salesforce is configured to use for this content). For _wrap folder, navigate to the _wrap folder.

3. Click OK. This creates a ZIP and a new folder called ImportToSalesForce_Project

4. (You can delete everything in Project folder except _config, scripts, and _m2xhtml.ini, and copy in the next book.)

The Finished ZIP Looks Like This

5. Import the ZIP into Salesforce

• This is a primitive tool!

• There is a hard limit of 10MB for the finished ZIP file.

• Upload ImportToSalesForce_Project to SalesForceKnowledge. Log in as admin. In the upper right corner under your name select Setup. Navigate to Administer > Data Management > Import Articles. Scroll down to the importer tool. Select Procedure and then browse to the ZIP file, then click Import Now.

6. Publish to Your Users

• Under +, select Article Management.

• View the files, test them, and then publish them.

What it Looks Like

Testing

Watch for:

• Ordered lists

• Images

Questions?