To obtain an access token, you need to register as a Facebook Developer by filling in the registration form: https://developers.facebook.com/async/registration. Make sure you are logged in to the account you use to manage your page.

Generating an access token

Go to https://developers.facebook.com/tools/explorer/. Log in to your account if needed.

Select the app you want to work with, either by its name (for example, Sirius) or ID (for example, 380469262752699). (If you manage multiple Facebook apps, you can check which app is selected in the Meta App menu on the right side of the page.)

Click the Generate Access Token button. A new window will open in which you need to log in to Facebook.

Next, select Get Page Access Token from the User or Page menu. Again, a new window will open. First, confirm your login (enter your password, if needed), then approve or select what Facebook page should be used. In the next step, agree to the required permissions (Read content posted on the Page, Show a list of the Pages you manage) and, in the last step, confirm everything by clicking OK.

The next step is to add the permissions to access user comments using the generated token: in the Permissions menu, specifically in the Add a Permission field, enter pages_read_user_content or select this permission from the drop-down menu.

When you add the permission, you need to select your Facebook page again. You can find it under Page Access Tokens in the User or Page menu.

Next, copy the access token using the Copy Token button on the top right of the page.

Token validation 

To verify that the token you created is valid, go to https://developers.facebook.com/tools/debug/accesstoken/. (Again, you must be logged in to your Facebook account.)

Paste the token you copied in the previous step into the text box and click the Debug button.

A table with token information similar to the image below will appear. (The page name or user information will be different, of course.)

The generated token is valid for approximately 60 minutes. You create it to check that everything is in order – if so, it is possible to generate a token with extended validity.

Generating an extended access token 

Re-generating the token

Return to https://developers.facebook.com/tools/explorer/ and check or add the permissions you have set in the Permissions menu.

The required permissions are:

• pages_show_list

• pages_read_engagement

• pages_read_user_content

• public_profile

• read_insights

After checking the permissions, select Return to User Token or User Token in the User or Page menu.

Next, click on Generate Access Token, same as when you first generated the token, i.e. confirm the login, select which Facebook page to use, agree to the required permissions and confirm everything with OK.

Verify that the User Token is selected in the User or Page menu. Copy the token (by clicking the Copy Token button).

Extending the token validity 

Go to https://developers.facebook.com/tools/debug/accesstoken/ again, enter the token in the text box and click Debug. Again, the table with token information is shown.

Click on the Extend Access Token button below the table. A new window will open where you enter your password. Then a new token will appear at the bottom of the page, with a Debug button next to it.

When you click this button, the table appears again; however, the expiration date is extended to two months (see the Expires row).

Next, copy the generated token.

Creating a token with unlimited validity

Return to https://developers.facebook.com/tools/explorer/ and paste the extended access token into the Access Token field. (You need to actually paste the new token, do not click the Generate Access Token button.)

Select your page in the Users or Page menu (under Page Access Tokens). The access token value will change. Copy the new token (using the Copy Token button) and check it again at https://developers.facebook.com/tools/debug/accesstoken/ (paste the token into the text box, and click Debug).

A table similar to the one below will be created; the value in the Expires row should change to Never.

If everything fits, the token is ready, and you can pass it on or save it for later use.

Creating a new repository from a template

First, you need to clone and prepare a template using a series of terminal commands. (The instructions are intended for a Linux or MacOS terminal; if you use Windows PowerShell, some of the commands will be slightly different.)

Start with cloning the template you will be working with:

git clone https://bitbucket.org/kds_consulting_team/kbc-python-template/src/master

After that, you can rename the downloaded directory, for example, using the name of the component you are creating.

mv master transformer-psc
cd transformer-psc

In the next step, you will remove the template history, i.e., you will get rid of information you do not need for the new component; on the contrary, it would complicate further work.

rm -rf .git (for Mac OS or Linux)
rm -fo .git (for Windows PowerShell)

Then, you will (locally) create a new repository with the necessary data:

git init
git add .
git commit -m 'Keboola Component Template'

The next step is to create a new (empty) repository on GitHub. (Click on your account avatar on the top right -> Your Repositories -> New.) Then, fill in the repository name and description.

Once you have created a repository, the next step is to upload the locally prepared data there; you can copy the command from GitHub (see the image below).

git remote add origin git@github.com:Phalanx-Ai/transformer-psc.git

Then, run:

git push --set-upstream origin master

For everything to work as it should, you need to have a working SSH key. You can also use HTTPS to upload data; in that case, the command sequence will be:

git remote add origin https://github.com/Phalanx-Ai/transformer-psc.git
git push --set-upstream origin master

When using HTTPS, note that the password used for authentication is not the user's GitHub password but an access token that can be generated in the settings (instructions here).

Adding the component to Keboola

Now that you have the repository ready, it is time to create a new component at components.keboola.com. Log in or create an account and create a component by clicking the Add Component button; enter the name and type of the component.

Once you have added the component, click Continue to update this component and fill in the License URL, Documentation URL, and Source code URL. This information can also be added later.

It is recommended to create a service account for the component in order to use it safely. Go to Service accounts and click Create a service account.

Enter an account name (e.g., czech-psc) and description. After creating the service account, you will be shown a username and password you will need in the next step – remember to save them.

Adding component access information on GitHub

Go to the GitHub repository with the component template and open Settings. In the left menu, under Security, expand the Secrets and variables menu and select Actions. Click New repository secret and add the information needed to work with the component, as shown in the list below.

• KBC_DEVELOPERPORTAL_USERNAME - service account name

• KBC_DEVELOPERPORTAL_PASSWORD - service account password

• KBC_DEVELOPERPORTAL_APP - Component ID

• KBC_DEVELOPERPORTAL_VENDOR - component prefix (Vendor ID found in the profile)

• APP_IMAGE - text “keboola-component”

Docker 

After adding the data to the GitHub repository, return to the terminal. Make sure you are in the directory where the docker-compose.yml file is located; then run the command that prepares the container image.

docker-compose build

(Before running this command, it is necessary to start Docker (service docker start); you may also need to run commands as root: sudo docker-compose build).

Next, check that everything works as it should; the template includes a component that prints the text Hello World.

docker-compose run --rm dev

Deploying the application

Upload the newly created component to GitHub, i.e., change src/component.py, and edit README.MD. The next step is to edit the component_long_description.md, component_short_description.md, and configSchema.json  files in the component_config folder as the information from there is transferred into the Keboola component.

The configSchema file specifies what parameters the component receives from the user. The details of setting up the schema are described in the documentation; usually, a form with entries for a string or number will suffice. 

As an example, see the example below from the schema of the Transform Czech ZIP code to district/county component:

{
  "type": "object",
  "title": "Parameters",
  "required": [
    "column_psc"
  ],
  "properties": {
    "column_psc": {
      "type": "string",
      "title": "Name of existing column with ZIP/PSČ",
      "propertyOrder": 1
    }
  }
}

Now, a little sidestep: if you have not filled in the License URL, Documentation URL, and Source Code URL in the component description on components.keboola.com, fill them in now.

The following steps are done in the terminal. Again, make sure you run the commands in the correct directory. 

Once you have a working application, it is time to test it. Run the tests that are included with the template. In this step, a linter is used to verify that nothing prevents the component from being accepted into Keboola. Any deficiencies must be corrected even if they do not affect the functionality of the code.

docker-compose run --rm test

Add a tag corresponding to the semantic versioning to be used in Keboola as the version number.

git tag 0.1.0 -m "0.1.0"
git push origin 0.1.0

Now you just need to wait a bit and you get a component you can use in Keboola.