API Resources

Understanding DataSets

API Documentation

Senest redigeret:

1. Introduction

DataSets are created whenever an end-user interacts with OnlineFundraising. DataSets are the key to:

  • Understanding the full context of an end-user's interaction with OnlineFundraising
  • Adding metadata for custom integrations (datamodel itself is not customisable)

A DataSet is created when either of the following occurs:

  • End-user submits a form (Form)
  • End-user sends a text message (SMS Campaign)
  • Onboarding user submits an Onboarding form on behalf of end-user (Onboarding Form)

DataSets provide insight to:

  • Configuration of FormSMS Campaign, or Onboarding Form
  • Data registered by end-user
  • Payment session result
  • Metadata: Custom data defined by OnlineFundraising user

DataSets exist as transactional and non-transactional.

2. Transactional versus Non-Transactional DataSet

2.1. Transactional DataSet

Transactional data refers to data which is relevant in context of a transaction, either single or recurring. A transactional DataSet is related to all records that are created or updated in context of a transaction.

2.2. Non-Transactional DataSet

OnlineFundraising supports non-transactional forms and SMSes, meaning no transaction is handled upon receiving an SMS or a form registration. Specific to non-transactional events is that no related entities are created. For instance, if an end-user fills out a non-transactional form, a DataSet is created in OnlineFundraising, which is marked as non-transactional. 

3. Breakdown of DataSet

This section breaks down the different parts of a DataSet. Please refer to the API Documentation on DataSets for detailed and up-to-date documentation.

Example of DataSet - Form & Onboarding Form

{
"dataSetGuid": "4e6c4a00-314f-4370-b6c5-xxxxxxxxxxxx",
"merchantId": "onlinefundraising",
"createdTs": "2022-07-12 09:00:14 +0200",
"updatedTs": "2022-07-12 09:00:39 +0200",
"jsonElement": {
"formResult": {
"name": "John Doe",
"email": "john.doe@yourdomain.tld",
"...": "..."
},
"formFields": [
{
"inputType": "text",
"label": "Name",
"name": "name",
"value": "John Doe"
},
{
"inputType": "email",
"label": "Email",
"name": "email",
"value": "john.doe@yourdomain.tld"
},
{
"...": "..."
}
],
"paymentSessionResult": {
"postProcessedTs": "2019-12-31 15:59:59 +0100",
"postProcessingErrorTs": "2019-12-31 15:59:59 +0100",
"postProcessingErrorDescription": "",
"contactGuidResult": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
"paymentMethodGuidResult": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
"agreementGuidResult": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
"subscriptionGuidResult": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
"paymentGuidResult": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx"
}
}
},
"sensitive_data": [
"middleName",
"phone2"
],
"isTransactional": true,
"isThirdParty": false,
"vendor": "My Fundraising Application",
"sourceType": "form",
"sourceGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx"
}

Example of DataSet - SMS

{
    "dataSetGuid": "4ce38735-d769-401c-8fb8-xxxxxxxxxxxx",
    "merchantId": "onlinefundraising",
    "createdTs": "2022-11-03 13:41:08 +0100",
    "jsonElement": {
        "smsMo": {
            "state": "Processed",
            "msisdn": "4526807821",
            "origin": "smsCPH",
            "channel": "1962",
            "keyword": "TEST",
            "createdTs": "2022-11-03 13:41:04 +0100",
            "messageTs": "2022-11-03 13:41:04 +0100",
            "merchantId": "onlinefundraising",
            "keywordGuid": "86338d0c-5c08-4312-85c6-xxxxxxxxxxxx",
            "messageGuid": "00b4acf1-69aa-417c-b9cb-xxxxxxxxxxxx",
            "processedTs": "2022-11-03 13:41:04 +0100",
            "campaignGuid": "549ef96e-633a-451c-bc51-xxxxxxxxxxxx",
            "receivedText": "Test",
            "smscphMessageGuid": "55815ff3-aad7-4258-8650-xxxxxxxxxxxx"
        },
        "smsMt": {
            "text": "Tak for din besked",
            "state": "Delivered",
            "msisdn": "4526807821",
            "channel": "1962",
            "keyword": "TEST",
            "createdTs": "2022-11-03 13:41:04 +0100",
            "serviceId": "1962-TEST",
            "externalId": "1667479264400",
            "merchantId": "onlinefundraising",
            "callbackUrl": "https://SMS-INBOUND-API-URL/SmsCallback",
            "deliveredTs": "2022-11-03 13:41:08 +0100",
            "messageGuid": "44d6a5d5-73a5-4259-b0c1-xxxxxxxxxxxx",
            "senderAlias": "1962",
            "handleCallback": true,
            "moReferenceGuid": "00b4acf1-69aa-417c-b9cb-xxxxxxxxxxxx",
            "smscphMessageGuid": "833a5c73-c062-4aa4-b122-xxxxxxxxxxxx",
            "subscriptionMessage": false
        },
        "keyword": {
            "active": true,
            "channel": "1962",
            "keyword": "TEST",
            "createdTs": "2022-03-14 10:57:10 +0100",
            "merchantId": "onlinefundraising",
            "keywordGuid": "86338d0c-5c08-4312-85c6-xxxxxxxxxxxx",
            "campaignGuid": "549ef96e-633a-451c-bc51-xxxxxxxxxxxx",
            "keywordIdleText": "Hej. Tak for din besked. Keywordet er ikke aktivt."
        },
        "campaign": {
            "unit": "pcs.",
            "active": true,
            "amount": 1.0,
            "oneOff": false,
            "metaData": [
                {
                    "key": "Permission",
                    "value": "Given"
                }
            ],
            "amountVat": 0.0,
            "createdTs": "2022-04-26 11:16:41 +0200",
            "replyText": "Tak for din besked",
            "unitPrice": 1.0,
            "merchantId": "onlinefundraising",
            "amountTotal": 1.0,
            "contentType": "HumanitarianDonation",
            "invoiceText": "TEST",
            "serviceType": "Message",
            "campaignGuid": "549ef96e-633a-451c-bc51-xxxxxxxxxxxx",
            "campaignName": "Message with meta",
            "currencyCode": "DKK",
            "scheduleType": "Monthly",
            "agreementName": "Test-aftale",
            "agreementType": "Personal",
            "taxDeductable": false,
            "vatPercentage": 0.0,
            "cancelReplyText": "Canceltext",
            "scheduleBaseTier": 1,
            "scheduleFixedDay": 1,
            "scheduleEveryOther": 1,
            "scheduleCalendarUnit": "Month",
            "purposeAccountingCode": "PAC",
            "targetAudienceUnderAge": false,
            "failedSmsPaymentReplyText": "Failedtext"
        },
        "formFields": [
            {
                "name": "Permission",
                "value": "Given"
            }
        ],
        "formResult": {
            "Permission": "Given"
        },
        "isTransactional": false,
        "isThirdParty": false,
        "sourceType": "SMS",
        "sourceGuid": "86338d0c-5c08-4312-85c6-xxxxxxxxxxxx"
    }
}

3.1. Configuration of Form, SMS Campaign or Onboarding Form

Forms, SMS Campaigns and Onboarding Forms are configured individually in OnlineFundraising to support the specifik needs of that Form (SMS Campaign or Onboarding Form). The DataSet contains the original configuration.

For instance, for a form, this corresponds to the property formFields of the DataSet (c.f. Example of DataSet). The DataSet contains the original configuration of each field in terms of input type, label, name and value (as provided by end-user):

"formFields": [
{
"inputType": "text",
"label": "Name",
"name": "name",
"value": "John Doe"
},
{
"inputType": "email",
"label": "Email",
"name": "email",
"value": "john.doe@yourdomain.tld"
},
{
"...": "..."
}
]

For a text message, the relevant properties are keyword and campaign.

3.2. Data Registered by End-user

The data registered by the end-user is summarised in the DataSet. For a form, this corresponds to the property formResult of the DataSet (c.f. example of DataSet):

"formResult": {
"name": "John Doe",
"email": "john.doe@yourdomain.tld",
"...": "..."
}

For a text message, the relevant property is smsMo.

Tip: DataSets double as logs and can readily be used you are troubleshooting. This is for instance useful if the end-user forgot which data they provided, or if a configuration was changed at some point.

3.3. Payment Session Result

Whenever a transaction takes place, the relevant transactional data is stored in OnlineFundraising. The resulting records are summarised in the Payment Session Result, which means that the DataSet contains references to all records that were created (or updated) in context of the end-users actions.

This corresponds to the property paymentSessionResult. For instance, if an end-user fills out a form and commits to an agreement, the payment session result will look like:

"paymentSessionResult": {
"postProcessedTs": "2019-12-31 15:59:59 +0100",
"postProcessingErrorTs": "2019-12-31 15:59:59 +0100",
"postProcessingErrorDescription": "",
"contactGuidResult": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
"paymentMethodGuidResult": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
"agreementGuidResult": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
"subscriptionGuidResult": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
"paymentGuidResult": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx"
}

The above payment session result reveals that the following records were created in OnlineFundraising:

  • (DataSet)
  • Contact
  • Agreement
  • Subscription
  • Payment Method
  • Payment if end-user opted to make payment instantly (OneOff)
Tip: Refer to the payment session result of a DataSet in order to derive exactly which events transpired in OnlineFundraising as result of an end-user's actions.

It is important to note that the payment sessions result is the same for forms and text messages. Non-transactional DataSets do not contain a payment session result.

Moreover, it is possible to configure webhooks to trigger on any record which is created (or updated) in context of an end-users actions.

3.4. Custom data defined by OnlineFundraising user (Metadata)

The article API Overview states that the data model is non-customisable, which makes for a very rigid data model, ensuring a robust operational system. However, it is possible to configure custom fields and metadata on a Form or SMS Campaign. Metadata and custom fields are contained in the resulting DataSet, making it available for the integration layer.

Metadata and custom fields are listed in the DataSet along with the original configuration and data registered by end-user. An example of metadata is UTM parameters.

Tip: Define your own metadata and parse the dataset in the integration layer to apply custom logic to special use cases. This is especially useful if you are applying non-transactional DataSets.

5. Summary

The DataSet ties all records together with information about the completed payment session, configuration of the form, as well as metadata defined by the OnlineFundraising user. This is useful in order to extract information about e.g. the event (end-user submitted a form) or metadata such as UTM parameters.