MuleSoft Connector for Facebook Ads

Build 21.0.7930

Establishing a Connection

This section describes how to connect to Facebook Ads from your AnyPoint Studio project. You can use wizards or the XML editor in AnyPoint Studio to define connection properties in a global element. Global elements can be reused across other building blocks in your project.

Create a Connection in the Visual Editor

Complete the following steps to visually add the connector to your project and create a connection:

  1. Create a new Mule Project in Anypoint Studio.
  2. From the palette, drag the connector into your Mule flow.
  3. On the Message Flow canvas, double-click the connector icon to open the connector properties in the Properties pane.
  4. In the General section, click Add and define the Facebook Ads connection properties. Note that the user name and Password properties always appear here. The user name must be set as it is used as the key for the connection if connection pooling is enabled.

Create a Connection in the XML Editor

Set connection properties in the <cdata-facebookads:config> element in the root of the project's XML.

Note: The user name attribute must always be included here and serves as the key for the connection if connection pooling is enabled.

  <cdata-facebookads:config name="CData_FacebookAds_Configuration" username="MyName" connectionProperty1="MyProperty" ... doc:name="CData FacebookAds: Configuration"/> 

Authenticating to Facebook

Facebook Ads uses the OAuth standard to authenticate users.

Authenticate via OAuth Authentication

You can connect without setting any connection properties for your user credentials. Set InitiateOAuth to GETANDREFRESH to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken.

When you connect, the connector opens the Facebook Ads OAuth endpoint in your default browser. Log in and grant permissions to the connector. The connector then completes the OAuth process.

  1. Extracts the access token from the callback URL and authenticates requests.
  2. Obtains a new access token when the old one expires.
  3. Saves OAuth values in OAuthSettingsLocation to be persisted across connections.

See Using OAuth Authentication for other OAuth authentication flows.

Posting as a Page

After authenticating to Facebook Ads with your user account, you can post, etc. as one of the pages you manage: Set the AuthenticateAsPage property to the Id of the page you want. You can find the Ids for all pages your account has access to by querying the Pages view.

Automatic Page Authentication

Facebook Ads has made a number of recent changes that require page tokens for most resources owned by a page. This can be troublesome if you manage multiple pages and want to execute the same queries across all pages (such as retrieving Insights). In order to make this work seamlessly with our tools, we have added a way to automatically detect the page token to use. For this to work, simply do not specify the AuthenticateAsPage. Note that the correct page token can only be resolved if the page id is specified as part of the target in the request. This means for some requests you will still need to manually specify AuthenticateAsPage.

Requesting Additional Permissions

You may find while using the connector that Facebook returns an error stating your app does not have permissions to do a certain action. To resolve this, you will need to generate a new OAuth access token with the required permissions. Set the Scope property in the authentication step.

You can find a list of available Facebook permissions here:

Fine Tuning Data Access

  • Target: Some Facebook tables can be filtered by a target. For example, to retrieve comments on a video, specify the Id of the video as the target. This property enables you to restrict the results of all queries in the connection to records that match the specified target. You can also specify this restriction per query with the Target column.
  • AggregateFormat: The connector returns some columns as a string aggregate. For example, the available likes data for an entity is returned in aggregate. By default, the connector returns aggregate columns in JSON. You can also return aggregates in XML.
  • Version: Set this property to the Facebook Ads API version if you need to work with a different version than the default.

Configure Connector Operations

The connector is an operation-based connector; its operations correspond to SQL statements and expose other functionality such as Schema Discovery. See Using the Connector (Mule 3.8+) for more information on executing SQL to Facebook Ads in Mule applications.

Copyright (c) 2021 CData Software, Inc. - All rights reserved.
Build 21.0.7930