Working with Facebook

Connecting to Facebook

Create a Facebook app

Create a Facebook connection

Create a Facebook app

By creating a Facebook app, you are enabling access to Facebook's Graph API. A Facebook app is not an actual "application", it is just a set of credentials and access rights, linked to your Facebook account.

Each application has a unique ID and and a Secret that can be used to obtain an access token, which will later be used to access Facebook's Graph API. When creating a Facebook connection in Integrator, the user is required to log in with their actual Facebook credentials (user name and password), but those are never stored in Integrator's database. Instead, it stores an Access token, linked to a particular App ID and a Secret.

Integrator includes a built-in Facebook app which provides very limited access to Facebook's Graph API. You must create an app if you want your Facebook connection to have access to the following rights: user_posts, user_managed_groups, user_about_me, user_actions.news, user_tagged_places, user_relationships, user_birthday, user_events, user_website, user_relationship_details, user_photos, user_hometown, user_likes, publish_actions, read_custom_friendlists, user_location.

Important: if you choose to create your own app, in most cases you will need a new app for each Facebook account you are going to be accessing, while using Integrator's Facebook connector.

To create a Facebook app:

Step 1. Log out from your personal Facebook account.

Step 2. Go to https://developers.facebook.com/ and log in with the account you are going to be creating the connection to.

Step 3. Click Add New App under the My Apps menu, on the top right corner of the screen.

Step 4. In the popup window enter the app Display Name and Contact Email. Pass the security check.

Step 5. Select Facebook Login under Select Product and click the Set Up button.

Step 6. Click the Web link in the next window.

Step 7. Enter the Site URL in the next window and click the Save button.

it is very important to understand what you are going to be entering as a Site URL.

• If you are using Integrator, hosted by Etlworks on any of the Etlworks subdomains, such as app.etlworks.com, your_company_name.etlworks.com, etc., just enter https://etlworks.com.

• If you are hosting Integrator yourself and are using your own domain, for example, https://integrator.your_company_name.com, just enter that URL in the protocol://domain format. For example: https://google.com.

• If you are hosting Integrator yourself, on localhost, for example, http://localhost:8080, then enter the URL in this format protocol://localhost, and skip the port number.

• If you are using an IP address, for example, http://192.168.1.100:8080, then enter the URL in this format protocol://ip_address, and skip the port number.

Step 8. 

at this point you can copy and paste App ID and App Secret. You will be using them to create a Facebook connection in Integrator.

Step 9. Go to Settings/Basic on the left navigational bar and enter the actual domain name in the App Domains field. Click the Save Changes button.

it is very important to understand what you are going to be entering for App Domains.

• If you are using Integrator, hosted by Etlworks on any of the Etlworks subdomains, such as app.etworks.com, your_company_name.etlworks.com, etc., enter that particular subdomain. For examples: app.etlworks.com, your_company_name.etlworks.com.

• If you are hosting Integrator yourself and are using your own domain, for example https://integrator.your_company_name.com, enter that particular domain, including the subdomain. For example: integrator.google.com.

• If you are hosting Integrator yourself on localhost, for example, http://localhost:8080, just enter localhost.

• If you are using an IP address, for example, http://192.168.1.100:8080, enter just the IP address, in this case: 192.168.1.100.

Step 10. Enter https://etlworks.com/docs/privacy-policy/ into the Privacy Policy URL field and click Save Changes. 

you can enter your own privacy policy URL.

Step 11. Go to App Review on the left navigational bar and slide Make App Public to the Yes position. Select Category and click the Confirm button.

Step 12. If you want this app to access accounts other than the account you used in Step 2, follow the Facebook app submission process. Otherwise - skip this step.

You are done. You can always access your application by opening https://developers.facebook.com/, logging in using the designated Facebook account, and selecting the app from the My Apps menu.

Create a Facebook connection

Step 1. Start creating a Facebook connection by opening the Connections window, clicking the + button and typing facebook into the search box:

Step 2. Depending upon whether you are going to be pulling data from Facebook's Graph API or posting to Facebook, select either the Facebook Feed or the Facebook Update connection.

Step 3. Enter the Authentication parameters. Click the Test Connection button to verify that the credentials are working.

• App ID and App Secret - Facebook's App ID and App Secret are assigned to the Facebook app created by you. You can leave both fields blank. In this case, Integrator will have access to a very limited subset of Facebook's Graph API. For example, it will not be able to pull public information from the profile, post status updates, etc.
• Access Token - click the Login with Facebook button to receive an access token from Facebook. 

if you are already logged in to Facebook with your personal account (or just a different account) you will need to log out first.

• Permissions - list of permissions required for that specific Facebook app.

Revoking the access token

To revoke the access token, click the Logout from Facebook button.

an Access token is granted for approximately 60 days. Once it expires, the integration flows with this particular connection will stop working. The access token will be displayed as expired and the user will need to Login with Facebook again to receive a new one.

Step 4. Continue by entering the connection parameters, which are unique for each type of connection.

Facebook Feed connection

A Facebook Feed connection is used to pull data from Facebook's Graph API.

Common parameters

• Feed Type - Each Facebook feed type is linked to a specific Facebook Graph API endpoint. Pay attention to the hint found in the feed type name. For example, Search places by keywords or center and distance from center implies that a keyword(s), which are entered as query parameters, as well as a location center and a distance from center are required. If the endpoint is not on the list, use the Call any Facebook API feed type, together with the endpoint name.
• Include Fields - an optional, comma-separated list of fields to include in the response. By default, Facebook returns a very limited subset of fields, mostly IDs and names. Other fields are returned as nulls. You have to manually list all the additional fields, such as emails, etc., if you wish to see them in the response.
• Endpoint name - an optional Facebook Graph API endpoint name. This parameter is used only if Call any Facebook API is selected as the Feed Type. Learn more about Facebook Graph API endpoints.
• Query parameters - use this field mostly for Search... feed types. A query parameter is required for some endpoints and ignored by others. If the Call any Facebook API feed type is selected, enter the query parameters in the format {"key":"value","key":"value"}.

Filter

• ID - some clearly marked feed types accept an optional ID, such as a User ID, Post ID, Group ID, or Album ID.
• Since Date - optional, included start date. The date must be in a format accepted by the PHP strtotime function. For example: yesterday, now, next Thursday, last Monday, 10 October 2017, +1 day, +1 week. etc.
• Until Date - optional, included end date. Date must be in a format accepted by the PHP strtotime function. For example: yesterday, now, next Thursday, last Monday, 10 October 2017, +1 day, +1 week. etc.
• After Date - optional, excluded start date. Date must be in a format accepted by the PHP strtotime function. For example: yesterday, now, next Thursday, last Monday, 10 October 2017, +1 day, +1 week. etc.
• Before Date - optional, excluded end date. Date must be in a format accepted by the PHP strtotime function. For example: yesterday, now, next Thursday, last Monday, 10 October 2017, +1 day, +1 week. etc.
• Center of the Location - optional, center of the location, for location-based requests, such as search places. Location must be in the format Latitude,Longitude. For example: 40.4327086,-79.92486689999998.
• Distance from the Center of the Location - optional, distance from the center of the location in meters, for the location-based requests, such as Search places.
• Limit - optional, limit on number of returned-by API rows.
• Offset - optional, start row (offset from the first row) for the response returned by API.
• Include Summary into response - if selected, the summary information (total number of rows, etc.) will be included in the response. 
• not all API endpoints support the summary field.
• Include Metadata into response - if selected, the metadata information (name and types of the fields) will be included in the response. 

not all API endpoints support metadata field.

• Include Hidden Data into response - if selected, typically hidden data will be included in the response. 

not all API endpoints support the hidden field.

• Show Expired data - if selected, expired data will be included in the response. 

not all API endpoints support the expired field.

• Include only data with location information - if selected, only data with location information (for example, checkins) will be included in the response. 

not all API endpoints support the Location field.

• Ordering - the order of rows in the response.
• Locale - optional, locale (country of origin) of the data.

• 

Facebook Update connection

A Facebook Update connection is used to post to Facebook and delete data from Facebook.

Common parameters

• Action - type of update. Each action is linked to a specific Facebook Graph POST or DELETE API endpoint. If the endpoint is not on the list, use the Call any Facebook API action, together with the endpoint name.
• Endpoint name - optional, Facebook Graph API endpoint name. This parameter is used only if Call any Facebook API is selected as an Action. Learn more about the Facebook Graph API endpoints.
• Request Parameters - the request parameters are required for some endpoints and ignored by others. If the Call any Facebook API action is selected, enter the query parameters in the format {"key":"value","key":"value"}.
• Post parameters
• Message - a message to post. It can include direct links, in the format https://link.
• Link - a link to include, together with the message.
• Picture - the URL of a picture to post with the message.
• Name - an optional name of the post.
• Description - an optional description of the post.
• Caption - an optional caption for the posted image.
• Tags - an optional comma-separated list of tags for the message.

Additional parameters

• ID - some clearly marked actions accept an optional ID, such as a User ID, Post ID, Friends List ID, Event ID, or Comment ID.
• Location - optional, location information for the post. The location must be in the format Latitude,Longitude. For example: 40.4327086,-79.92486689999998.
• Start Date - optional, date to start showing the post. The start date must be in the format mm/dd/YYYY.
• End Date - optional, date to stop showing the post. The end date must be in the format mm/dd/YYYY.
• Publishing status update and privacy settings
• Who can see Status Update - define who can see the status update.
• Publish Immediately - if selected, the post will be published immediately.
• Publish Date - define date (or date+time) when the post should be published. It will not work if Publish Immediately is selected. The date must be in the mm/dd/YYYY format. For example: 02/23/2017.

• 

Step 5. optionally, continue by entering the auto-retry parameters.

Retries - the number of retries allowed for failed execution attempts.

Delay between retries - the delay between retries, in minutes.

Step 6. Click Save to save the connection.

Pulling data from Facebook

Step 1. Create a Facebook Feed connection, which will be used as a source (FROM).

Step 2. Create a destination (TO) connection and (if needed) a format.

Step 3. Start creating the flow by opening the Flows window, clicking the + button and typing extract data from well-known API into the search box:

Step 4. Select the flow type based on what the destination is going to be. For example, Extract data from well-known API, create file.

Step 5. Select the connection created in Step 1 as the source (FROM) and the connection/format created in Step 2, as the destination (TO). Set the FROM and TO fields.

Step 6. Continue by setting the parameters and defining the mapping.

Posting to Facebook

Step 1. Create a Facebook Update connection.

Step 2. Start creating the flow by opening the Flows window, clicking the + button and typing facebook into the search box. Select the Update Facebook flow type.

Step 3. Continue by selecting the connection created in Step 1 as a Facebook Update connection.

Step 4. Optionally, define the message text in the Parameters tab. The message can contain {tokens}, which will be substituted at runtime.

Deleting data from Facebook

Step 1. Create a Facebook Update connection. When configuring the connection select one of the Delete... actions. Enter the required ID. Most of the delete actions require an ID: User ID, Post ID, etc.

Step 2. Start creating the flow by opening the Flows window, clicking the + button and typing delete files into the search box. Select the Delete Files flow type.

Step 3. Add the transformation and select the connection created in Step 1 as the source connection.