The Wizdom API is a RESTful API with a JSON payload that can be used to access Wizdom services from external applications. The details about the API can be found in the Wizdom Configuration Center under the specific module. Read more about connecting to Azure AD-secured APIs in SharePoint Framework solutions here.
The following Wizdom modules come with public API’s, which you can find in the Configuration Center:
- Course Management
- Mega Menu
Typical use cases
- Creating a flow for the Projects module to automatically upload document templates as part of the project site creation process
- Create web application consuming Wizdom services
- Building Native mobile applications
- Create custom endpoints
- Request additional data in a webhook event or custom site template
The Wizdom API uses OAuth 2.0 to handle authentication and authorization. Before using the Wizdom API an Azure Active Directory application with correct permission scope needs to be created. This app will provide the authentication service for accessing the Wizdom API.
Wizdom endpoints require 2 headers to complete the requests successfully.
- “Authorization”, “Bearer [oauth access token]”
- “x-wizdom-rest”, “app01”
Visual Studio 2017 / .NET web application sample
This section will provide a sample on how to use the Wizdom API. In about ten minutes you’ll have a simple .NET web application that makes requests to the Wizdom API and receives news items from the Wizdom Noticeboard service.
The sample uses authorization code grant type. This is a redirection-based flow which is the most commonly used because it is optimized for server-side applications, where source code is not publicly exposed, and secret confidentiality can be maintained.
Authorization code grant type only work because this is a web application. The web application is capable of interacting with the user-agent (i.e. the user’s web browser) and receiving API authorization codes that are routed through the user-agent. Console applications does not have this capability and you will need to use resource owner password credentials grant type.
To see an example using resource owner password credentials grant type, please refer to the webhook sample.
- Visual Studio 2017
- Office 365 site collection with Wizdom installed
Step 1: Create a .NET web application
Create ASP.NET (Web Application) and choose WebAPI, no authentication
Step 2: Setup the Azure Active Directory Application
1. Navigate to the Azure Portal (https://aad.portal.azure.com) logged in as your tenant admin.
2. Navigate to Azure Active Directory > App Registrations
3. Add app (new application registration).
4. Give it a name and choose Application Type: Web app / API
5. Enter the url of your previously created webapplication (ex. http://localhost:51191/)
6. Add webapplication + /auth to reply urls (ex. http://localhost:51191/auth)
7. Assign required permissions (delegated and application)
Azure AD: Read Directory data
SharePoint: Read Items in all site collections + Read user profiles
Yammer: Read and Write
8. Create Key and save/copy it.
9. Press the “Grant Permissions” button.
Step 3: Setup the sample
1. Find your noticeboard view id by loading a page with the Wizdom Noticeboard webpart. View the network trace and look for a url containing: /api/wizdom/noticeboard/views/[guid]. Copy the guid: (ex. 36534921-ce5b-487b-9e66-5776cab4d504)
2. Add app settings to the web.config. Replace the values in brackets.
3. Add an empty MVC 5 controller to the project. Name it AuthController
4. Install nuget package: Install-Package System.IdentityModel.Tokens.Jwt -Version 5.1.4
5. Replace the Index() method with this code and resolve the missing references.
6. Insert the following in the Shared/_Layout.cshtml view right after the opening body tag
7. In the same file (_Layout.cshtml) insert the following after the ActionLink(“API”)
8. Replace the Index() method of the HomeController with this code and resolve missing dependicies.
9. Add a new model called: NewsItem
9. Add an empty MVC 5 controller to the project. Name it NewsController. Replace the Index() method with this code and resolve missing dependicies.
10. Add a new View named Index in the News folder and insert the following code below the heading 2 tag. Remember to update the namespace in the IEnumerable if needed.
Run the application.
Press the login link and verify it changes to: Welcome Your Name. If promptet, please login.
Press the News link in the navigation and verify you see the news from Noticeboard.
This concludes this sample application.