CMS

Introduction

The purpose of the CMS integration is to fully automate the flow of contact information between the Church Management System (CMS) and Xledger.

Currently, each diocese must manually update both systems whenever parish contact details change. This integration removes that duplication by synchronising updates automatically. 

Terminology

CMS:

• Parish: An area within a diocese that has its own church and administration.

• Treasurer: The main point of contact for each parish.

• Post record: A record that collates all details relating to a specific post. It includes the Contact, Role, and Place data associated with that post.

• Contact record: Stores the contact information for the person assigned to the post.

• Place record: Contains location information (e.g. name of the place and whether it is a parish, church, or group).

• Role record: Defines all available roles within CMS. Each person is assigned a role.

Xledger

• Company: Represents a parish.

• Customer: Represents the treasurer of the parish.

• Supplier: Also represents the treasurer of the parish.

API Endpoints and Functions

• Get Companies: Retrieves parishes from Xledger. Each parish is set up as its own Company (identified by the "National Reference Number" from CMS) for billing purposes.

• Get Customers: Retrieves contact information for each parish’s main contact (the treasurer) from Xledger.

• Get Suppliers: Retrieves the same contact information but from the supplier record associated with the treasurer.

• Update Customers: GraphQL mutation used to update customer records in Xledger with new CMS contact information.

• Update Suppliers: GraphQL mutation used to update supplier records in Xledger with new CMS contact information.

Steps which need to be actioned:

If the diocese is already using the National Reference Number from CMS as the code for its customer and supplier records in Xledger, no action is required.

If not, each diocese must first update these records to ensure accurate mapping between CMS and Xledger:

1. For every customer and supplier record in Xledger, replace the existing code with the corresponding National Reference Number from CMS.

2. Move the previous code:

   • To the Your reference field for supplier records.

   • To the External identifier field for customer records.

This ensures that the integration can correctly identify and match records between the two systems.

What will be used:

• Xledger GraphQL API

• Church of England CMS API v2

• Cyclr (for orchestration and automation)

Solution description:

The integration performs the following process daily:

1. Retrieve updated post records from the CMS API, limited to those modified on the current day.

   • These include updates to Contact, Role, or Place data.

2. Match the post record to the Xledger company using the National Reference Number from the Place record.

3. Locate the customer record in Xledger by searching within the matched company (using the company’s dbId).

4. Update the customer record with the latest contact information from CMS.

5. Locate and update the supplier record (also matched via the National Reference Number) with the same new contact details.

This ensures that both customer and supplier records in Xledger always reflect the latest information stored in CMS.

Limitations:

• The integration only updates existing Customer and Supplier records, it does not create new ones.

• Any new parishes or contacts must be created manually in Xledger before they can be synchronised.

Process Flow:

Field mappings

Customers Suppliers

Updating Customer Records

updateCustomer (Xledger)	Get Posts (CMS)	Value/notes
Customer DbID	Customer DbID returned from Get Customer	Step 7 in Cyclr.
Code	Company code returned from Get Companies	Step 6 in Cyclr.
Description	Post Place Name
Email	Contact Email address
Street Address	C/O Contact Title + Contact Forenames + Contact Surname + Contact Address1 + Contact Address2 + Contact Address3 + Contact Address4
Zip Code	Contact Address1 Post Code
Place	Contact Address1 Town
Phone	Contact Home Phone
Company DbID	Company DbID returned from Get Companies	Step 6 in Cyclr.

Updating Supplier Records

updateSupplier (Xledger)	Get Posts (CMS)	Value/notes
Supplier DbID	Supplier DbID returned from Get Supplier	Step 10 in Cyclr.
Code	Company code returned from Get Companies	Step 10 in Cyclr.
Email	Contact Email address
Street Address	C/O Contact Title + Contact Forenames + Contact Surname + Contact Address1 + Contact Address2 + Contact Address3 + Contact Address4
Zip Code	Contact Address1 Post Code
Place	Contact Address1 Town
Phone	Contact Home Phone