Before You Start Publishing to ServiceNow®

In each table mentioned below, create the following Access Control Records with the MadCap Connect role added to them:

• kb_knowledge (to publish and delete stale topics)

  • kb_knowledge: create (see example below)

  • kb_knowledge: read

  • kb_knowledge: write

  • kb_knowledge: delete

  • kb_knowledge.workflow_state: write

• kb_category (to create categories when the "Use TOC to define categories" destination option is enabled)

  • kb_category: create

  • kb_category: read

  • kb_category: write

  • kb_category.parent_id: write

  • kb_category.parent_table: write

• kb_knowledge_base (to read available knowledge bases on the ServiceNow instance and populate them in the Default Knowledge base destination options)

  • kb_knowledge_base: read

• kb_keyword (to generate and remove stale ServiceNow keywords)

  • kb_keyword: create

  • kb_keyword: read

  • kb_keyword: write

  • kb_keyword: delete

• kb_knowledge_keyword (this is necessary for ServiceNow keywords with article association)

  • kb_knowledge_keyword: create

  • kb_knowledge_keyword: read

  • kb_knowledge_keyword: write

  • kb_knowledge_keyword: delete

• label (to generate and remove stale ServiceNow tags)

  • label: create

  • label: read

  • label: delete

• label_entry (to generate and remove stale ServiceNow tags and their association with articles)

  • label_entry: create

  • label_entry: read

  • label_entry: write

  • label_entry: delete

  • label_entry.table: write

  • label_entry.table_key: write

• v_plugin (multilingual output publishing and article versioning)

  • v_plugin: read

• sys_translated_text (multilingual output publishing)

  • sys_translated_text: create

  • sys_translated_text: read

  • sys_translated_text: write

• sys_ws_definition (article versioning)

  • sys_ws_definition: read

1. Install the Knowledge Management Advanced plugin. Click here.

   Note This plugin is installed by default since the Xanadu ServiceNow instance. For older instances you will have to install the plugin for article versioning to work.

2. In the ServiceNow application, navigate to Knowledge > Administration > Properties, and from Knowledge Management Properties, select Enable article versioning feature (set it to Yes).

   Note This option in ServiceNow properties will not display unless the Knowledge Management Advanced plugin is installed.

3. Create a custom endpoint with the name “MadCap Connect API” in a new REST API.

   Note This step is required for the Flare Desktop side to support article versioning. As the Flare Desktop user, you need to provide the JavaScript code to your ServiceNow administrator to complete on the ServiceNow side.

   1. From System Web Services, click REST, and Scripted REST APIs.

   2. Click New.

   3. Provide a name for the REST API. It must be MadCap Connect API.

   4. In the new REST API, navigate to Resources related list, and click New.

   5. Ensure the following fields are set:

      • Name MadCap Connect API

        Note This will associate the custom endpoint with the JavaScript function.

      • Relative Path /{action}/{sys_id}

      • HTTP Method POST

   6. In the Script field of the resource, paste the following code. (Provide this code to your administrator.)

      Copy

      (function process(request, response) {
          var action = request.pathParams.action;
          if (!action)
              return new sn_ws_err.BadRequestError('Missing action parameter');
          action = action.toLowerCase();
      
          if (action === 'status') {
              var plugin = new GlideRecord('v_plugin');
              var pluginFound = plugin.get('id', 'com.snc.knowledge_advanced');
      
              // {plugin_active: active|inactive|unknown, feature_enabled: true|false|unknown}
              return {
                  plugin_active: pluginFound ? plugin.getValue('active') : 'unknown',
                  feature_enabled: gs.getProperty('glide.knowman.versioning.enabled', 'unknown')
              };
          }
      
          var sysId = request.pathParams.sys_id;
          if (!sysId)
              return new sn_ws_err.BadRequestError('Missing sys_id parameter');
          var topic = new GlideRecord('kb_knowledge');
          if (!topic.get(sysId))
              return new sn_ws_err.NotFoundError('No record found');
      
          var kbVersioning = new KBVersioningSNC();
          var result;
          switch (action) {
              case 'checkout':
                  result = kbVersioning.checkout(topic, false);
                  if (result)
                      return { "sys_id": result.sys_id.toString() };
                  return new sn_ws_err.ServiceError('Checkout operation failed');
              case 'recall':
                  kbVersioning.recall(topic);
                  return { "sys_id": topic.sys_id.toString() };
              default:
                  return new sn_ws_err.BadRequestError('Invalid action. Supported methods are: status, checkout and recall');
          }
      })(request, response);

   7. Save.