How to use IBM App Connect with Microsoft OneNote

Microsoft OneNote is a digital notebook that is designed to collect information and organize notes freely, making it a useful tool for organizing ideas and effectively collaborating with people in real time.

Availability:

App Connect Enterprise as a Service connector
Local connector in containers (Continuous Delivery release) 12.0.9.0-r2 or later

Connecting to Microsoft OneNote
General considerations
Events and actions
Examples

Connecting to Microsoft OneNote

Complete the connection fields that you see in the App Connect Designer Catalog page or flow editor. If necessary, work with your Microsoft OneNote administrator to obtain these values.

Microsoft OneNote connection fields:

Authorization method	Connection field	Applicability
BASIC OAUTH	Application client ID	App Connect Enterprise as a Service and App Connect in containers
	Application client secret
	Access token
	Refresh token
OAUTH 2.0 PASSWORD	Username	App Connect Enterprise as a Service and App Connect in containers
	Password
	Application client ID
	Application client secret
OAUTH 2.0 AUTH CODE	Tip: Authorize connection to Microsoft OneNote by signing in to your account.	App Connect Enterprise as a Service

Description of the connection fields:

Connection field	Description
Application client ID	The unique identifier generated after the Microsoft Azure app registration gets mapped to the specific project requests.
Application client secret	The application client secret for a project-specific unique application client ID.
Access token	The access token that is generated from the application client ID and client secret.
Refresh token	The refresh token that is generated from the application client ID and client secret.
Username	The username that is authorized to access the Microsoft OneNote API.
Password	The password for the specified username.

To generate these values and connect to Microsoft OneNote, you need to register an application with the required permissions in Microsoft Azure, which will enable App Connect to integrate with Microsoft OneNote by using APIs and protocols.

To connect by using different authorization methods, you need to obtain client ID, client secret, access token, and refresh token for your registered app, and then configure permissions.

Note: These instructions assume that you are registering an application in Microsoft Azure for the first time.

Note: Choose the applicable steps for the connection values based on the authorization method you selected.

To register an application with Microsoft Azure, for use with App Connect:
1. Log in to the Microsoft Azure portal, and then locate and click App registrations.
2. If you have access to more than one tenant, switch to the tenant where you want to register the app by using the Directories + subscriptions filter in the banner and then click the Close icon (X) to return to the previous page.
3. In the App registrations page, click New registration.
4. In the Register an application page, specify a unique name for your app, select Accounts in any organizational directory (Any Azure AD directory - Multitenant) as the account type, and accept the default values for the remaining fields.
5. Click Register. The Overview page for the application is displayed.
6. Make a note of the Application (client) ID value because you need to specify it as a connection value when creating the account in App Connect.
To generate a client secret for your registered application:
1. Next to Client credentials on the Overview page, click Add a certificate or secret. This displays the Certificates & secrets page.
2. Click New client secret
3. In the Add a client secret panel, specify a description for the secret (for example, App Connect secret) and then select an expiry period.
4. Click Add. The generated client secret is displayed on the Certificates & secrets page.
5. Copy and store the client secret value because you need to specify it as a connection value when creating the account in App Connect.
  Note: The client secret value won't be shown again in full after you leave this page.

Configure the permissions that App Connect needs.

In the left pane, click API permissions and then click Add a permission > Microsoft Graph > Delegated permissions to add each of the following permissions in turn. You can search for and select a permission, and then click Add permissions.

Permissions	Description
`Notes.Create`	Create user OneNote notebooks
`Notes.Read`	Read user OneNote notebooks
`Notes.Read.All`	Read all OneNote notebooks that user can access
`Notes.ReadWrite`	Read and write user OneNote notebooks
`Notes.ReadWrite.All`	Read and write all OneNote notebooks that user can access
`Notes.ReadWrite.CreatedByApp`	Limited notebook access (deprecated)

If the status of any permission is shown as Not granted for myDomain, click Grant admin consent for myDomain, where myDomain is your domain name. Then click Yes to confirm. (This updates the status of all permissions to Granted for myDomain.)

Use an application such as IBM API Connect Test and Monitor or Postman to submit a POST request to generate an access token and a refresh token that will be used to interact with Microsoft OneNote on your behalf. Specify the following parameters:

Request URL:

https://login.microsoftonline.com/organizations/oauth2/v2.0/token

Content-Type: application/x-www-form-urlencoded

Request parameters:

Key	Value
`client_id`	Set this to the Application (client) ID value that was generated for your registered app.
`scope`	`Directory.ReadWrite.All offline_access`
`grant_type`	`password`
`client_secret`	Set this to the client secret value that was generated under Certificates & secrets for your registered app.
`userName`	Set this to the username that was used to log in to the Azure portal.
`password`	Set this to the associated password for the username.

Postman Version 7.29.1 was used in these instructions, so there might be a slight variation in the fields that you see if your version is different.
1. Start a new POST request and specify the request URL.
2. Click the Body tab and select x-www-form-urlencoded. This option automatically adds the Content-Type: application/x-www-form-urlencoded setting in the request header.
3. Specify the request parameters.
When you click Send, an access token and refresh token are returned in the response. Make a note of these values because you need to specify them as connection values when creating the account.
Note: The generated access token is valid for 1hour, and the refresh token will expire after 90 days of inactivity. So, it is expected that you need to generate new tokens only if the refresh token has been revoked or has not been used in 90 days.

To connect to a Microsoft OneNote endpoint from the App Connect Designer Catalog page for the first time, expand Microsoft OneNote, then click Connect. For more information, see Managing accounts.

Tip:

Before you use the account that is created in App Connect in a flow, rename the account to something meaningful that helps you to identify it. To rename the account on the Catalog page, select the account, open its options menu (⋮), then click Rename Account.

General considerations

Before you use App Connect Designer with Microsoft OneNote, take note of the following considerations:

The following table describes the service limits for the Microsoft OneNote connector:

Limit type	Limit per app per user (delegated context)	Limit per app (app-only context)
Requests rate	120 requests per 1 minute and 400 per 1 hour	240 requests per 1 minute and 800 per 1 hour
Concurrent requests	5 concurrent requests	20 concurrent requests

For more information about service limits, see OneNote service limits on the Microsoft Documentation page.

All the supported actions in the Microsoft OneNote connector has User ID as an input field.
- If you want to execute an action for your own notebook, then you have to provide 'me' as the input value.
- If you want to execute an action on behalf of other users who have permitted you, then you must provide the user ID of the other user as the input value.
Example of App Connect user interface fields that are filled for the action Create page with embedded content:
In the example, you can see that the Content field contains information about the HTML content which consists of a file attachment. You can configure this field to include multiple images and file attachments. For more information about configuring this field, see the following useful resources on the Microsoft Documentation page.
Restriction: For a list of limitations while sending image and file data, see Size limitations for POST pages requests on the Microsoft Documentation page.

(General consideration) You can see lists of the trigger events and actions that are available on the Catalog page of the App Connect Designer.
For some applications, the events and actions in the catalog depend on the environment and whether the connector supports configurable events and dynamic discovery of actions. If the application supports configurable events, you see a Show more configurable events link under the events list. If the application supports dynamic discovery of actions, you see a Show more link under the actions list.
(General consideration) If you are using multiple accounts for an application, the set of fields that is displayed when you select an action for that application can vary for different accounts. In the flow editor, some applications always provide a curated set of static fields for an action. Other applications use dynamic discovery to retrieve the set of fields that are configured on the instance that you are connected to. For example, if you have two accounts for two instances of an application, the first account might use settings that are ready for immediate use. However, the second account might be configured with extra custom fields.

Events and actions

Microsoft OneNote events

These events are for changes in this application that trigger a flow to start completing the actions in the flow.

Note: Events are not available for changes in this application. You can trigger a flow in other ways, such as at a scheduled interval or at specific dates and times.

Microsoft OneNote actions

Your flow completes these actions on this application.

Object	Action	Description
Pages	Create page with embedded content	Creates a page with embedded content in OneNote Tip: For more information about using the Create page with embedded content operation, see Add images, videos, and files to OneNote pages on the Microsoft Documentation page.
	Create page	Creates a page in OneNote
	Retrieve pages	Retrieves pages from OneNote
	Delete page	Deletes a page from OneNote
	Download page content	Downloads the page content
	Append note	Appends a note in OneNote page
Notebooks	Create notebook	Creates a notebook in OneNote
	Retrieve notebooks	Retrieves the notebooks from OneNote
	Retrieve recent notebooks	Retrieves the recent notebooks from OneNote
Sections	Create section	Creates a section in OneNote page
Sections	Retrieve sections	Retrieves the sections from OneNote pages
Section groups	Create section group	Creates the section group in OneNote page
Section groups	Retrieve section groups	Retrieves the section groups from OneNote page

Examples

Dashboard tile for a template that uses Microsoft OneNote

Use templates to quickly create flows for Microsoft OneNote

Learn how to use App Connect templates to quickly create flows that complete actions on Microsoft OneNote. For example, open the Templates gallery, and then search for Microsoft OneNote.

Learn more

Use IBM® App Connect to build flows that integrate with Microsoft OneNote.

Read the blog in the IBM Community to learn how to create a page with embedded content for each new email received with attachments from Microsoft Exchange. Click Read the blog to go to the blog.

Read the blog