ServiceNow® Versioning

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.

If you have multiple roles to set up and need to create different access controls it can be time-consuming to do that manually for each one. You can optionally run a JavaScript to 1) create a role with your specified name, 2) generate all required access control lists (ACLs) for the role, and 3) easily identify the ACL with an added description.

Since the following instructions take place on the ServiceNow side, they are intended to be a guide in getting you started. Be aware that the user interface and items such as labels, links, and options are subject to change over time. Please see ServiceNow documentation.

1. In the ServiceNow application, navigate to All > Scripts (i.e., System Definition - Scripts - Background).

2. In the Script field, paste the following code. Be sure to edit role name variable with the correct name (e.g., MadCap Connect).

   Copy

   // Set the role name before running the script!
       var roleName = 'MadCap Connect';
       
       var roleGr = new GlideRecord('sys_user_role');
       roleGr.addQuery('name', roleName);
       roleGr.query();
       
       if (roleGr.next()) {
           gs.info('Role ' + roleName + ' already exists. Exiting script.');
       } else {
           // Create the role
           roleGr = new GlideRecord('sys_user_role');
           roleGr.initialize();
           roleGr.name = roleName;
           roleGr.description = roleName;
           var roleSysId = roleGr.insert();
           gs.info('Created role: ' + roleName);
       
           var aclData = [
           {table: 'kb_knowledge_base', operation: 'read'},
           {table: 'kb_category', operation: 'read'},
           {table: 'kb_category', operation: 'create'},
           {table: 'kb_category', operation: 'write'},
           {table: 'kb_category', field: 'parent_table', operation: 'write'},
           {table: 'kb_category', field: 'parent_id', operation: 'write'},
           {table: 'kb_knowledge', operation: 'read'},
           {table: 'kb_knowledge', operation: 'create'},
           {table: 'kb_knowledge', operation: 'write'},
           {table: 'kb_knowledge', operation: 'delete'},
           {table: 'kb_knowledge', field: 'workflow_state', operation: 'write'},
           {table: 'kb_keyword', operation: 'read'},
           {table: 'kb_keyword', operation: 'create'},
           {table: 'kb_keyword', operation: 'write'},
           {table: 'kb_keyword', operation: 'delete'},
           {table: 'kb_knowledge_keyword', operation: 'read'},
           {table: 'kb_knowledge_keyword', operation: 'create'},
           {table: 'kb_knowledge_keyword', operation: 'write'},
           {table: 'kb_knowledge_keyword', operation: 'delete'},
           {table: 'label', operation: 'read'},
           {table: 'label', operation: 'create'},
           {table: 'label', operation: 'delete'},
           {table: 'label_entry', operation: 'read'},
           {table: 'label_entry', operation: 'create'},
           {table: 'label_entry', operation: 'write'},
           {table: 'label_entry', operation: 'delete'},
           {table: 'label_entry', field: 'table', operation: 'write'},
           {table: 'label_entry', field: 'table_key', operation: 'write'},
           {table: 'v_plugin', operation: 'read'},
           {table: 'sys_ws_definition', operation: 'read'},
           {table: 'sys_translated_text', operation: 'read'},
           {table: 'sys_translated_text', operation: 'create'},
           {table: 'sys_translated_text', operation: 'write'}
       ];
           // Create ACLs
           aclData.forEach(function(acl) {
               var gr = new GlideRecord('sys_security_acl');
               gr.initialize();
               gr.name = acl.table + (acl.field ? '.' + acl.field : '');
               gr.operation = acl.operation;
               gr.type = 'record';
               gr.description = roleName;
               var aclId = gr.insert();
       
               gs.info('Created ACL: ' + gr.name + ' (' + gr.operation + ')');
       
               // Add role to ACL
               var aclRoleGr = new GlideRecord('sys_security_acl_role');
               aclRoleGr.initialize();
               aclRoleGr.sys_security_acl = aclId;
               aclRoleGr.sys_user_role = roleSysId;
               aclRoleGr.insert();
           });
       
           gs.info('Completed creating role and ' + aclData.length + ' ACL records');
       }

3. Click Run Script.

   

If you run the above script, it replaces two "manual" steps:

• Creating a user role.

• Creating required access records in different tables and assigning a user role to them.