- Previous: Legacy APIs (Deprecating)
- Up: Legacy APIs (Deprecating)
- Next: Public API
Web Services Handshake (Legacy) - Notification and Command Messages
The handshake is a set of web services available for integration between Global Partners (GP) and Compassion's Global Ministry Center (GMC). It contains a set of notification messages sent from Compass to GPs, a set of command messages that can be used by GPs to create or update data at the GMC, and a number of services for retrieving data on demand. This document is primarily focused on describing the notification and command messages to be used between GPs and the GMC in business integration use cases. It is updated as new testing is completed to convey answers to common questions.
All of the notification and command messages are delivered through a service known as the OnRamp. The GMC has an OnRamp for receiving messages from GPs and each GP has an OnRamp for receiving messages from the GMC. Details about the OnRamp and how it is configured are available from the Enterprise Services team.
For more information, download the OnRamp WSDL document.
Business Integration Use Cases
Use Case |
Associated Notification or Command Messages |
---|---|
The GP requests from the GMC some quantity of active, unsponsored children for marketing purposes. |
GMC sends AllocateChild notification |
Active, unsponsored, un-consigned children are grouped to create a consignment for a marketing event or website. |
None. This is only at the GP |
A GP event or website results in a sponsorship request. The constituent and the commitment between constituent and child is created in the GP system. Note: If this is a ChildSponsorship commitment, it is assumed to be a funded commitment. |
GP sends CreateConstituent or UpsertConstituent command message GMC sends ConstituentCreated or ConstituentUpserted command response GP sends CreateCommitment command message with ConstituentActivityType of “ChildSponsorship” GMC sends CommitmentCreated command response |
A GP event or website results in a correspondence sponsorship request. The constituent iand the letter-writing commitment between constituent and child is created in the GP system. Note: If this is a ChildCorrespondenceSponsorship commitment. A correspondence commitment can only be created for a sponsored child (already has a funded commitment.) |
GP sends CreateConstituent or UpsertConstituent command message GMC sends ConstituentCreated or ConstituentUpserted command response GP sends CreateCommitment command message with ConstituentActivityType of “ChildCorrespondenceSponsorship” GMC sends CommitmentCreated command response |
An active, unsponsored child, currently allocated to an GP, receives a new case study and photo every eighteen months. |
GMC sends UpdateChild notification with Event="Image" or "CaseStudy" |
An active, unsponsored child, currently allocated to an GP, transfers from one program to another. |
GMC sends UpdateChild notification with Event="Transfer" |
An active, unsponsored child, currently allocated to an GP, exits the Compassion program. |
GMC sends DepartChild notification message |
An active, sponsored child, currently allocated to an GP, receives a new case study and photo every eighteen months. |
GMC sends UpdateChild notification with Event="Image" or "CaseStudy" |
An active, sponsored child, currently allocated to an GP, transfers from one program to another. |
GMC sends UpdateChild notification with Event="Transfer" |
An active, sponsored child, currently allocated to an GP, exits the program. |
GMC sends DepartChild notification message |
A child who had previously exited the program returns to the program and is reinstated. They are still allocated to the same GP. |
GMC sends AllocateChild notification |
A constituent calls to indicate they can no longer afford to sponsor the child and cancels the commitment. |
GP sends CancelCommitment command message GMC sends CommitmentCanceled command response |
A constituent contacts the GP to indicate that their name has changed. |
GP sends UpdateConstituent or UpsertConstituent command message GMC sends ConstituentUpdated or ConstituentUpserted command response |
A constituent contacts the GP to indicate that their email address has changed. |
GP sends UpdateEmail command message GMC sends EmailUpdated command response |
A constituent contacts the GP to send a gift to their sponsored child. |
GP sends CreateGift command message GMC sends GiftCreated command response |
A constituent writes a letter to their child and mails it to the GP. |
None. This is only at the GP |
An GP requests that currently allocated, unsponsored, un-consigned children be released back to the GMC. |
GMC sends DeallocateChild notification |
A sponsor with an active commitment with another GP requests for his or her account to be transferred to this GP. |
GMC sends AllocateChild notification |
Receiving Notification Messages from the GMC
Allocate Child Message
This message is used to notify the GP that a child has been assign to them for marketing purposes or supporter-beneficiary communication. Usually it occurs because the GP has requested more children to add to its marketing efforts. It will also occur when a constituent with an active commitment is being transferred from one GP to another.
Update Child Message
This message is used to notify the GP that a child currently allocated to them has new information. The message indicates whether there is a new image, the child’s case study has changed, or the child has transferred to another program.
Deallocate Child Message
This message is used to notify the GP that their requested de-allocation of a child has occurred in Compass. The child, which should have been put on hold before requesting deallocation, can now be removed from their system.
Depart Child Message
This message is used to notify the GP that a child has left the Compassion program. This can be a result of graduation or for a variety of other reasons, such as moving to a place where there are no Compassion projects.
Update Project Message
This message is used to notify the GP that the information available about a Compassion program at an Implementing Church Partner has been updated. Currently, there is no way to indicate what portion of the data has changed. This comparison will need to be done manually.
Processing Notification Messages from the GMC
Allocate Child Message
Processing - when this message arrives, please take the following steps in the GP system:
- Add the child to your system making sure to use both the ChildId and the ChildKey.
Note: The ChildId is unique to this child regardless of which project they participate in. The ChildKey, on the other hand, is associated with the child while they are in a particular project. If they transfer to a new project, they will receive a new ChildKey, while retaining the same ChildId. Set initial status of the child to OnHold so they will not be included in any consignments.
- Use the ChildKey to call web services to gather as much information as needed for advocacy and marketing purposes. For example: GetChildInformation, GetChildImage, GetChildCaseStudy, GetProgramImplementor.
- GetChildInformation contains a field called SponsorFlag that indicates whether the child is currently sponsored. If not, set the child’s status to Available.
- If the child is currently sponsored, keep status OnHold so that the child won’t be included in any consignments. Manual data entry will be needed to add the constituent to the GP system. Then a commitment can be created between the constituent and child, at which point the child’s status can be set to Sponsored.
- For additional information regarding the implementing church, the program or geographic information call: GetLocalChurchPartner, GetCDSPImplementor, GetProjectAgeGroups, GetCSPImplementor, GetCommunity, GetCountry.
Update Child Message
Processing - when this message arrives, please take the following steps in the GP system:
An Update Child Message will have different processing based upon the Event
- For Event=Image
- Call GetChildImage and update your system with the latest child photo
- Trigger additional manual or automatic business process – i.e. send new photo to constituent
- For Event=CaseStudy
- Call GetChildCaseStudy and update your system with the latest data about the child
- Trigger additional manual or automatic business process - translation, notification to sponsor, etc.
- For Event=Transfer
- This event means the child has moved from one project to another. This means that the child must be found in your system by ChildId, and the ChildKey should be updated. You will need to ensure that you update child information as well as program implementor information, local church information, as needed.
- Trigger additional manual or automatic business process - translation, notification to sponsor, etc.
Deallocate Child Message
Processing - when this message arrives, please take the following steps in the GP system:
This message means that the child was allocated to another partner and should no longer be marketed by the GP.
When this message arrives, essentially the child must become Inactive. However, the processing of the message will vary based upon the state the child is in when the message arrives.
- For CurrentState= OnHold or Available - make the child Status=Inactive
- For CurrentState=Inactive – no action needs to be taken
- For CurrentState=Consigned - this is an error. Flag the error for an operator. Do not change child Status. Children should be removed from consignments before requesting that the GMC re-allocate to another GP.
- For CurrentState= Sponsored - this is an error. Flag the error for an operator. Do not change child Status. Sponsored children should not be deallocated except under special circumstances.
Depart Child Message
Processing - when this message arrives, please take the following steps in the GP system:
When a child departs from the Compassion program this can be for a variety of reasons. The reasons can be found in the GetChildExitDetail service call.
Processing of the response will be different depending upon the status of the child
- For child Status=Sponsored, set child status to OnHold
- Call GetChildExitDetail and update your system with the latest exit details about the child
- Trigger additional manual or automatic business process – translation, notification to sponsor, etc. (For example: One GP solution looks up a possible substitute child and creates a case for the SDR-Sponsor Donor Relations worker.)
- For child Status= Consigned, Available, OnHold, set child status to Inactive.
Update Project Message
Processing - when this message arrives, please take the following steps in the GP system:
This message means that one of the fields in the program or project information has been updated.
There is currently no way to receive a notification of which fields have changed.
- Call services related to program and project to get the latest information (GetProgramImplementor, others)
- Trigger additional manual or automatic business process - translation, notification to sponsor, etc.
Sending Command Messages to the GMC
Create Constituent Message
[Deprecated] This message is used by the GP when a constituent is created in the GP system. Send this Command message to the GMC to keep Compass in sync.
Update Constituent Message
[Deprecated] This message is used by the GP when a constituent Name, FirstName or LastName is updated in the GP system. Send this Command message to the GMC to keep Compass in sync.
Upsert Constituent Message
This message is used by the GP when a constituent is created in the GP system. Send this Command message to the GMC to keep Compass in sync.
This Command message is recommended in place of both CreateConstituent and UpdateConstituent.
Create Email Message
This message is used by the GP when a constituent provides their email address in the GP system. Send this Command message to the GMC to keep Compass in sync.
UpdateEmail
This message is used by the GP when a constituent changes their email address in the GP system. Send this Command message to the GMC to keep Compass in sync.
Create Commitment Message
This message is used by the GP when a constituent creates their sponsorship or correspondence commitment in the GP system. Send this Command message to the GMC to keep Compass in sync. If a commitment is considered unfunded, it would be best to wait until funding is complete before sending the commitment.
If the GP sends only a ChildSponsorship commitment, it is assumed that this constituent will be the letter-writer for the child. There is no need to send both ChildSponsorship and ChildCorrespondenceSponsorship for the same constituent.
If the GP sends both a ChildSponsorship commitment and a ChildCorrespondenceSponsorship commitment (each with a different constituent id) both constituents need to have been created in Compass and all correspondence will go to the constituent with the ChildCorrespondenceSponsorship.
Cancel Commitment Message
This message is used by the GP when a constituent cancels their sponsorship or correspondence commitment in the GP System. Send this Command message to the GMC to keep Compass in sync.
Create Gift Message
This message is used by the GP when a constituent sends a gift in the GP system. The message can be used for family gifts, birthday gifts, graduation gifts, project gifts, or general gifts. Send this Command message to the GMC to keep Compass in sync.
Receiving Command Responses from the GMC
Command responses are sent by Compass to the GP so that the GP system will know whether their original command message succeeded. Since this response is sent asynchronously, the GP system will need to correlate this response back to their original command message using the message headers. The RequestCorrelationId header of this response will contain the RequestId of the original command message. To learn more see the Messaging Standard.
Constituent Created Message
This response message is sent by Compass to indicate whether or not the constituent was successfully created in the Compass system. If not, the message will contain a Status=Failure and description of the failure.
Constituent Updated Message
This response message is sent by Compass to indicate whether or not the constituent was successfully updated in the Compass system. If not, the message will contain a Status=Failure and description of the failure.
Constituent Upserted Message
This response message is sent by Compass to indicate whether or not the constituent was successfully added or updated in the Compass system. If not, the message will contain a Status=Failure and description of the failure.
Email Created Message
This response message is sent by Compass to indicate whether or not the constituent's email address was successfully created in the Compass system. If not, the message will contain a Status=Failure and description of the failure.
Email Updated Message
This response message is sent by Compass to indicate whether or not the constituent's email address was successfully updated in the Compass system. If not, the message will contain a Status=Failure and description of the failure.
Commitment Created Message
This response message is sent by Compass to indicate whether or not the constituent's commitment was successfully created in the Compass system. If not, the message will contain a Status=Failure and description of the failure.
Commitment Cancelled Message
This response message is sent by Compass to indicate whether or not the constituent's commitment was successfully cancelled in the Compass system. If not, the message will contain a Status=Failure and description of the failure.
Gift Created Message
This response message is sent by Compass to indicate whether or not the constituent's gift was successfully accepted in the Compass system. If not, the message will contain a Status=Failure and description of the failure.
Processing Command Responses from the GMC
Constituent Created Message
Processing- when this message arrives, please take the following steps in the GP system:
- If Status=Success
- Update the status of the original command message that it was successful. The constituent is now in Compass and can be connected to commitments.
- We can trigger the “Next Transaction” which may be the CreateCommitment.
- If Status=Failure
- Update the status of the original command message that it was not successful and log the included error message. The constituent is not confirmed in Compass. The GP system and GMC system are now out of sync. This situation needs to be corrected and retried before any dependent messages can be processed.
- Trigger additional manual or automatic business process to fix and resend if possible.
- Common failure messages that are returned with ConstituentCreated message
- ”Error: Constituent ID (@con_id): 10011 already exists.”
The constituent already exists. This would catch the case in which a ConId was used for more than one constituent. This can also be a false negative if the intended constituent associated with this Constituent Id was already successfully created.
- ”Error: Constituent ID (@con_id): 10011 already exists.”
Constituent Updated Message
Processing - when this message arrives, please take the following steps in the GP system:
- If Status=Success
- Update the status of the original command message that it was successful.
- Generally an update to the constituent has no follow on steps.
- If Status=Failure
- Update the status of the original command message that it was not successful and log the included error message. The update to the constituent is not confirmed in Compass. The GP system and GMC system are now out of sync. This situation needs to be corrected and retried.
- Trigger additional manual or automatic business process to fix and resend if possible.
- Common failure messages that are returned with ConstituentUpdated message
- “” The constituent cannot be updated because it was never successfully created.
- “Error: No rows updated for Constituent (10201); No update was performed. Contact Compassion IT for support.
Constituent Upserted Message
Processing - when this message arrives, please take the following steps in the GP system:
- If Status=Success
- Update the status of the original command message that it was successful.
- We can trigger the “Next Transaction” which may be the CreateCommitment if this is the original creation of the constituent. If this is an update to the constituent, generally there are no further steps to take.
- If Status=Failure
- Update the status of the original command message that it was not successful and log the included error message. The constituent is not confirmed in Compass. The GP system and GMC system are now out of sync. This situation needs to be corrected and retried before any dependent messages can be processed.
- Trigger additional manual or automatic business process to fix and resend if possible.
Email Created Message
Processing - when this message arrives, please take the following steps in the GP system:
- If Status=Success
- Update the status of the original command message that it was successful.
- If Status=Failure
- Update the status of the original command message that it was not successful and log the included error message. The constituent’s email is not confirmed in Compass. The GP system and GMC system are now out of sync. This situation needs to be corrected and retried before any dependent messages can be processed.
- Trigger additional manual or automatic business process to fix and resend if possible.
- Common failure messages returned in an EmailCreated message
- “Error: Constituent (10180) does not exist” Email cannot be created. Check that the Constituent was properly created before resending.
Email Updated Message
Processing - when this message arrives, please take the following steps in the GP system:
- If Status=Success
- Update the status of the original command message that it was successful.
- If Status=Failure
- Update the status of the original command message that it was not successful and log the included error message. The update of the constituent’s email is not confirmed in Compass. The GP system and GMC system are now out of sync. This situation needs to be corrected and retried.
- Trigger additional manual or automatic business process to fix and resend if possible.
- Common failure messages returned in EmailUpdated messages
- “The email address has an invalid format.” Check the email address and ensure it has a valid format before resending.
- “Empty EmailAddress node in message” Check the email address and resend.
Commitment Created Message
Processing - when this message arrives, please take the following steps in the GP system:
- If Status=Success
- Update the status of the original command message that it was successful.
- Update the Commitment in the GP system so that it is confirmed.
- Trigger additional manual or automatic business process.
- If Status=Failure
- Update the status of the original command message that it was not successful and log the included error message. The commitment is not confirmed in Compass. The GP system and GMC system are now out of sync. This situation needs to be corrected and retried.
- Trigger additional manual or automatic business process to fix and resend if possible.
- Common failure messages returned in CommitmentCreated message
- “Error: Constituent (10221) does not exist” The CreateCommitment command can fail if the constituent does not exist in Compass. This generally happens when the GP system has not confirmed that the CreateConstituent command succeeded before sending the CreateCommitment command.
- “Error: Program for this Need is not allowing new Commitments” The program is on a status that does not allow new sponsorships.
- “Error: Program for this Need is not Active” The program is not active and cannot accept sponsorships.
- The CreateCommitment command can fail if the child is not available for sponsorship.
Commitment Cancelled Message
Processing - when this message arrives, please take the following steps in the GP system:
- If Status=Success
- Update the status of the original command message that it was successful.
- Update the Commitment in the GP system so that it is now confirmed to be cancelled.
- Trigger additional manual or automatic business process.
- If Status=Failure
- Update the status of the original command message that it was not successful and log the included error message. The cancellation of the commitment is not confirmed in Compass. The GP system and GMC system are now out of sync. This situation needs to be corrected and retried.
- Trigger additional manual or automatic business process to fix and resend if possible.
- Common failure messages returned in CommitmentCancelled message
- The constituent in the message does not have an active commitment of the right type with this child. Error: Constituent ID (@con_id) - 10297 does not have a (CHISPN) commitment to Need Key (@need_key) - PH6720084
Gift Created Message
Processing - when this message arrives, please take the following steps in the GP system:
- If Status=Success
- Update the status of the original command message that it was successful.
- Trigger additional manual or automatic business process.
- If Status=Failure
- Update the status of the original command message that it was not successful and log the included error message. The gift is not confirmed in Compass. The GP system and GMC system are now out of sync. This situation needs to be corrected and retried.
- Trigger additional manual or automatic business process to fix and resend if possible.
- Common failure messages returned in GiftCreated message
- “Error: Constituent: (11097) is not the sponsor of this child: PE5510344” The constituent referenced in the gift message is not in an active commitment with this child.
- “Error: Child has been departed longer than allowed to receive a gift” The child has departed and can no longer receive gifts.
Rare Cases
Under rare cases, Compass may throw an unexpected SQL error message all the way back to the partner. It might look like this: “Cannot insert duplicate key row in object 'dbo.cm' with unique index 'uk_cm_con_line_nbr_seq_nbr'. The duplicate key value is (10982, 77, 1, 1). Error inserting Commitment data in procedure uspAPICommitmentNonCompassInsert Error: 2601 Rowcount: 0 The statement has been terminated.” In cases like this, please contact Compassion IT for assistance. Be prepared to provide the RequestId included in your original command message.
Retrieving Data on Demand from the GMC
All services for retrieving data on demand from the GMC are available through Compassion’s Developer Portal.
Sign up for an account and contact the Enterprise Services team (ITSOA@us.ci.org) to indicate you need access to the private APIs for GPs.
All of the documentation you need to call services in either SOAP or REST is available on the developer portal once you have the proper access to the private APIs.
Private APIs Available
Private SOA SOAP IPTest API – Test SOAP Services for data on demand
Private SOA SOAP API – Production SOAP Services for data on demand
Private SOA REST IPTest API – Test REST Services for data on demand.
Private SOA REST API – Production REST Services for data on demand.
Type of Data Available Through Private APIs
Using the private APIs you may retrieve data in either SOAP/XML, REST/XML or REST/JSON.
Child Information – the core data about a child including name, age, hobbies, and family.
Child Case Study – more extensive data gathered to give a more complete picture of the child
Child Exit Details – provides information when a child has departed the Compassion program
Child Image – the latest image on file for the child
Program Implementor – details about the program in which the child is registered
Local Church Partner – more detailed information about the church hosting the child’s program
CDSP Implementor – details about the program in which the child is registered. Contains substantial overlap with Program Implementor.
Project Age Groups – a listing of the different groupings of children along with the months and days of the week when the program is active.
CSP Implementor – details about the program in which the child is registered. Contains substantial overlap with Program Implementor.
Community – information about the wider community in which the church resides.
Country – information about the country in which the project resides.
All of these are available as either SOAP or REST service calls. Please see the developer portal for details.
- Previous: Legacy APIs (Deprecating)
- Up: Legacy APIs (Deprecating)
- Next: Public API
Docs Navigation
- Compassion API Library
- Standards Documents
- Legacy APIs (Deprecating)
- Web Services Handshake (Legacy) - Notification and Command Messages
- Public API
- Private IPG APIs
- Private REST Services
- REST Get CDSP Implementor V1
- REST Get Child Case Study V1
- REST Get Child Exit Details V1
- REST Get Child Image V1
- REST Get Child Information V1
- REST Get Community V1
- REST Get Country V1
- REST Get CSP Implementor V1
- REST Get Local Church Partner V1
- REST Get Program Implementor V1
- REST Get Project Age Groups V1
- REST Get Child Image V1 - 2015/03
- Private Messaging APIs
- Quick Start Guide
- OffRamp Prerequisites and Setup
- IP OnRamp Service Configuration
- Available Message Types
- Message and Service Relationships
- Troubleshooting
- General Error Messages from Compass Party Host
- EsdMessageErrorMOE Sample
- Sample REST End-To-End Test Plan
- SOAP Wrapper Sample for Messages to GMC
- Allocate Child Message
- Cancel Commitment Message
- Commitment Canceled Message
- Commitment Created Message
- Constituent Created Message
- Constituent Updated Message
- Constituent Upserted Message
- Create Commitment Message
- Create Constituent Message
- Create Email Message
- Create Gift Message
- Deallocate Child Message
- Depart Child Message
- Email Created Message
- Email Updated Message
- Gift Created Message
- Update Child Message
- Update Constituent Message
- Update Email Message
- Upsert Constituent Message
- Update Project Message
- Private SOAP Services
- SOAP Get Child Exit Detail 201211
- SOAP Get Child Exit Detail 201310
- SOAP Get CDSP Implementor 201309
- SOAP Get Child Image 201211
- SOAP Get Child Case Study 201310
- SOAP Get Child Case Study 201412
- SOAP Get Child Information 201211
- SOAP Get Child Information 201310
- SOAP Get Community 201309
- SOAP Get Country Information 201104
- SOAP Get Local Church Partner 201309
- SOAP Get Program Implementor 201303
- SOAP Get Program Implementor 201309
- SOAP Get Project Age Group 201309
- Service Overview
- SOAP Get CSP Implementor 201309
- SOAP Get Child Image 201503
- Private USA APIs
- Private USA Web APIs
- private cornerstone connect messaging
- private cornerstone test
- public api
0 Comments
New comments are not being accepted at this time.