This manual is divided into several sections, each focusing on a specific aspect of the SharePoint-Kognitos integration.

Introduction

The integration of SharePoint with Kognitos offers a powerful and intuitive way to interact with SharePoint data and functionalities. This integration enables users to perform a wide range of operations on SharePoint items, including connecting to SharePoint, retrieving files and folders, uploading and moving files, and converting data to SharePoint-compatible formats, all through the use of Kognitos’ natural language processing capabilities. This section provides an overview of the SharePoint-Kognitos integration and outlines the prerequisites for using SharePoint on Kognitos.

Prerequisites for Using Kognitos with SharePoint

Before you can start using Kognitos to interact with SharePoint, there are several prerequisites that need to be met:

Kognitos Account: You need to have an active Kognitos account. If you do not have one, you can sign up for a Kognitos trial account to get started.
SharePoint Account: You need to have an active SharePoint account. If you do not have one, you can sign up for a SharePoint trial account to get started.
API Access: Ensure that your SharePoint account has API access enabled. API access is required for Kognitos to communicate with SharePoint.
Client ID and Client Secret: Obtain your SharePoint client ID and client secret, which are used to authenticate API requests. You can find these in your SharePoint app registration settings.
Tenant ID: Obtain your SharePoint tenant ID, which is used to identify your SharePoint instance. This can be found in your SharePoint admin center.
Basic Understanding of SharePoint Items: While Kognitos simplifies interactions, having a basic understanding of SharePoint items (e.g., files, folders, lists) and their relationships will help you automate more effectively with Kognitos.

Once these prerequisites are met, you are ready to start leveraging the power of Kognitos to enhance your SharePoint experience, making it more accessible, efficient, and customizable.

Setting Up SharePoint Connection

Kognitos supports integration with Microsoft SharePoint via the Microsoft Graph APIs. Access is generally provided using app registration without a user via Entra ID (formerly Azure AD). This section outlines the credentials required for this connection and provides a detailed, step-by-step guide to connect successfully.

Required Credentials

To connect to SharePoint, you will need the following credentials (these are provided when enabling the integration in the platform or when first interacting with SharePoint, depending on the flow in use):

SharePoint Client ID: The client ID associated with your SharePoint app registration.
SharePoint Client Secret: The client secret associated with your SharePoint app registration.
SharePoint Tenant ID: The tenant ID of your SharePoint instance.

See below for more information on obtaining the above information. In addition, when using the integration, URLs for the resources you would like to access, create, and otherwise mutate within SharePoint are required.

Resources Accessed

The Kognitos SharePoint integration accesses the following types of resources via the Microsoft’s Graph APIs:

Drives/files (listing of files and folders, file uploads and downloads, file moves, file deletes) - by drive id
Sites (for accessing, updating, and deleting lists) - by site id

Access Pattern

Once the SharePoint integration has been configured in the Kognitos platform, the platform stores the provided client id, secret, and tenant. These are then used whenever access to SharePoint is requested by a running automation to obtain an temporary access token via a request to Microsoft’s auth endpoint. The given token is then used for that particular automation run.

The stored information can be removed or updated whenever desired from within the Kognitos platform. Only automations within the customer department where SharePoint has been configured have the ability to make SharePoint requests using the configured client id and secret.

Configuring Access

To obtain a client id, secret, and tenant id:

Login to portal.azure.com and click on “Microsoft Entra ID” under “Azure services”
Click on “App registrations”, on the left hand menu, then “New registration” on the top menu, and enter a name; the defaults should be acceptable for other fields
After the app registration is created, note the Application (client) ID and Directory (tenant) ID entries shown - these are the Client ID and Tenant ID values Kognitos requires.
Next, provision a client secret by clicking on “Add a certificate or secret”, then “New client secret”

Add a name and expiration timeline as desired - note that a new secret will have to be provided on the Kognitos platform once this secret expires. Note the Value column for the created secret - this is the Client Secret value Kognitos requires.
Lastly, add permissions for the app registration. Click on “API permissions”, then “Add a permission”, and select “Microsoft Graph”. Select “Application permissions”, then select permissions for sites. If desired it is possible to use the “Sites.Selected” permission instead of the broader set shown below - there are however extra steps required in this case to grant access to the desired sites. Please see Microsoft’s documentation for more details on this. Be sure to grant admin consent for the permissions you add.

Now that you have configured the access, you should be able to integrate Sharepoint with Kognitos

Learning the Sharepoint book (Integration)

Gather Credentials: Ensure you have all the required credentials: Client id, Client secret, Tenant id
Navigate to the Department tab of Kognitos and select the Salesforce book to learn.

Click on + Book button on the right of the card
Add in the credentials when you are prompted

Note: In case you see Test and Production credentials separately you can add both. If you don't have two sets of credentials you can use the same credentials in both.

Successful integration: Once the book has been learnt successfully, you are ready to perform various operations on SharePoint. You can now fetch data, create new records, update existing ones, delete records, manage files, and more.

Working with SharePoint Items

Interacting with SharePoint items is a core functionality when integrating SharePoint with Kognitos. This section covers how to fetch data, create and modify SharePoint items, and delete them when necessary.

Retrieving SharePoint Items

To retrieve items from SharePoint, you can use the following commands:

Fetching a File

get sharepoint's file whose url is "<file-url>"

Example:

get sharepoint's file whose url is "https://company.sharepoint.com/sites/ProjectX/Documents/file.docx"

Fetching Files from a Folder

get a folder at <folder-url>
get the folder's files

find the files from sharepoint whose folder is <folder-url>

Example:

get a folder at "https://company.sharepoint.com/sites/ProjectX/Documents"
get the folder's files

find the files from sharepoint whose folder is "https://kognitostest.sharepoint.com/sites/ProjectX/Shared%20Documents/"

Fetching Specific Files from a Folder

get a folder at <folder-url>
get the folder's files whose url is "<folder-url>/file-name"

Example:

get a folder at "https://company.sharepoint.com/sites/ProjectX/Documents"
get the folder's files whose url is "https://company.sharepoint.com/sites/ProjectX/Documents/file.docx"

Uploading a File to Sharepoint

# once you have located a folder in sharepoint
# and once you have access a file (can be pdf, Excel sheet, csv, image, etc)

upload the file to the folder where
  the filename is "boarding-pass.xlsx"

Deleting a File

delete a file at "https://yoursharepointlink.com/sites/FILE_PATH"

Creating and Retrieving a Folder

To create or retrieve a folder in SharePoint, use the following commands:

get a folder at "https://company.sharepoint.com/sites/ProjectX/Documents/FolderName"

Example:

get a folder at "https://company.sharepoint.com/sites/ProjectX/Shared Documents/NewFolder"

Uploading a String to a Folder

To upload a string (file content) to a folder in SharePoint, use the following command:

get a file at "<file-url>"
get a folder at "<folder-url>"
upload the file to the folder where
  the filename is "<new-filename>"

Example:

get a file at "https://company.sharepoint.com/sites/ProjectX/Documents/file.docx"
get a folder at "https://company.sharepoint.com/sites/ProjectX/Documents"
upload the file to the folder where
  the filename is "newfile.docx"

Getting a Folder

To get a folder, you need the URL to the folder you want:

get a folder at "https://kognitosinc.sharepoint.com/sites/PresalesDemos/Shared%20Documents/ExcelFiles"

The formatting of the URL is very important, for example:

This is the URL we use in the automation:
https://kognitosinc.sharepoint.com/sites/PresalesDemos/Shared%20Documents/ExcelFiles

This is the URL if I were to copy from the browser:
https://kognitosinc.sharepoint.com/:f:/s/PresalesDemos/EjGzzRsBoEVGrts4Y6gCUMIB4TXvUy4Q3oN5QMC79wqTTg?e=bGA6dL

So please note, the URL as is when you copy from Sharepoint is formatted differently than the one we use in our automations!

Deleting a Folder

delete a folder at "https://test.sharepoint.com/sites/YOUR_FOLDER_PATH"

Moving a File to a Folder

To move a file to a different folder in SharePoint, use the following command:

get the file at "<file-url>"
get the folder at "<folder-url>"
move the file to the folder

Example:

get the file at "https://company.sharepoint.com/sites/ProjectX/Documents/file.docx"
get the folder at "https://company.sharepoint.com/sites/ProjectX/Archives"
move the file to the folder

Converting Data to SharePoint String

To convert data into a SharePoint-compatible string format, use the following commands:

get the document metadata
get the metadata as a sharepoint string

Example:

the list item is {"Title": "New Item", "Body": "This is a new item."}
get the list item as a sharepoint string

Glossary of Terms

API (Application Programming Interface): A set of rules and protocols for building and interacting with software applications. SharePoint API allows external services like Kognitos to communicate with SharePoint to retrieve or modify data.
SharePoint Client ID: A unique identifier for your SharePoint app registration, used for API authentication.
SharePoint Client Secret: A secret key associated with your SharePoint app registration, used for API authentication.
SharePoint Tenant ID: A unique identifier for your SharePoint instance, used to identify your organization’s SharePoint environment.
SharePoint Item: An entity within SharePoint, such as a file, folder, or list item.
SharePoint Record: A single data entry within a SharePoint list or library.

By following these guidelines, you can effectively manage SharePoint items in Kognitos, from fetching and creating records to updating and deleting them as needed.