User Tools

Site Tools


siam_sharepoint

Perspectium SIAM for Sharepoint

(Importing Microsoft Sharepoint 365 Articles to ServiceNow Knowledge Articles)

v3.18.0

This integration imports entire Microsoft Sharepoint 365 sites and its sub-sites, lists, and pages to create ServiceNow Knowledge Base articles. This integration allows you to continuously update your ServiceNow Knowledge base with content from Microsoft Sharepoint 365 in a scheduled manner so that articles that are created or updated will be updated in ServiceNow in an automated fashion. This allows the enterprise IT and its self service customers to search and comment on articles within the ServiceNow Knowledge Base that are created in Microsoft Sharepoint.

The following is an architectural diagram of the integration.

This integration is currently one direction from Sharepoint to ServiceNow

Supported Versions

  • ServiceNow: Kingston and previous
  • Sharepoint 365 2013

Installation

Please request installation download links from support@perspectium.com. For more information on installing or updating the update sets, visit the first time install or updating pages.

The update sets should be installed in this order:

  1. Perspectium for ServiceNow
  2. Perspectium Common Endpoint
  3. Perspectium Common Knowledge
  4. Perspectium SIAM for Sharepoint

Once all three update sets have been installed the Perspectium app in the ServiceNow menu should show the Sharepoint SIAM module.

Configuration

Service Provisioning

Contact support@perspectium.com requesting provisioning of this integration. You will be asked the ServiceNow instance name for the service configuration. In return, you will be given links via email to download the required update sets.

If you have been previously provisioned for other Perspectium products please let support know at this time.

Properties

If you have previously installed Perspectium products, you would have already provisioned default properties for connectivity and can skip step 1. If you have previously provisioned Replicator previously, you should skip step 2.

  1. Sharepoint Properties
  2. Shared/Subscribe Queues (depends on service destination)
Sharepoint Properties

  • The default knowledge base is used for all newly created knowledge articles from an import. After updating the knowledge article to your knowledge base, this value will not be changed by the import on subsequent runs.
  • Next, the base URL property to your sharepoint site so that incoming articles will be updated to have absolute URLs pointing to your Sharepoint site
  • Following this are the credentials needed for a REST service login at your Sharepoint site for the integration
Shared/Subscribe Queues

You do not need to configure Shared/Subscribe Queues if your Sharepoint integration service is on the default endpoint that you have already configured. Perspectium support will let you know.

If you have been provisioned for other Perspectium services, you may be required to create separate Share/Subscribe queues if your other services do not reside on the same endpoint. Perspectium support will be aware and provide you with the necessary credentials to create these configurations at the time of provisioning.

Follow the instructions on creating shared queues and enter the endpoint and credentials given to you, you should have an entry that is similar to the following.

Similarly, follow the instructions to create subscribe queues, and enter the credentials given to you, you should have something similar to the following.

Usage

The Sharepoint integration takes advantage of Sharepoint's “Site”, 'List“, and “Pages” hierarchy. The integration will discover and import your Sharepoint Sites, their Sub-Sites, and corresponding Lists so that you can select and activate only the Sites and Lists you wish to import from. The following is a screenshot of the installed application in ServiceNow.

The following are the steps to get your Sharepoint hierarchy imported and configured to import your knowledge articles.

  1. Configure Properties
  2. Select “Discover sites and lists” and wait for the sites to be discovered and populated (this can take up to a minute)
  3. Select “Sharepoint Sites” and drill down to specific sub-site or directly to a List
  4. Double click and activate the “Import articles” field on the list
  5. At this point you may wish to select the “Import now” UI action on the List or select the “Import articles from all active lists” UI action on the Site

Each action you select produces a Topic=siam, Type=sharepoint message in the Outbound messages table of Replicator. Responses from the integration service will appear in the Inbound messages table with the same Topic and Type. Error messages will appear in the Inbound message table as well if they occurred at the service endpoint.

Default Knowledge Base

When discovering sites, the default knowledge base set in the Properties page will be used.

By design, the default is “Sharepoint Imports” which is a new knowledge base that is installed part of the update set. Knowledge authors should look in this knowledge base to reassign to the appropriate knowledge base after an import has occurred or if a scheduled import has run.

You may also change this property to another default knowledge base if you want all new imports to be assigned to this one.

Default Knowledge Category

After a discovery of the Sharepoint site and sub-sites, site records such as the following will be created under the “Sharepoint sites” module.

The “Assign Category” field would be blank on creation. Select the category (from kb_category table) that you would want subsequent imports of this site to automatically assign the category to the articles. By default if left blank, will not overwrite any imported articles that have been manually categorized.

List Types

Perspectium Replicator for Sharepoint supports importing Sharepoint articles of type Item and FAQ. For example, on a discovered Sharepoint List entry, select the Source of FAQ if you know the list you have in Sharepoint is an FAQ list.

Inbound Maps

The Inbound Maps module actually refer to an Import Set Transform Map which describes the field mappings from common_knowledge to kb_knowledge table. The default coalesce is on topic and description fields which are mapped from the Sharepoint Site name which can contain the main site and its sub-site e.g. /mainsite/sub-site/ and the article title together.

The inbound updates will ignore updating the kb_knowledge_base and short_description fields on subsequent updates. The rest of the fields in the map will copy over unless its blank, because “Copy empty fields” option is false by default.

CSS Styles

Often times, you want to apply CSS styles from your Sharepoint site on your newly created knowledge articles. You can do so by by creating a new Content Management → Style Sheets entry and linking to it in the System UI → UI Pages → kb_view UI page.

You can download your Sharepoint style by accessing it using the following URL

https://[your tenant site].sharepoint.com/_layouts/15/1033/styles/Themable/corev15.css

Copy the content of the CSS page and create a new Style Sheet record. Next, copy the sys_id of the newly created Style Sheet entry and use it to paste the following HTML

<link href="[the sys_id of your Sharepoint Style Sheet].cssdbx" rel="stylesheet" type="text/css"/>

Paste it into the top part of the kb_view (or kb_view_customer in Knowlegde V3) UI page like this:

When you view your knowledge article next time, you will be able to see your Sharepoint styles being applied.

The Sharepoint CSS you have added this way will actually be applied to all articles, whether or not it was imported from Sharepoint.

Content from Sharepoint

Dubnium

By default, the text area of your Sharepoint's Knowledge articles contains the URL to the item in your Sharepoint site unless it is part of the Wiki Page Library.

Currently, it is not possible to pull the list's item content in a general case as its field name depends on what the column name is first set as. Even if the user changes the column name, the field name will remain the same.

Here is an example:

The content for “Perspectium List 1: Lab Exercise” is stored as:

 <d:Here_x005f_x0020_x005f_is_x005f_x0020_x005f_a_x005f_x0020_x005f_sing>I added this text after lunch</d:Here_x005f_x0020_x005f_is_x005f_x0020_x005f_a_x005f_x0020_x005f_sing>

If you want the actual content to be displayed in your Knowledge articles, you would need to contact support@perspectium.com and include the all the field names for all lists in your Sharepoint to change your mappings. To do so, follow these steps:

To check which records are libraries or lists in your instance:

  1. Go to your instance and go to “Sharepoint Lists”
  2. Click on the gear icon in Sharepoint Lists.
  3. Make sure “Library” is in “Selected”
  4. Click OK. Records that have the value false in the Library column are lists. Records that have the value true in the Library column are libraries.
  5. Show records that have a false value in the Library column by right-clicking the value and click on “Show Matching” on false or “Filter Out” on true

There are some records on your instance that are not your custom lists in Sharepoint but is part of Sharepoint. You can include columns from all lists or just your custom lists. If you don't include columns from other lists, the articles that get imported to your instance will have the text area be blank.

To get the field names:

  1. In your browser, access:
    <Sharepoint site name>/_api/web/lists/GetByTitle('<list name>')/items(<item #>)/FieldValuesForEdit

    This is where you would see a XML document for your list. Make sure the <list name> is in quotes. Also, for the item #, try to use '1' (without quotes) first. If it does not work, try other positive numbers like 2 and 3 until you can see a XML document.

    Example:

    https://perspectiumdev.sharepoint.com/travel/_api/web/lists/GetByTitle('New list coming out')/items(2)/FieldValuesForEdit
  2. Find the field name by looking for the exact content that matches one of your list's items. It is usually in the form:
     <d:field_name>content</d:field_name> 

  3. Copy down the field name that surrounds the content
  4. If you have multiple columns, repeat the steps 2 -3 for the other column. Usually, the columns are adjacent to each other. Also, make sure the field names are in the correct order as in your actual list when copying it down.
  5. Repeat all steps for other lists

This would not work with Libraries, where they contain actual files.

If you have items with column values that goes through multiple lines, make sure you have setting that column to “Enhanced Rich Text” on Sharepoint. Here is how you access this setting on Sharepoint:

  1. Go to a list with columns that goes through multiple lines
  2. Click on the gear icon on the upper right and click on “List Settings
  3. Scroll down to the “Columns” section
  4. Click on the column that has type “Multiple lines of text”
  5. Go to the section “Additional Column Settings” and select “Enhanced rich text” if it is not already selected.
  6. Click on “OK” to save your settings

Next, you will need to transform the content from the messages you would receive after importing articles.

  1. In ServiceNow, go to Inbound Maps under Sharepoint SIAM and click on PSP Common Knowledge.
  2. In the Field Maps table, click u_text.
  3. Check the Use source script checkbox.
  4. Follow the instructions for one of the two options described below:

Option 1 - URL

To have just the URL and the item, copy and paste the following:

function escapeRegExp(str) {
    return str.replace(/([.*+?^=!:${}()|\[\]\/\\])/g, "\\$1");
}

function replaceAll(str, find, replace) {
  return str.replace(new RegExp(escapeRegExp(find), 'g'), replace);
}

function prefixURL(text) {	
    var pv = pspUtil.getPspPropertyValue("com.perspectium.siam.sharepoint.base_url", "unknown");
	
	if (pv == "unknown")
		return text;
	
	if(!pv.endsWith("/"))
		pv = pv + "/"; // endsure that URL endswith "/"
	
	if (text.indexOf("<a href=\"/") > 0)
		text = replaceAll(text, "<a href=\"/", "<a href=\"" + pv );
	
	if (text.indexOf(" src=\"/") > 0)
		text = replaceAll(text, " src=\"/", " src=\"" + pv );
	
	return text;
}

function defaultTransformEntry(source) {

	// if there is no text, insert the origin URL to page
	if (!source.u_text.nil())
		return prefixURL(source.u_text.toString()); // return the value to be put into the target field
	
	var olink = "<p><a title='" + source.u_origin + "' href='" + source.u_origin + "' target='_blank'>" + source.u_origin + "</a></p>";
	return olink;
}

answer = defaultTransformEntry(source);

Option 2 - Actual Content

To have the item's actual content, copy and paste the following (Make sure you have changed your mapping with support):

function escapeRegExp(str) {
    return str.replace(/([.*+?^=!:${}()|\[\]\/\\])/g, "\\$1");
}

function replaceAll(str, find, replace) {
  return str.replace(new RegExp(escapeRegExp(find), 'g'), replace);
}

function prefixURL(text) {	
    var pv = pspUtil.getPspPropertyValue("com.perspectium.siam.sharepoint.base_url", "unknown");
	
	if (pv == "unknown")
		return text;
	
	if(!pv.endsWith("/"))
		pv = pv + "/"; // endsure that URL endswith "/"
	
	if (text.indexOf("<a href=\"/") > 0)
		text = replaceAll(text, "<a href=\"/", "<a href=\"" + pv );
	
	if (text.indexOf(" src=\"/") > 0)
		text = replaceAll(text, " src=\"/", " src=\"" + pv );
	
	return text;
}

function defaultTransformEntry(source) {

	// if there is no text, insert the origin URL to page
	if (!source.u_text.nil())
		return prefixURL(source.u_text.toString()); // return the value to be put into the target field
	
	var olink = "<p><a title='" + source.u_origin + "' href='" + source.u_origin + "' target='_blank'>" + source.u_origin + "</a></p>";
	return olink;
}

answer = (function contentTransformEntry(source) {
			if (source.u_origin.indexOf('DispForm.aspx?ID') == -1 || source.u_text.nil()) {
				return defaultTransformEntry(source);
			}
			
			var text = source.u_text.toString();
			var formatContent = text.split(/<p><\/p>|<p>nbsp;<\/p>/);
			var content = "";
	
			// removes empty strings
			formatContent = formatContent.filter(Boolean);
	
			for (var i = 0; i < formatContent.length; i++) {
				content += formatContent[i];
			}
			
			return content;
})(source);

To revert back to your default settings, e-mail support@perspectium.com to change your Field Map and use the URL.

siam_sharepoint.txt · Last modified: 2018/08/24 15:07 by timothy.pike