Example: OAuth 2.0 Authorization
This example shows you how to call a REST-style Web service that requires OAuth 2.0 Authorization. The client application is a MapForce mapping that will retrieve calendar events using the Google Calendar API (https://developers.google.com/calendar/). To keep things simple, the mapping will retrieve the calendar information "as is" and will just output the raw JSON result without any other processing.
Prerequisites:
•MapForce Enterprise Edition
•To follow this example step-by-step, you must have a Google account. If you would like to call another Web service, obtain OAuth 2.0 credentials from your Web service provider and use them in the instructions below instead.
Obtain the OAuth 2.0 credentials
If you already have the OAuth 2.0 credentials required to access the Web service, you can skip this step. Otherwise, the exact instructions to obtain them depend on the provider of the Web service that your mapping will call. To call the Google Calendar API like in this example, follow these steps:
1.Login to the Google API Console (https://console.developers.google.com/).
2.Create a new project.
3.Click OAuth consent screen.
4.Select External as user type, unless you have a G Suite account which would enable you to grant API access only to users in your organization.
5.Enter "mapforce-demo" as application name and save the settings.
6.Click Create credentials and then select OAuth Client ID.
7.Enter Desktop app as application type and "MapForce Client" as the client name.
8.Click Create. The client ID is created and becomes available in the Credentials page.
9.Click 
to download the OAuth 2.0 authorization details as a JSON file.
You have now obtained the OAuth 2.0 authorization details from Google Console API, namely:
1.Authorization Endpoint
2.Token Endpoint
3.Client ID
4.Client Secret
Enable the Google Calendar API
To accept calls from clients, the Google Calendar API used in this example must be enabled. In the Google API Console, click Library, search for the Google Calendar API and enable it:
In this example, we are going to call the list method of the Events entity. You can find detailed reference to this API method at https://developers.google.com/calendar/v3/reference/events/list. For now, note the following important points:
1.As pointed out in documentation, the method must be called by sending a GET request to https://www.googleapis.com/calendar/v3/calendars/calendarId/events, where calendarId is the identifier of a Google Calendar. The calendarId request parameter will be configured from MapForce in a subsequent step.
2.Calling the API method requires at least one of the following scopes:
•https://www.googleapis.com/auth/calendar.readonly
•https://www.googleapis.com/auth/calendar
•https://www.googleapis.com/auth/calendar.events.readonly
•https://www.googleapis.com/auth/calendar.events
During the OAuth 2 authorization process, your mapping will have to provide one of the scopes above—this will also be configured in a subsequent step. For the purpose of this example, the first "read-only" scope is sufficient.
Request an authorization token
In order to preview the mapping in MapForce, you will need to add the OAuth 2.0 authorization details to the mapping and request an authorization token, as illustrated below.
1.In MapForce, right-click an empty area on the mapping, and select Open Credentials Manager from the context menu.
2.Click 
Add Credential.
3.Enter a name ("my.oauth", in this example), and select OAuth 2 as type.
4.Fill in the Authorization Endpoint, Token Endpoint, Client ID, Client Secret text boxes with the corresponding values from the JSON file downloaded previously.
5.Enter https://www.googleapis.com/auth/calendar.readonly in the Scope text box.
6.Leave all other settings as is.
7.Click Request Access Token to obtain the token from the authorization server (in this example, Google). A browser window opens asking you to connect to your Google account.
8.Login to your Google account. Since you haven't submitted any app verification requests to Google yet, the following page appears.
9.Click Advanced, and then click Go to mapforce-demo (unsafe).
10.Click Allow. A confirmation is now displayed in the browser.
MapForce also notifies you that the OAuth 2.0 authorization code has been retrieved successfully.
11.Click OK. Notice that the Access Token and Refresh Token fields have now been populated with data.
12.Save the mapping as GetCalendarEvents.mfd.
In this tutorial, the Save encrypted in MFD file check box is selected on the Edit Credentials dialog box. Therefore, the sensitive fields Client Secret , Authorization Token, and Refresh Token will be saved in encrypted form in the mapping design file (.mfd) when you save the mapping. |
Be aware that the authorization token will eventually expire after a period. When that happens, you will no longer be able to run the mapping (at this stage, no mapping has been designed, but this will happen in a subsequent step). Whenever you need to obtain a new authorization code manually, click Request Access Token, and follows the steps described above.
Design the Web service call
The mapping GetCalendarEvents.mfd created so far does not do anything yet. The only thing it contains are OAuth 2.0 credentials that enable access to the Google Calendar API.
Let's now design the Web service call in MapForce, as follows:
1.Open the GetCalendarEvents.mfd mapping.
2.On the Insert menu, click Web Service Function. The "Web Service Call Settings" dialog box appears.
3.Click Manual.
4.Select GET as request method and enter the URL to the Web service mentioned in a previous step: https://www.googleapis.com/calendar/v3/calendars/calendarId/events.
5.Because calendarId is a placeholder that must be provided as a parameter, enclose it within curly braces as shown below.
6.Click the 
Add Parameter button and define the parameter details as follows:
In the configuration above, the "Template" style makes it possible to replace the URL part enclosed within curly braces with the parameter value at runtime. "Mappable" means that you can supply the value from the mapping (for example, from a constant, or perhaps from an input parameter). Finally, the parameter has been marked as "Required" because the API call cannot take place without it. For further information, see Defining Web Service Parameters.
7.Click the Edit button adjacent to HTTP Security Settings.
8.On the "HTTP Security Settings" dialog box, select Use Credential and choose the "my.oauth" credential record configured previously.
The Web service configured so far has the following appearance on the mapping:
You can now complete the design by taking the following steps:
1.On the Insert menu, click Insert Input, and configure the component as follows:
As illustrated above, the input component has the design-time value "primary". According to the API's documentation, the value "primary" instructs the API server to access the primary Google calendar of the currently logged in user. Note that this value is a design-time value and is applicable only when you preview the mapping in MapForce. When the mapping runs in a server environment, you will need to provide the desired value at runtime.
2.Drag the decode-mime-entity function from the Libraries window into the mapping area. This function converts the raw MIME body received from the server into a string.
3.On the Insert menu, click Insert Output, and add a simple output component whose role is to output the result as a plain string.
4.Make the connections between components as illustrated below.
This concludes the design part in MapForce.
Test the mapping execution
To test the mapping execution in MapForce, click the Output tab and observe the result displayed in the Messages window.
If you get an authorization error such as "Unauthorized (401)", note the following troubleshooting tips:
1.Make sure that the Google Calendar API is enabled, see Enabling the Google Calendar API.
2.Request a new authorization token, in the event that the access token obtained previously has already expired.
3.Double-check that all OAuth 2.0 details were entered correctly in MapForce.
On successful execution and OAuth 2.0 authorization from MapForce, the mapping output is expected to look similar to the one below:
If you used a Google account that does not have any calendar events like in this example, the "items" array is empty in the response. However, if you add an event to your Google Calendar and run the mapping again, the output will reflect that. As a side note, you could also retrieve events from a calendar other than the default one. For example, you could retrieve data from a public calendar like "Holidays in United States". To do this, set the value of calendarId parameter to en.usa#holiday@group.v.calendar.google.com instead of primary.
For information about other parameters that you can add to the API call, refer to the API method's documentation at https://developers.google.com/calendar/v3/reference/events/list.