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)
1.1. Sources of DataSets
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)
1.2. DataSets give useful insight
DataSets provide insight to a lot of information. The main areas of insight are emphasised in the table below.
| Main Area of DataSet | Description |
| Configuration of source |
Details of configuration of the source Form, Onboarding form or SMS Campaign. |
| Data registered by end-user | Data as registered by end-user when they either submitted the form, Onboarding form or sent the text message. |
| Payment Session Result | Details of all information related to transaction. The payment session result is omitted if no transaction took place. |
| Metadata |
Custom data defined by OnlineFundraising user. Metadata is key to adding custom data which the OnlineFundraising datamodel does not allow. Not all metadata is defined by the user. Some metadata is added to the DataSet automatically. An example of this type of metadata is UTM parameters. |
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 flagged 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",
"isTransactional": false,
"isThirdParty": false,
"sourceType": "SMS",
"sourceGuid": "86338d0c-5c08-4312-85c6-xxxxxxxxxxxx",
"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"
}
}
}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.
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)
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.
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.