Introduction
This article is about accessing your Office 365 SharePoint application via the SharePoint API to fetch or update its resources specifically using REST API services from OutSystems. You are probably reading this article because you want to get access to your existing company intranet, which is created in SharePoint, but within your new OutSystems application. Now, with the SharePoint API, you can access all the resources, in the same way you would in ASP.NET, or any other development language that supports REST API access, for that matter. I am going to use a tool called PostMan in order to demonstrate how a REST API works, and how you can get access to the basic operations of your SharePoint site.
Postman Tool
This is a developer friendly tool for handling the REST APIs from any platform. By using this tool we’ll retrieve and update any information from SharePoint using REST API endpoints. We can get this here: PostMan Download Link.
Postman & SharePoint Rest endpoints
If you are new to SharePoint REST API or you want to know more about REST endpoints in SharePoint; visit the link Get to know the SharePoint 2013 REST service.
Now that you have at least some understanding about the PostMan tool & SharePoint Rest API endpoints, we’ll start testing the SharePoint REST API with this tool.
Example
Let’s take a simple scenario like, retrieving the web title from the current site context. The equivalent syntax for retrieving the website’s title is
https://<SiteName>.sharepoint.com/_api/web?$select=Title
After entering the above URL in the text-box in the URL text-box. We will simply receive an Unauthorized exception. That is because SharePoint Online is very much secure and doesn’t simply allow anonymous users to access the information on the site. Below is the error message response, after sending the request:
Figure 1
To avoid an Unauthorized exception, we need to add some request header values to the API request. Authentication and Authorization of SharePoint Add-Ins gives an overview of authorizing the Add-ins to access SharePoint resources by the APIs.
Authentication Policies:
SharePoint online considers any one of the below three type of polices to authenticate the Add-In.
- User Policy
- Add-In Policy – We are using this policy to authenticate the external system to access SharePoint
- User +Add-In Policy
Request Headers:
And, we require the following information in various requests to authenticate with SharePoint online site.
- Client Id
- Client Secret
- Realm (Tenant Id)
- Access Token
Authorize Application to access SharePoint
To get authorization from an external system, we should pass access-token value as a request header along with the REST API URL. Before that we have to get the access-token. And in order for us to obtain an access-token, we should generate a Client Id and Secret information from the site by registering as an App only Add-In in our SharePoint site.
I have provided the steps below to get the Tenant Id, Access Token and data from SharePoint using our trusty PostMan utility.
Register Add-In
First, we have to register the Add-In in SharePoint, where we want to access the information. Follow the steps below to register the Add-In in your SharePoint site:
- Navigate and login to SharePoint online site.
- Then navigate to the Register Add-In page by entering the URL as
https://<sitename>.SharePoint.com/_layouts/15/appregnew.aspx
- On App Information section, click Generate button next to the Client Id and Client Secret textboxes to generate the respective values.
- Enter Add-In Title in Title textbox
- Enter AppDomain as a localhost
- Enter RedirectUri as a https://localhost
Figure 2
-
Click Create button, which registers the add-in and returns the success message with created information.
Figure 3: Add-In Registration Successful
Grant Permissions to Add-In
Once the Add-In is registered, we have to set the permissions for that add-in to access the SharePoint data. We will set the Full Control permission level to the web scope, so that we will be able to read and write to the SharePoint site.
Figure 3: Set Permission for Add-In.
Then click the Create button. This will then display the confirmation page where you confirm that you want to trust your newly created Add-In. Click the ‘Trust it’ button to continue:
Figure 4: Confirm Add-In permissions
Connect OutSystems application to SharePoint
Now, we can finally use our OutSystems application to connect directly to SharePoint! Since the Add-In is now registered, we can now use it to retrieve the Tenant ID, which is then used to Generate an Access Token. The Token is usually valid for a limited amount of time, so it would be easier just to generate a token every time you want to perform an operation with SharePoint, unless you have a substantial number of operations every time your OutSystems application runs.
Note: I also created an OutSystems project, that is used for the article. It is located in the OutSystems forge (https://www.outsystems.com/forge/). Simply search for ‘Sharepoint Connector’.
Retrieve the Tenant ID
Once we have registered the Client Id and Secret with the permissions, we are ready to access SharePoint from our OutSystems application.
First, we need the Tenant ID. This is accomplished by calling the GetClient method in the OutSystemsSharepointGetTenantId REST API service as shown:
Figure 5: OutSystems GetClient REST API Function
As you can see from figure 5, there is an ‘Authorization’ parameter. The test value is ‘bearer’, and that’s what is passed by the calling Server Action. This does not authorize the request, but simply returns the Bearer realm and client_id as part of the WWW-Authenticate header:
Figure 6
Note that the client_id is actually a global resource id for SharePoint itself. Don’t confuse it with the ‘AppId; you created for your add-in previously.
Generate the Access Token
These attributes are now used to actually generate the access token. We now need to create a POST API method with the URL:
https://accounts.accesscontrol.windows.net/<TenantID>/tokens/OAuth/2
to actually retrieve the access token. The preparation action of the ‘SharepointTest1’ web screen actually contains all the logic for retrieving the access token, (if expired), and using that token to retrieve and create objects within your SharePoint site. The first action that encapsulates both retrieving the tenant and generating the access token, if necessary, is GetAccessToken Server action:
Figure 7: Retrieve Tenant Id and Access Token
The GetAccessToken Server action calls the GetClient method first (Figure 5 and 6), to retrieve the Tenant Id (Realm in Figure 6), and ResourceClient Id (Client_id in Figure 6). Then, to acquire a new token, the BuildAccessTokenRequest server action is called to form the request body:
Figure 8: BuildAccessTokenRequest Server action
Now, that the Request Body is created, this is passed into the PostOauth REST API method to generate the actual token:
Figure 9: Request new Access Token
Once, the request has been posted, the response, should contain the new token:
Figure 10: Bearer Token response
SharePoint REST API methods
Now, that we finally have our token, we can now actually access our SharePoint site via specific REST API commands. The GetSiteInfo is the first REST API call that retrieves information from your actual SharePoint site:
Figure 11: Get Site Title
This simply retrieves the site title, and metadata as follows:
Figure 12: Request site title response
The next server action that we will look at is ‘CreateTestFolder’. This action calls the CreateTestFolder REST API method to actually create a folder. I have chosen to create a folder under the ‘Share Documents’ folder called ‘Folder A’:
Figure 13: Create a new folder in ‘Shared Documents’
Once the post occurs, the folder is successfully created on the main team site Documents folder:
Figure 14: Folder creation successful!
As you can see, the folder was created successfully. Next, lets take a look at the file creation REST API method. This method simply creates a file within the newly created FolderA that we just created:
Figure 15: Create new file within folder
The request body contains the actual file contents, in this case a text file. When the POST is sent to the server, as you would expect, a new file is created:
Figure 16: File successfully created
Now, to verify that it actually worked, and to read the contents of the newly created text file, the last server action is ‘GetTestFileContents’ which in turn calls the REST API method with the same name:
Figure 17: Read Contents of newly created text file
And, then when this GET method is executed, as you can see from the console debug window, the file contents match what was originally created:
Figure 18: Read contents of newly created file.
Summary
This concludes my demonstration of how to integrate your existing SharePoint Office 365 tenant with your OutSystems applications. As you can see, the Postman utility was very useful in helping test and create the Add-In and REST API methods used to communicate with your SharePoint site. If you are new to WEB API, hopefully you have learned all the basics of creating WEB API methods as well. OutSystems, while seemingly easy to use, is not recommended for learning any complex programming methods such as REST. Postman is very powerful and is easy to learn, and very useful for debugging your web service calls. So, I would recommend starting off with Postman, as I did at the beginning of this article, as it makes your API method creation much easier.
