Callbacks - Connector Callbacks

Introduction

Connector callbacks are only triggered when translations have been completed and are ready for download (using the API).

Use case: When you link a CMS with the Beebox, the CMS uses the limited "Connector" credentials to exchange work. If you would like to notify the CMS of work completed you may want to have a specific CMS page be called. That page may then notify a CMS user or trigger the download of translations.

Setup

Connector callbacks are configured in the "CMS Connector" tab of the project "Settings" page:

As you can see the URL is supplied on the same page where you supply the credentials for the CMS or another external system.

This URL will be called for the event "CreatedTranslatedFiles" only. See list of all events.

Callback URL

The URL that you configure above will be called whenever a translated file or a batch of translated files is "delivered". This means that the translated file was added or updated in the "out" directory. It can then be pulled by API or FTP. With the example in above screenshot, the URL being called might be:

[GET] http://apicallback.com?bbevent=CreatedTranslatedFiles&bbproject=dddac1e2-32fa-4f29-ab92-78128a94809e&bbdate=2023-06-20 06:56:35Z&bbok=yes&bberror=&bbid=b0227cc0-fb64-45df-b0dd-fa25770390cd

You can find an explanation of all parameters here: Callback URL parameters.

The most important are:

bbproject: Is the Beebox project ID. This is the same ID used by the connector to authenticate.
bbid: This is a unique ID for the operation. Use the API to obtain the details such as the list of delivered files.
bbok: Indicates "yes" if the delivery operation was successful and "no" if it failed.
bberror: Only available if the operation failed: A string with a short error message, in case the operation failed.

Getting details of operation

Once your system has received the callback, you would extract the "bbid" and the "bbproject" properties from the URL.

The former is the unique operation ID. See below how to now fetch the details with the API.
Use the latter to know to which project to authenticate (with the connector credentials)

With the bbid value you can now connect to the Beebox project and fetch all the details for the delivered files.

The API method to get the event details: API - Full event details
An example for event details: Event Details - Created Translated Files