Please enable JavaScript to view this site.

Altova MapForce Server 2021 Advanced Edition

This example shows you how to call a REST-style Web service that requires OAuth 2.0 Authorization. The client application is a MapForce Server execution file (.mfx) that will retrieve calendar events using the Google Calendar API (https://developers.google.com/calendar/). To keep things simple, the .mfx file will retrieve the calendar information "as is" and will just output the raw JSON result without any other processing.

 

Prerequisites:

 

MapForce Enterprise Edition

MapForce Server Advanced 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.

inc-oauth2-create-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.

inc-oauth2-consent-screen1

5.Enter "mapforce-demo" as application name and save the settings.

inc-oauth2-consent-screen2

6.Click Create credentials and then select OAuth Client ID.

7.Enter Desktop app as application type and "MapForce Client" as the client name.

inc-oauth2-client-id

8.Click Create. The client ID is created and becomes available in the Credentials page.

inc-oauth2-google-credentials

9.Click inc-oauth2-download 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:

inc-oauth2-enable-api

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 _ic_mf_credential_add 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.

inc-oauth2-credential-dlg

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.

inc-oauth2-app-access1

9.Click Advanced, and then click Go to mapforce-demo (unsafe).

inc-oauth2-app-access2

10.Click Allow. A confirmation is now displayed in the browser.

inc-oauth2-app-access3

MapForce also notifies you that the OAuth 2.0 authorization code has been retrieved successfully.

inc-oauth2-app-access4

11.Click OK. Notice that the Access Token and Refresh Token fields have now been populated with data.

inc-oauth2-credential-dlg2

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.

inc-oauth2-ws-dialog1

6.Click the _ic_ws_param_add Add Parameter button and define the parameter details as follows:

inc-oauth2-ws-dialog2

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.

 

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.

inc-oauth2-http-security-dialog

The Web service configured so far has the following appearance on the mapping:

inc-oauth2-ws-incomplete

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:

inc-oauth2-design-parameter

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.

inc-oauth2-design-complete

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:

inc-oauth2-result

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.

 

Run the mapping with MapForce Server (standalone)

This section specifically deals with running the demo OAuth 2.0 mapping with MapForce Server installed as a standalone product, not under FlowForce Server management. For information about running such mappings with MapForce Server under FlowForce Server management, refer to the FlowForce Server documentation, where this example is continued.

 

To run an OAuth 2.0 mapping with MapForce Server standalone, there are two ways to deal with OAuth 2.0 credentials:

 

Include the OAuth 2.0 token (in encrypted form) in the compiled .mfx file. With this approach, you will not need to supply any OAuth 2.0 credentials at the command line (or in the MapForce Server API call) because the embedded credential will be used. However, this also means that anyone with access to the .mfx file will be able to run it without providing the authorization token—until it expires or the authorization server revokes it. Importantly, you can always override the authorization token from the command line without having to recompile the .mfx file (see the next bullet).

Do not include the OAuth 2.0 token in the compiled .mfx file. With this approach, you (or another user who runs the .mfx file) will need to supply the OAuth 2.0 authorization token at the command line or in the MapForce Server API call. The authorization token itself must be obtained outside of MapForce Server, for example with MapForce, as already described previously.

 

In this example, the authorization token will not be included in the compiled .mfx file. Instead, it will be provided at runtime.

 

1.In MapForce, right-click an empty area on the mapping and select Open Credentials Manager.

2.Double-click the credential record ("my.oauth", in this example) and clear the Include in MapForce Server Execution File and Mapping Deployment check box.

3.Save the mapping design file (.mfd).

 

Let's now compile the mapping to a MapForce Server Execution file (.mfx):

 

1.On the File menu, click Compile to MapForce Server Execution File.

2.Select a destination directory and save the file as GetCalendarEvents.mfx.

 

You can now open a Command Prompt window and run the .mfx file with a command like:

 

mapforceserver-exec run GetCalendarEvents.mfx --p=calendarId:"primary" --credential=my.oauth:oauth:token=mytoken

 

Where:

 

mapforceserver-exec is the path to the MapForce Server executable, typically C:\Program Files\Altova\MapForceServer2021\bin\MapForceServer.exe.

GetCalendarEvents.mfx is the path to the .mfx file relative to the current directory of the command line. Adjust the path if applicable, or use an absolute path.

calendarId is the name of the input parameter as it was created in MapForce

my.oauth is the name of the credential as it was created in MapForce in a previous step.

mytoken is the value of the authorization token obtained externally (in this case, with MapForce).

 

On successful execution and OAuth 2.0 authorization, the command line output displays the response returned by the Google Calendar API, for example:

inc-oauth2-mfx-result

Be aware that the authorization token expires very quickly (the interval depends on the authorization server, which is Google in this case) and you may need to request a new one if you get "Unauthorized" errors, see Request an authorization token.

© 2020 Altova GmbH