Sync Adapter Boilerplate

This is a boilerplate for a ChurchTools sync adapter, which can be used to synchronize data between a ChurchTools system and other systems. The adapter is designed to be used by ChurchTools and the ChurchTools sync worker.

General concepts

The adapter is a Node.js application that provides a REST API for ChurchTools and the synchronization system to access it. It supports various domain types, such as persons, transactions, accounts, and so on. The adapter acts as a proxy to the external system, allowing ChurchTools to perform CRUD operations on the data in the external system.

The adapter is designed to be flexible and extensible, allowing developers to add support for new domain types or modify existing ones. It uses a modular architecture, with separate controllers for each domain type (in src/domains).

Adapter specific details, such as the name, logo, and connection details for the external system, are defined in adapterDetails.js.

Supported domain types

ChurchTools currently supports the domain types person, transaction, account, cost_center, account_group, account_class and account_type for syncing. To adjust the domain types supported by the adapter, the getDomainTypes in adapterDetails.js needs to be modified.

New domain types

To add support for a new sync domain type (not yet supported by ChurchTools), the following steps need to be performed:

1. Ask ChurchTools if the domain type could be added to the ChurchTools sync adapter. If yes, ask for a domain type key (e.g. appointment), which will be used in the sync adapters.
2. Add the domain type to the getDomainTypes function in adapterDetails.js.
3. Create a new controller in src/domains, e.g. appointmentController.js, based on one of the existing controllers.
4. Implement the CRUD operations for the new domain type in the new controller.
5. Implement the field mappings for the new domain type in the new controller.
6. Test the new domain type with the external system via Swagger or Postman.
7. Test the new domain type with ChurchTools, once the domain type is supported by the ChurchTools sync adapter.

Field mappings

For each supported domain type, the adapter provides endpoints (getMapping) to get information for the field mappings between ChurchTools and the external system. For each field, the following information is provided:

Mandatory field settings

• key: an arbitrary key, which identifies the field, e.g. 'length'
• name: a ChurchTools i18n key for the name of the field, e.g. 'length',
• fieldTypeCode: the type of the field, one of text, number, select, multiselect, date, member, checkbox, domainTypeReference
• length: the maximum length of the field (each value will be compared as text, so even number have a length), e.g. 255
• options: an array of options, if the fieldTypeCode is select or multiselect, e.g. [ { id: 'mr', name: 'Mr.' }, { id: 'ms', name: 'Ms.' } ]. The id is the value that is stored in ChurchTools or the other system, the name is the display name of the option. For non-select fields, this array has to be empty.

Optional field settings

• nameAddendum: an optional ChurchTools i18n key for an addendum to the name, e.g. 'characters'
• memberI18nKey: i18n key for the member, if the fieldTypeCode is member, e.g. role.in.x
• referenceType: the referenced domain type, if the fieldTypeCode is domainTypeReference, e.g. person

Optional field flags (default: false)

• required: whether the field is required or not, true or false
• nullable: whether the field can be set to null, true or false
• nooverwrite: whether the field can not be overwritten if it already has a value, true or false
• canBeIncomplete: whether the field can be incomplete, true or false
• extendOnly: whether the field can only be extended, but not reduced, e.g. for emails, true or false
• matchingOnly: whether the field is only used for matching, but not for syncing, true or false
• noMapping: whether the field can not be mapped, true or false
• createDefaults: if set to true, the user has to configure a default value for the field mapping, if no value is provided in the sync data. This is typically used for fields that are required in the external system, but not in ChurchTools or vice versa. true or false

API

The adapter API is roughly divided in two parts:

• endpoints to get static or dynamic information about the adapter, starting with /adapter
• endpoints for CRUD operations for the supported domain types

Error handling

The adapter uses HTTP status codes to indicate the success or failure of requests. The following status codes are used:

• 200 OK: The request was successful.

• 500 Server Error: An error occurred on the server while processing the request.

• Errors should be returned in the code like this:

return res.status(statusCodes.INTERNAL_ERROR).json({
    status: statusCodes.INTERNAL_ERROR,
    statusText: errorMessage
});

Development

All adjustable source files are found in the directory src. All other files are boilerplate code and should not be changed.

For a new adapter, only three files need to be adjusted:

• adapterDetails.js
• src/domain/<domain>Controller.js (for each supported domain type)
• clientFor<ExternalSystem>.js (for the external system the adapter is connecting to)

adapterDetails.js contains

• general information about the adapter, like the name
• a logo resource url
• the connection details for the external system, such as the API URI and authentication token, as header names
• the domain types supported by the adapter and which operations (get, post, put, delete, archive, ...) are supported for each domain type

The API endpoints are configured in lib/api.js. The /adapter endpoints are handled by the generic lib/adapterController.js, the /<domain> endpoints and the mapping and filter adapter-endpoints for the respective domain are handled by the domain specific src/domain/<domain>Controller.js.

The clientFor<ExternalSystem>.js file contains the code to connect to the external system. It is used by the domain controllers to perform the actual CRUD operations on the external system. Although the methods are named like REST API methods (get, post, put, delete), they can use any protocol to connect to the external system. The client is responsible for login and session management, if required by the external system, as well as rate limit handling.

Swagger

To open the swagger api documentation, run the adapter with node index.js and open http://localhost:8090/api-docs.

Examples

In the directory 'churchtoolsDomains' there are example implementations for the domain types person, transaction and several other finance related domain types, which can be used as a starting point for implementing other domain types.

Configuration

The adapter uses a .env file for configuration. The following configuration options (shown with their default values) can be set :

PORT=8090
LOGGING_TO_CONSOLE=true
LOGGING_TO_FILE=false
LOGGING_PATH=/var/log/syncAdapter
LOGGING_LEVEL=debug
X_ADAPTER_AUTH=<a random secret>

# graylog options
LOGGING_TO_GRAYLOG=true # default=false
GRAYLOG_HOST=graylog01.ct-srv.de # default=localhost
GRAYLOG_PORT=12201 # default=12201

For X_ADAPTER_AUTH a secret must be set, this is the only non-optional configuration option.

Execution

Simply run node index.js.

Security

To be able to access the adapter endpoints that return sensitive data, the caller needs to provide the configured secret in the header X_ADAPTER_AUTH.

For API endpoints, that access the external system (all CRUD endpoints for domains types, as well as /adapter/testconnection and /adapter/mapping/...), the connection headers defined in adapterDetails.js must be provided in the request headers. E.g.

• X_ES_API_URI: the URI to the external system
• X_ES_AUTH: access token for the external system

Registering a new adapter with a ChurchTools system

To register a new adapter with a ChurchTools system, the adapter has to be added to the ChurchTools database. This can be done via the ChurchTools API:

curl -X POST "https://<churchtools-url>/api/sync/adapters" \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "<adapter name>",
  "token": "<X_ADAPTER_AUTH value>",
  "url": "<url of the adapter, publicly accessible>",
}'

Once the adatper is registered, it can be used in ChurchTools to configure sync connections.