Altova MapForce Server 2025 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.

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.

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.

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.

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:

Where:

•mapforceserver-exec is the path to the MapForce Server executable, typically C:\Program Files\Altova\MapForceServer2025\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: