Managing Integration Dependencies

info

All RaiseNow and Altruja customers have been approached via the designated organisation contacts regarding migration of your subscription from the legacy platforms to the new RaiseNow Hub. If you aren't aware of any communications to that end, please contact RaiseNow support as soon as possible.

Subscriptions migrated from either Altruja or RaiseNow Manager will have the following element in custom_parameters:

{
  "migrated_at": "timestamp",
  "source": "epp|altruja",
  "source_identifier": "<epp_subscription_token>|<altruja_donation_id>",
  "source_organisation_identifier": "<epp_merchant_id>|<altruja_charity_id>",
}

Partners or customers who have integrated Altruja or the RaiseNow Manager have to adapt their integrations for compatibility with RaiseNow Hub. Please visit this article for possible integration strategies. For customers using an integration provided by RaiseNow, we provide an automated migration process. See below for the various supported target systems.

Custom Integrations

In order to update records in a third party system, you can use one of the following two approaches.

Query Search API

After the migration, use the below search query to retrieve all migrated subscriptions from RaiseNow Hub. Replace epp|altruja as appropriate. The retrieved result set will contain the new uuids for the migrated RaiseNow subscription records. In the custom_parameters object you will find the identifiers of the original subscription from the legacy system.

tip

You can specify the ìncludes element as an empty array to return all available fields in the search results.

POST {{base_url}}/search/subscriptions
{
  "query": {
    "$and": [
      {
        "$term": {
          "status": "active"
        }
      },
      {
        "$term": {
          "custom_parameters.source": "epp|altruja"
        }
      },
            {
        "$term": {
          "organisation_uuid": "{{organisation_uuid}}"
        }
      }
    ]
  },
  "size": 10000,
  "from": 0,
  "includes": ["uuid","amount","custom_parameters","payment_method"],
  "excludes": [],
  "aggs": {
    "status": {
      "field": "status",
      "type": "terms"
    }
  },
  "sort": {
    "created": "DESC"
  }
}

The result set will contain the new Hub subscription_uuid as well as the legacy id from Altruja|RaiseNow Manager. Based on this result, customers & partners can update their systems.

Example response:

{
    "summary": {
        "hits": 1,
        "last_sort_values": [
            1731600482000
        ]
    },
    "hits": [
        {
            "amount": 100,
            "custom_parameters": {
                "migrated_at": "1731600481",
                "source_organisation_identifier": "wer-3d03gk",
                "source": "epp",
                "source_identifier": "b2a3raa62bdb25d484e958e1160565e58b57a12c"
            },
            "uuid": "f9899975-209f-4a16-afcf-8312516ccfae",
            "payment_method": "card"
        }
    ],
    "aggregations": {
        "status": [
            {
                "key": "active",
                "doc_count": 1
            }
        ]
    }
}

If you need to search RaiseNow Hub for a specific subscription based on the id from the legacy system, you can use this query to identify the new record in RaiseNow Hub.

POST {{epms_base_url}}/search/subscriptions
{
  "query": {
    "$and": [
      {
        "$term": {
          "status": "active"
        }
      },
      {
        "$term": {
          "custom_parameters.source_identifier": "{{epp_subscription_token|altruja_donation_id}}"
        }
      }
    ]
  },
  "size": 10000,
  "from": 0,
  "includes": ["uuid","amount","custom_parameters","payment_method"],
  "excludes": [],
  "aggs": {
    "status": {
      "field": "status",
      "type": "terms"
    }
  },
  "sort": {
    "created": "DESC"
  }
}

Subscribing to event notifications

warning

This approach has the significant advantage, that it will work automatically and without any coordination required when the subscription import is executed. However, when RaiseNow imports subscriptions from the legacy system to RaiseNow Hub, this approach will result in subscription.created and subscription.activated events being fired in close succession. Depending on the number of subscriptions active in the legacy system for the given customer, this may result in significant load on the target endpoint/system. The customers/partners target system must be able to cope with the resulting load. See our section on webhook retries regrading unresponsive target systems for more information on the handling of error responses from the target system.

Partners can subscribe to receive event notifications on the subscription.activated event. Such an event subscription will result in the RaiseNow systems automatically sending notifications to the defined target system when a new subscription is activated on RaiseNow Hub. That event subscription will contain the custom_parameters element as described in the mapping section for Altuja or RaiseNow Manager. The target system can then execute business logic to update records as needed.

RaiseNow Integrations (RICE)

Salesforce NPSP Integration

Starting with backend integration version v1.20.4, RaiseNow will automatically update records in Salesforce when these are being imported into RaiseNow Hub. During this process, the following objects and fields will be updated in Salesforce:

npe03__Recurring_Donation__c.RaiseNow__RaiseNow_Subscription_Token__c: Will be updated with the subscription_uuid from RaiseNow Hub.
RaiseNow__Customer__c.RaiseNow__Customer_Identifier__c: Will be updated with the supporter_uuid from RaiseNow Hub.
RaiseNow__Payment_Source__c.RaiseNow__Payment_Source_Identifier__c: Will be updated with the payment_source_uuid from RaiseNow Hub.
RaiseNow__Payment_Source__c.RaiseNow__Account_Identifier__c: Will be updated with the account_uuid from RaiseNow Hub.
RaiseNow__Subscription__c.RaiseNow__Subscription_Identifier__c: Will be updated with the subscription_uuid from RaiseNow Hub.
RaiseNow__Subscription__c.RaiseNow__Account_Identifier__c: Will be updated with the account_uuid from RaiseNow Hub.
RaiseNow__Subscription__c.RaiseNow__Payment_Source__c: Will relate to above RaiseNow__Payment_Source__c

Integration to Microsoft Dynamics Nonprofit Accelerator

msnfp_paymentschedule.rnw_raisenowsubscriptionidentifier: Will be updated with the subscription_uuid from RaiseNow Hub.
msnfp_donorcommitment.rnw_raisenoworganisationidentifier: Will be updated with the organisation_uuid from RaiseNow Hub.
msnfp_donorcommitment.rnw_raisenowaccountidentifier: Will be updated with the account_uuid from RaiseNow Hub.
msnfp_donorcommitment.rnw_raisenowsubscriptionidentifier: Will be updated with the subscription_uuid from RaiseNow Hub.
Contact.Contact: Will be updated with the supporter_uuid from RaiseNow Hub.

SEXTANT Integration

For the SEXTANT integration, RaiseNow will automatically send an import request to SEXTANT for the RaiseNow Contract Renewals import definition. This will contain:

RaiseNowNewContractId: subscription_uuid from RaiseNow Hub
RaiseNowOldContractId: legacy_subscription_id from RaiseNow Manager

OM Integration

Coming soon

Salesforce Nonprofit Cloud Integration

A migration for the Salesforce Nonprofit Cloud is not required as recurring payments are not managed through the RaiseNow Manager.

Managing Integration Dependencies

Custom Integrations​

Query Search API​

Subscribing to event notifications​

RaiseNow Integrations (RICE)​

Salesforce NPSP Integration​

Integration to Microsoft Dynamics Nonprofit Accelerator​

SEXTANT Integration​

OM Integration​

Salesforce Nonprofit Cloud Integration​