Breadcrumbs

PortalTalk Customer API usage

Introduction

PortalTalk offers various interfaces for users to interact with the application, including a web application for browsers and an MS Teams app for full integration within MS Teams and SharePoint Web Parts. These integrations enable end users to engage with the application in their daily tasks.

Additionally, the PortalTalk API allows programmatic interaction with PortalTalk services, offering various functions for seamless integration.

Typical use of the PortalTalk API

The PortalTalk API can automate tasks from other systems and extract information to feed automated systems.

Typical scenarios for using the PortalTalk API include:

  1. An ERP/CRM/EPM system that requires a document workspace. When creating a new project, a project workspace is simultaneously created in SharePoint or MS Teams, including provisioning for the default configuration.

  2. Accessing PortalTalk API functions from a PowerShell script. QS Solutions provides basic scripts that can be adapted to meet specific needs. Using a script, you can batch create sites or teams, add owners and members, register in PortalTalk under a category, and provision immediately.

Reference PortalTalk API functions

PortalTalk Generic
Applicable for both MS Teams and SharePoint workspaces

  • GetWorkspaceAppID

    • Converts workspace names to the unique workspace GUID ID registered by PortalTalk, used in subsequent functions to select the correct workspace.

      • AddMember

        • Adds a member to workspaces via API.

      • GetMember

        • Selects a specific member of a recipient workspace.

      • RemoveMember

        • Removes a member from a workspace.

      • AddOwner

        • Adds a user as an owner of a workspace.

      • RemoveMember

        • Removes a member.

      • GetMembers

        • Retrieves the list of members from a recipient workspace.

      • Archive

        • Archives a workspace.

      • UnArchive

        • Unarchives a workspace and reactivates it.

MS Teams

  • CreateMSTeam

    • Creates an MS Team under a PortalTalk category and assigns a user as owner.

  • ImportMsTeam

    • Imports an existing team and registers it under a PortalTalk category.

SharePoint

  • CreateSPsite

    • Creates a SharePoint site under a PortalTalk category.

  • ImportSPsitecollection

    • Import an existing SharePoint site without group to register in PortalTalk. No permissions are changed

  • ImportSPsitecollection+group

    • Import an existing SharePoint site with a group to register in PortalTalk. No permissions change; only the MS365 group permissions are removed from the SharePoint site. This is due to PortalTalk's unique feature that supports role-based access, including the MS365 group.

Example: Instruction to use the PortalTalk API for MS Teams

Introduction

This document outlines how to perform various actions in batch using the PortalTalk API for MS Teams.

Requirements

To use the Import API, ensure you have the following software components installed:

  • PowerShell 7.x

  • Visual Studio Code

  • PowerShell Plugin for Visual Studio Code

  • PnP.PowerShell

App registration

First, create an app registration in the customer's tenant to obtain an access token for the routine:

  1. Go to portal.azure.com and log in with a customer account.

  2. Navigate to Azure Active Directory.

  3. Click on "App registrations" in the left navigation.

Then click on "New registration".

  • Enter "PortalTalk Access Token" as the name.

  • Click "Register".

  • The app registration is created, and you will see the Overview page.

  • Copy the Application (client ID) and record it (e.g., in Notepad) for later use.

  • Click on "Certificates and secrets".

  • Click on "New client secret".

  • Provide a description and define the expiration time for the Client Secret.

  • Click "Add". The registration is now created.

Copy the value of the Client Secret and record it (e.g., in Notepad) for later use. This cannot be retrieved later.

Create MS Teams API

This section explains how to create MS Teams in batch via the API and assign them to a category in PortalTalk.

  1. Ensure a category of the type "MS Team" exists in PortalTalk.

  2. Find the Category ID. You can easily see this by opening PortalTalk in the browser and selecting a category. The URL will display your Category ID.

Create a Single Team

  1. Download the PowerShell Script "PT365API_CreateMSTeam.ps1" from the provided zip file and place it in a folder on your system.

  2. Open the script in Visual Studio Code.

  3. Change the values in the "tenant environment parameters" and "parameters" sections.

  4. Run the script to create the Team.

Create multiple MS Teams via a CSV file

  1. Download this file: PT API example scripts Create MS Teams.zip.

  2. Unzip the file to obtain the script "PT365API_CreateMSTeam with CSV.ps1" and the CSV file "CreateMSTeams.csv".

  3. Place them in a folder on your system.

  4. Open the script in Visual Studio Code.

  5. Change the values in the "tenant environment parameters" and "parameters" sections.

  6. Customize the CSV file with the desired values.

  7. Run the script to create the MS Teams.


Need help!

We have much more information available te help you to understand how the API functions can be used for your specific scenario. Also example PowerShell scripts of all functions are available to share with you. If needed, please contact us a sc.portaltalk@qssolutions