Module microsoft.sharepoint.lists

ballerinax/microsoft.sharepoint.lists Ballerina library

1.0.0

Overview

Microsoft SharePoint is a collaborative platform that enables organizations to create, manage, and share content, documents, and data through customizable sites, lists, and libraries deeply integrated with the Microsoft 365 ecosystem.

The ballerinax/microsoft.sharepoint.lists package offers APIs to connect and interact with the Microsoft SharePoint Lists API endpoints, specifically based on Microsoft Graph REST API v1.0.

Setup guide

To use the Microsoft SharePoint Lists connector, you must have access to the Microsoft SharePoint API through a Microsoft Azure developer account and obtain client credentials by registering an application in Microsoft Entra ID. If you do not have a Microsoft account, you can sign up for one at the Microsoft account sign-up page.

Step 1: Create a Microsoft Account and Set Up SharePoint Access

  1. Navigate to the Microsoft 365 website and sign up for an account or log in if you already have one.

  2. Ensure you have a Microsoft 365 Business Basic, Business Standard, Business Premium, or an Enterprise (E1, E3, or E5) plan, as SharePoint Online and its API capabilities are restricted to users on these plans.

Step 2: Register an Application and Generate Credentials

  1. Log in to the Microsoft Azure Portal using your Microsoft account credentials.

  2. In the left-hand navigation menu, select Microsoft Entra ID in the top search bar.

  3. In the left panel, navigate to App registrations and click New registration.

    New application registration

  4. Enter a name for your application, select the appropriate Supported account types (e.g., "Single tenant only"), and click Register.

    Application registration details

  5. Once the application is registered, note down the Application (client) ID and Directory (tenant) ID from the Overview page.

    Client ID and Tenant ID

  6. Navigate to Certificates & secrets in the left panel, click New client secret, provide a description and expiry period, then click Add. Copy the generated client secret value immediately.

    Create client secret

  7. Navigate to API permissions in the left panel and click Add a permission.

    Add API permission

  8. Select Microsoft Graph from the available API options.

    Microsoft Graph API permission

  9. Select Application permissions, then search for and add the following permissions depending on your use case, then click Add permissions.

    PermissionOperations covered
    Sites.Read.AllRead sites, lists, columns, content types, drives, analytics
    Sites.ReadWrite.AllCreate and update lists, list items, drives, and content
    Sites.Manage.AllUpdate site properties, create/delete columns and content types
    Sites.FullControl.AllManage site permissions

    Tip: Grant only the permissions your application actually requires. For read-only use cases, Sites.Read.All is sufficient. For full connector coverage, add all four.

    API site permissions

  10. Click Grant admin consent to approve the permissions for your organization.

    Grant admin consent

  11. Construct the tokenUrl using the Directory (tenant) ID obtained in step 5:

Copy
https://login.microsoftonline.com/<TENANT_ID>/oauth2/v2.0/token

This is the OAuth 2.0 token endpoint the connector uses to exchange your clientId and clientSecret for an access token with the https://graph.microsoft.com/.default scope.

Quickstart

To use the microsoft.sharepoint.lists connector in your Ballerina application, update the .bal file as follows:

Step 1: Import the module

Copy
import ballerinax/microsoft.sharepoint.lists;

Step 2: Instantiate a new connector

  1. Create a Config.toml file and configure the credentials obtained above:
Copy
clientId = "<CLIENT_ID>"
clientSecret = "<CLIENT_SECRET>"
tokenUrl = "https://login.microsoftonline.com/<TENANT_ID>/oauth2/v2.0/token"
  1. Instantiate a lists:Client with the obtained credentials.
Copy
configurable string clientId = ?;
configurable string clientSecret = ?;
configurable string tokenUrl = ?;

final lists:Client listsClient = check new ({
    auth: {
        clientId,
        clientSecret,
        tokenUrl,
        scopes: "https://graph.microsoft.com/.default"
    }
});

Step 3: Invoke the connector operation

Now, utilize the available connector operations.

Create a new list

Copy
public function main() returns error? {
    lists:MicrosoftGraphList newList = {
        displayName: "Project Tasks",
        list: {
            template: "genericList",
            contentTypesEnabled: false
        }
    };

    lists:MicrosoftGraphList response = check listsClient->createList("contoso.sharepoint.com,abc123,def456", newList);
}

Step 4: Run the Ballerina application

Copy
bal run

Examples

The microsoft.sharepoint.lists connector provides practical examples illustrating usage in various scenarios. Explore these examples, covering the following use cases:

  1. Compliance snapshot verification - Demonstrates how to capture and verify compliance snapshots of SharePoint list data.
  2. Sharepoint webhook subscription lifecycle - Illustrates creating, verifying, and extending SharePoint webhook subscriptions to manage event-driven notifications.
  3. Content type compliance audit - Demonstrates how to audit SharePoint list items for adherence to expected content type configurations.
  4. Stale items archival audit - Illustrates identifying and archiving stale items from SharePoint lists based on inactivity criteria.

Import

import ballerinax/microsoft.sharepoint.lists;Copy

Other versions

1.0.0

Metadata

Released date: 3 days ago

Version: 1.0.0

License: Apache-2.0


Compatibility

Platform: any

Ballerina version: 2201.12.0

GraalVM compatible: Yes


Pull count

Total: 3

Current verison: 3


Weekly downloads


Source repository


Keywords

Area/Storage & File Management

Vendor/Microsoft

Name/Microsoft SharePoint Lists

SharePoint

Type/Connector


Contributors