Introduction
The Wizdom API is a RESTful API with a JSON payload that can be used to access Enterprise services from external applications.
The details about the API can be found in the Enterprise Administration under the specific module. Read more about connecting to Azure AD-secured APIs in SharePoint Framework solutions here.
The following Enterprise modules come with public API’s, which you can find in the Administration:
- Course Management
- Helpdesk
- Workspaces
- Noticeboard
- Export/Import
- Mega Menu
- Webhooks
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 Enterprise services
- Building Native mobile applications
- Create custom endpoints
- Request additional data in a webhook event or custom site template
Authentication
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.
Prerequisites:
- 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 Enterprise 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.
<add key="tenant" value="[your tenant].onmicrosoft.com" />
<add key="client_id" value="[azure directory app application id]" />
<add key="client_secret" value="[azure directory app key]" />
<add key="resource" value="https://[your tenant].sharepoint.com/"/>
<add key="redirect_uri" value="[azure directory reply url]" />
<add key="app_url" value="https://[wizdom app name].azurewebsites.net"/>
<add key="view_id" value="[view guid]"/>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.
public async Task<ActionResult> Index()
{
if (Request.QueryString["code"] != null)
{
Dictionary<string, string> post = null;
post = new Dictionary<string, string>
{
{"client_id", ConfigurationManager.AppSettings["client_id"]}
,{"client_secret", ConfigurationManager.AppSettings["client_secret"]}
,{"grant_type", "authorization_code"}
,{"code", Request.QueryString["code"]}
,{"resource", ConfigurationManager.AppSettings["resource"]}
,{"redirect_uri", ConfigurationManager.AppSettings["redirect_uri"]}
};
var client = new HttpClient();
var postContent = new FormUrlEncodedContent(post);
var response = await client.PostAsync($"https://login.microsoftonline.com/{ConfigurationManager.AppSettings["tenant"]}/oauth2/token", postContent);
var content = await response.Content.ReadAsStringAsync();
var json = JObject.Parse(content);
var accessToken = json["access_token"].ToString();
Session["access_token"] = accessToken;
var handler = new JwtSecurityTokenHandler();
var jwtToken = handler.ReadJwtToken(json["id_token"].ToString());
Session["name"] = jwtToken.Payload["name"];
}
return RedirectToAction("Index", "Home");
}6. Insert the following in the Shared/_Layout.cshtml view right after the opening body tag
<div>
@if (Session["access_token"] == null)
{
<a href="@ViewBag.LoginLink">Login</a>
}
else
{
<span>Welcome @Session["name"].ToString()</span>
}
</div>7. In the same file (_Layout.cshtml) insert the following after the ActionLink(“API”)
<li>@Html.ActionLink("News", "Index", "News", new { area = "" }, null)</li>8. Replace the Index() method of the HomeController with this code and resolve missing dependicies.
public ActionResult Index()
{
ViewBag.Title = "Home Page";
ViewBag.LoginLink = $"https://login.microsoftonline.com/{ConfigurationManager.AppSettings["tenant"]}/oauth2/authorize?client_id={ConfigurationManager.AppSettings["client_id"]}&response_type=code&redirect_uri={HttpUtility.UrlEncode(ConfigurationManager.AppSettings["redirect_uri"])}&response_mode=query&resource={HttpUtility.UrlEncode(ConfigurationManager.AppSettings["resource"])}";
return View();
}9. Add a new model called: NewsItem
public class NewsItem
{
public string Heading { get; set; }
public string Content { get; set; }
public NewsItem(string heading, string content)
{
this.Heading = heading;
this.Content = content;
}
}9. Add an empty MVC 5 controller to the project. Name it NewsController. Replace the Index() method with this code and resolve missing dependicies.
public ActionResult Index()
{
var token = Session["access_token"];
var appUrl = ConfigurationManager.AppSettings["app_url"];
var viewId = ConfigurationManager.AppSettings["view_id"];
var filter = "current";
if (token != null)
{
ViewData["News"] = GetContent(appUrl, viewId, filter, token.ToString());
}
else
{
ViewData["News"] = new List<NewsItem>();
}
return View();
}
private static List<NewsItem> GetContent(string appUrl, string viewId, string filter, string token)
{
WebClient wc = new WebClient();
var url = $"{appUrl}/api/wizdom/noticeboard/1/views/{viewId}/items/{filter}?$take=5&$skip=0";
wc.Headers.Add("Authorization", $"Bearer {token}");
wc.Headers.Add("x-wizdom-rest", "app01");
var res = wc.DownloadString(url);
var jsonTemp = JObject.Parse(res);
List<NewsItem> list = new List<NewsItem>();
var results = jsonTemp["items"]["results"] as JArray;
foreach (var item in results.Children())
{
list.Add(new NewsItem(item["heading"].ToString(), item["content"].ToString()));
}
return list;
}<ul>
@foreach (var item in ViewData["News"] as IEnumerable<WebApplication2.Models.NewsItem>)
{
<li>
<h2>@item.Heading</h2>
<div>@item.Content</div>
</li>
}
</ul>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.
Comments
0 comments
Please sign in to leave a comment.