White Paper

The Wild World of Wikis in Acumatica

Published on

August 15, 2019

By

by

Troy Vars

The most common complaint on employment surveys is lack of communication. Followed closely on the heels of that is not knowing what is expected or what the “right” procedure is. Wikis are one method companies are utilizing to battle the concept of tribal knowledge. This article focuses on the technical aspect of implementing a Wiki. Due consideration should be given to the cost of creating and maintaining documentation vs. the cost of not having clear policies and procedures. The costs of fraud, indecision and rework should be weighed against the frequency and speed of change in your organization. Likewise, one shouldn’t discount the cost of documenting and maintaining processes that do not reflect the reality of the situation. Paying for something that is never used, is the quintessential example of “Just because you can do a thing doesn’t mean you should.”

Today we discuss the built-in functionality of Wikis in Acumatica. Wikis allow us to expand on and customize the robust help articles provided by the Acumatica team. We are able to tailor them to our own business processes and provide quick reference materials for our employees. Coupling this with a company dictionary and/or abbreviation glossary and we improve our ability to onboard new employees effectively.  

Further uses include troubleshooting knowledge bases for Internal use, or even external use via the Acumatica customer portal. Since, Acumatica has included Wiki functionality from the beginning there are some handy tools to quickly add to the knowledge base from Cases or even Inventory screens. This makes it easy to maintain and grow your knowledge base as the life cycle of product support matures and develops.

Alternatively, you maybe running a separate site for employee communications of upcoming events and company news such as Sales Activities or Policy Changes. These sites are great when employees regular check them for updates. However, you might consider a Wiki page as your Acumatica default landing page. This way every employee would see the page when they logged on to your ERP System.

Basic Structure

The Wiki site at its core consists of the built-in help Wikis and any additional Wikis you may desire. For example, my former company added a Corporate Dictionary Wiki, a Corporate Process Wiki, a weekly Announcement Wiki, and both an internal and external Knowledge base Wiki. Each of these Wikis has a default wiki article or landing page, its own set of security for editing, reading and approving new articles, its own look and feel section with templates for header, footer, reading and printing, and site map.

Getting Started with a New Wiki in Acumatica

Create a new Wiki under the Modern UI System Management=> Wiki Preferences => Wiki menu option. Give it an ID that makes sense and can be understandable by others. The built help uses HelpRoot_ plus

the name of the module it applies to. For my example I choose CorpRoot_Dict and for the name I put Corporate Dictionary Wiki. I add this to the help dashboard give it a sequence of 99. I will come back later and add my default article after it’s created. I set the classic UI to Help as well and use Corp Dictionary for my title.  I set the articles to go on hold before release and opt not have an approver. If I wanted one, I could use an existing approver from the company tree or create a new group for just this Wiki.

I set my article type to Article since this isn’t a knowledge base article. I will come back and set a default site map tag later after I create one. I set internal users to be able to edit the Wiki and set Wiki Admins to delete. This gives all internal employees the ability to edit an existing page but only admins can remove or add new pages. Edits will trigger the article revision to go on hold and only Wiki Admins will review and then publish the changes. I save these settings and voilà I have a Wiki. Well, I have the shell of a Wiki we haven’t done anything with a layout design or added any pages with content yet.

Designing the Layout

Technically I could start creating pages right now using standard Wiki Markup Language. Those pages would be independently formatted and dependent on the Wiki Authors to format the pages. Probably a better idea to set some standards and make it easy on the authors.

Acumatica has a section for creating a style sheet using standard CSS like what can be found here https://www.w3schools.com/css/ . There are also four sample style sheets for you to reference or use. In addition, you can create a Wiki Page to use as one of the four template types. Give the page as per the Acumatica help quoted below, and then create your content.

On the Content tab, in the Article ID box, specify the ID for the template as follows:

  • If this is an article template or print template, type ContainerTemplate: and then specify a text string identifying the template; do not use any spaces in the line.
  • If this is a header or footer template, type GenTemplate: and then specify a text string identifying the template; do not use any spaces in the line.

Lastly you need to decide on the breakdown of what constitutes a Wiki page worth of content. The beauty of Wiki Markup is the ease with how links to other content can be created either as separate pages or as anchors on the same page.  

For my Dictionary example I could have one article/page holding all the terms and definitions, a separate article for definitions and abbreviations, an article by letter all the A words on a page then BCD on the next page etc, or each word could be its own page Wiktionary style. My Dictionary is pretty small only a dozen words so far, so I will opt to do one article but with the header and footer having anchor links to the alphabet sections. That way I can split it off into separate articles later if I want to.

Creating Pages

From the Wiki Site Map or the Wikis menu options select any article from your newly created Wiki. Use the + to add a new article. If you don’t see this button or it is grayed out, make sure you have wiki Admin role in User Security.  

Set your Article ID, the basic help tries to follow the Module and Transaction naming conventions using AA_AP_ with a short description. I will be using DICT_Landing for my main article and DICT_A and DICT_BCD etc for subsequent breakdowns if needed. This is inelegant and may lead to having to Rename or Re-ID a wiki article later, luckily Acumatica allows to make this change easily. If I were using the wiktionary approach I would use DICT_ with the word I was defining. This distinguishes it from a help article that might use the same name. For example, DICT_Ionizer vs KB_Ext_Ionizer vs KB_Int_Ionizer vs HELP_AP_IonizerWarranty. Which maybe separate articles that could be linked to each other. Note: if you want your wiki article tied to a specific form it must contain the form reference like AP_10_10_00.

Name your article and select Wiki or HTML format. Wiki uses the Wiki Markup Language and Html uses HTML 5. Select you parent folder if applicable or this may be your main Wiki ID.  

Add your content. Here we write our article using all the styling tools and leveraging our work thus far. What content you choose to put here is up to you, pictures, embedded objects, links into and out of the site. The built in Wiki Help Articles have references to using all of these features. Of particular help are the Wiki Markup Reference, Wiki Content Procedures: To Add A Link, To Add A Graphic and To Add A Table.

Properties tab allows you to write a brief summary, add keywords and tags all of which are searchable by Acumatica search engine. Here we also select versioning or un-versioned. Previous versions are accessible when versioning is selected, if not only the last revision is saved.  

Categories is an advanced tagging function that allows articles from separate Wikis to appear when an end user performs a search.

Products tab further ties articles to specific products identifying these articles as related to the specific product.  

In my Ionizer example above, one might tie all the articles to the Ionizer product or category and for the HELP_AP_IonizerWarranty to a warranty and special AP process.

Each article stores the images and objects from the content and utilizes the built document management tools for revisions, approvals etc. Want your current phone list downloadable from an article? Track and display the date of update and current revision here and be able to link to it from other articles or transactions in Acumatica. One place to store it, one place to update it, many places to access it.

History tab shows the history of changes on versioned articles. Use the compare button to see a list of changes between to selected versions.

Responses Tab allows viewers to make comments or request changes or clarification to an article from the Wiki Author.

Lastly, each article further has built in security so that individual articles can be locked down further. Have a Knowledge Base article only tier 2 support can perform, this could be restricted so that Tier 1 cannot see the steps to complete it.

Once your article is complete and ready for publication or approval remove the hold and the system sets the status based on your Wiki rules. Once approved and published the new article or version is released into the wild and Users will now be able to see it.

Add a Wiki Article to a Dashboard  

Navigate to the dashboard you want to add the Wiki Article to. Click on design and add a widget. Select the article you want to display and enter an optional caption for it. Size to display as appropriate.

Wikis are great tools when implemented and maintained well. Hopefully this article has helped you determine the time cost necessary to get yours up and started. Remember CS3 support team is here to answer any questions you might have on the Acumatica software or documenting business processes in general.

Photo by Franck V. on Unsplash

Written By
Website Proudly Crafted by DSB Creative