Skip to main content

Best Practice: Publishing Knowledge to MindTouch (TCS)

Written by Amanda Cross
Content Strategist at Crosswise Consulting
This page applies to:MindTouch 4 and MindTouch TCS


This document explains how and why to use the MindTouch API to push knowledge capital into MindTouch from other systems you use in your business.


This solution includes writing code that calls to the MindTouch API from another business system. To use this solution, you'll need:

  • User credentials for a MindTouch user with Admin permissions.
  • Proficiency with using APIs. The MindTouch API elements you'll need are described in this document.

If you want to build a solution that automatically keeps the information in MindTouch in sync with the business system where the knowledge originates, then you'll need a way to write a plug-in for that business system. If you only want to batch update the knowledge in MindTouch on a periodic basis, then you'll only need a way to access the knowledge that you're populating in MindTouch. 

Why Centralize Knowledge Capital

Many people from around your organization may need knowledge from the ticketing system used by your customer support team, issue tracker used by your product development team, or other business systems.

But giving widespread access directly in to the business systems can be inconvenient because advanced skills and training may be needed to ensure that the casual viewer doesn't disrupt the regular usage of the system. When a person only accesses a system occasionally, it is easy to forget the training, which makes allowing access risky.

Even if you can mitigate the risk, sending each person to each individual business system to gather different kinds of information is difficult and inefficient. People end up feeling overwhelmed with too many places to find the knowledge they need to make good decisions. In many cases you'll find that people find it so difficult to get the information that they need from these systems, that they'll rely on old versions of the knowledge or worse, make decisions without using the knowledge at all.

By centralizing reports from diverse business systems into MindTouch, you can create a real-time dashboard of knowledge people need that: 

  • Puts the information in a central location that everyone has access to, saving time and annoyance.
  • Ensures that everyone is using the freshest data.
  • Makes it easy for people from all over your organization to share knowledge and make better decisions.

Example Scenario


A software company's Gold Support agents can file feature requests on behalf of their Gold-level clients. These feature requests are managed by the Product Development team in their issue tracking system.

The Gold Support agents need knowledge about the feature requests from the issue tracking system so they can share it when their Gold-level clients call. However, it is not practical for each Gold Support agent to navigate the issue tracking system. Instead, the Gold Support agents end up asking the Product Developers for status updates when a Gold-level client calls, which is inefficient and unsatisfactory to the customer:

  • The Product Development team does not like being interrupted so often for status information about their tasks
  • The Gold Support agents do not like scrambling to find information when a client calls in
  • The Gold-level clients do not like waiting for information when they call in for a status update


The software company decided to push information about the feature requests status from the issue tracker into a MindTouch page. 

  1. Together, the Gold Support team and the Product Development team evaluated what information from the issue tracking system was needed by the Gold Support agents in order to successfully answer Gold-level client questions. They decided that five fields from the issue tracking system were all that was required:
    Field Purpose
    Issue number Clients often refer to their change requests by issue number, so showing this number in MindTouch allowed the Gold Support agents to find the relevant page.
    Description The short description of the issue allowed the Gold Support agent to verify that this was the right issue.
    Status This short code describes the current status of the issue in the Product Development workflow.
    Last Updated This field shows the most recent date the feature request was changed.
    Comments This field contains comments the Product Developer wrote while working on this feature request.

  2. They considered how fresh the information from the issue tracking system needed to be. They decided it would be adequate to update the MindTouch page each evening with the information about the relevant feature requests.
  3. The Gold Support team created a special page in the hierarchy to contain the imported feature request status information. They called this page Gold Client Feature Requests.

  4. The Product Development team created a script to output a CSV file from the issue tracking system. The CSV file contains one row for each feature requested by a Gold-level client. It contains one column to contain each of the five fields described above.

  5. Together, the Gold Support team and the Product Development team wrote code to call the MindTouch API to create a MindTouch page for each row in the CSV file. They concatenated the Issue number and the short Description to be the page's title, and set the rest of the fields to appear in the body of the page.

  6. They set up a script to run the API calls each night.

When a Gold-level client calls their Gold Support agent to ask about a feature request, the Gold Support agent opens MindTouch, goes to the Gold Client Feature Requests page, and clicks the link that includes the issue number and the description. A page appears with the Status, Last Updated Date, and developer Comments, which the Gold Support agent can share with the client immediately.

How the Example Works

The code samples below show how to implement the Example Scenario.

CSV Import File

123444,Custom Report,In Progress,2014/02/10,Waiting on explanation from client about which users to include in the report.
124765,Reverse alphabetize users,Pending QA Approval,2014/02/14,Being reviewed by MBH.
125852,Fixing memory leak,Complete,2014/02/18,Approved by JS.
125898,Correcting CSS sidebar glitch,Pending QA Approval,2014/02/15,Developed by JH.
125900,Twitter embed tweak,In Progress,2014/02/16,Awaiting approval from Twitter.
125903,Update header to improve tracking,Pending QA Approval,2014/02/16,Developed by EK.
126375,Add switch to turn off video autoplay.,Pending QA Approval,2014/02/17,Developed by PP.
127123,Feedback form not displaying,Complete,2014/02/18,Approved by AW.
127214,Fix cache config for local development,Complete,2014/02/17,Approved by DC.
127294,Update Facebook API integration,In Progress,2014/02/18,Waiting on response from Facebook.


// Settings.
// Base URL of the MindTouch API.
define('API_URL', '');
// MindTouch username.
define('API_USERNAME', 'admin');
// MindTouch user password.
define('API_PASSWORD', '********');
// Name and path of CSV file being used for import.
define('CSV_FILE', 'csv_import_example.csv');
// Page ID of the MindTouch page to be the parent of the imported issues.
define('IMPORT_PARENT', 'Gold_Client_Feature_Requests');
// Edit time to overwrite existing pages. Format: YYYYMMDDhhmmss
define('EDIT_TIME', date('YmdHis'));

// Open the CSV file.
if (($handle = fopen(CSV_FILE, "r")) !== FALSE) {
    while (($data = fgetcsv($handle, 1000, ",")) !== FALSE) {
        // Store the issue's data.
        $issue_no = $data[0];
        $description = $data[1];
        $status = $data[2];
        $last_updated = $data[3];
        $comments = $data[4];

        // Build the page ID.
        $page_id = $issue_no . " - " . urlencode($description);
        if (IMPORT_PARENT !== '') {
            $page_id = IMPORT_PARENT . '/' . $page_id;
        // The MindTouch API requires page IDs to be URL encoded twice.
        $page_id = urlencode(urlencode($page_id));

        // Build the page content.
        $content = "<h3>Description</h3>\n<p>$description</p>\n<h3>Status</h3>\n<p>$status</p>\n<h3>Last Updated</h3>\n<p>$last_updated</p>\n<h3>Comments</h3>\n<p>$comments</p>\n";

        // Build the MindTouch API URL to create or update a page's content.
        $url = API_URL . "pages/=$page_id/contents?edittime=" . EDIT_TIME . "&overwrite=true";

        // Open curl.
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, $url);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_USERPWD, API_USERNAME . ":" . API_PASSWORD);
        curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
        curl_setopt($ch, CURLOPT_POSTFIELDS, $content);
        $output = curl_exec($ch);

API Components

The following API components are used in the code samples:

The following API documents may be useful as you extend this solution:

  • Was this article helpful?