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:

  1. 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.
  1. 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.
    1. GetChildInformation contains a field called SponsorFlag that indicates whether the child is currently sponsored. If not, set the child’s status to Available.
    2. 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.

    3. 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

  1. For Event=Image
    1. Call GetChildImage and update your system with the latest child photo
    2. Trigger additional manual or automatic business process – i.e. send new photo to constituent
  2. For Event=CaseStudy
    1. Call GetChildCaseStudy and update your system with the latest data about the child
    2. Trigger additional manual or automatic business process - translation, notification to sponsor, etc.
  3. For Event=Transfer
    1. 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.
    2. 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.

  1. For CurrentState= OnHold or Available - make the child Status=Inactive
  2. For CurrentState=Inactive – no action needs to be taken
  3. 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.
  4. 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

  1. For child Status=Sponsored, set child status to OnHold
    1. Call GetChildExitDetail and update your system with the latest exit details about the child
    2. 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.)
    3. 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.                              

  1. Call services related to program and project to get the latest information (GetProgramImplementor, others)
  2. 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:

  1. If Status=Success
    1. Update the status of the original command message that it was successful. The constituent is now in Compass and can be connected to commitments.
    2. We can trigger the “Next Transaction” which may be the CreateCommitment.
    3. If Status=Failure
      1. 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.
      2. Trigger additional manual or automatic business process to fix and resend if possible.
      3. Common failure messages that are returned with ConstituentCreated message
        1. ”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.

Constituent Updated Message

Processing - when this message arrives, please take the following steps in the GP system:

  1. If Status=Success
    1. Update the status of the original command message that it was successful.
    2. Generally an update to the constituent has no follow on steps.
    3. If Status=Failure
      1. 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.
      2. Trigger additional manual or automatic business process to fix and resend if possible.
      3. Common failure messages that are returned with ConstituentUpdated message
        1. “”  The constituent cannot be updated because it was never successfully created.
        2. “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:

  1. If Status=Success
    1. Update the status of the original command message that it was successful.
    2. 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.
    3. If Status=Failure
      1. 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.
      2. 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:

  1. If Status=Success
    1. Update the status of the original command message that it was successful.
    2. If Status=Failure
      1. 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.
      2. Trigger additional manual or automatic business process to fix and resend if possible.
      3. Common failure messages returned in an EmailCreated message
        1. “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:

  1. If Status=Success
    1. Update the status of the original command message that it was successful.
    2. If Status=Failure
      1. 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.
      2. Trigger additional manual or automatic business process to fix and resend if possible.
      3. Common failure messages returned in EmailUpdated messages
        1. “The email address has an invalid format.”  Check the email address and ensure it has a valid format before resending.
        2. “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:

  1. If Status=Success
    1. Update the status of the original command message that it was successful.
    2. Update the Commitment in the GP system so that it is confirmed.
    3. Trigger additional manual or automatic business process.
    4. If Status=Failure
      1. 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.
      2. Trigger additional manual or automatic business process to fix and resend if possible.
      3. Common failure messages returned in CommitmentCreated message
        1. “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.
        2. “Error: Program for this Need is not allowing new Commitments” The program is on a status that does not allow new sponsorships.
        3. “Error: Program for this Need is not Active” The program is not active and cannot accept sponsorships.
        4. 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:

  1. If Status=Success
    1. Update the status of the original command message that it was successful.
    2. Update the Commitment in the GP system so that it is now confirmed to be cancelled.
    3. Trigger additional manual or automatic business process.
    4. If Status=Failure
      1. 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.
      2. Trigger additional manual or automatic business process to fix and resend if possible.
      3. Common failure messages returned in CommitmentCancelled message
        1. 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:

  1. If Status=Success
    1. Update the status of the original command message that it was successful.
    2. Trigger additional manual or automatic business process.
    3. If Status=Failure
      1. 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.
      2. Trigger additional manual or automatic business process to fix and resend if possible.
      3. Common failure messages returned in GiftCreated message
        1. “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.
        2. “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.

Docs Navigation