The following workflow outlines a process for pushing data from an external source into the Alida Member Data Service.
This workflow will function acceptably for small volumes of data of up to 1,000 members; however, it may not scale well when dealing with large volumes of data. To improve performance, see Best practices: Optimization.
Below is a diagram outlining the simplest process for pushing data into the Alida Member Data Service. Click the corresponding steps below the diagram for more information about each stage of the process.
A. Select the target Member Variable
Based on the integration in question, there will be a set of target Member Variables where data is stored in the Member Data Service. These are typically defined when describing the requirements for the integration.
The simplest way to describe these target variables is with the
name attribute. However, we recommend describing the
target using the actual
memberVariableId and to maintain it in the input
mapping. This is because the
name attribute could be changed independently,
resulting in a new Member Variable being created the next time an integration
flow is executed.
At this step in the process, you will want to select one of the target Member Variables from your list.
B. GET Member Variable
Call the
/membervariables resource to check if the target
membervariable exists and to get the identifier if it
does.
The key information to extract from this response is the
id attribute which will be described as
memberVariableId in other resources.
You may also want to validate the
type and
datatype attributes to ensure that they are as
expected.
Example: Member Variable exists
Request URL:
GET /membervariables?name=sfdc_lead_source
Response Content:
{
"meta": {
"offset": 0,
"limit": 20,
"count": 1
},
"items": [
{
"id": "0bfb0f1b-160d-43b1-b711-a62c0059ca52",
"name": "sfdc_lead_source",
"description": "The value of the Lead Source field from the associated contact record in Sales Force",
"source": "SFDC",
"type": "open",
"dataType": "text",
"constraints": {
"disabled": false,
"hidden": false,
"readOnly": false,
"returnLatest": false,
"uniquePerMember": false
},
"categories": [
"profileVariable"
],
"memberVariableValues": {
"href": "https://api.{region}.alida.com/v1/applications/{communityApiKeyName}/membervariablevalues?memberVariableId=0bfb0f1b-60d-43b1-b311-a62c0059ca52"
},
"sequenceId": 211,
"sensitive": false,
"createDate": "2014-11-05T05:15:17.8954252Z",
"lastUpdateDate": "2014-11-13T15:58:03.3751361Z",
"createdBy": "5daf3fc8-d28f-4da0-94c1-c4f9ca8b445c",
"lastUpdatedBy": "5daf3fc8-d28f-4da0-94c1-c4f9ca8b445c",
"links": [],
"href": "https://api.{region}.alida.com/v1/applications/{communityApiKeyName}/membervariables/0bfb0f1b-50d-43b1-b711-a62c0059ca52"
}
],
...
}Example: Member Variable does not exist
Request URL:
GET /membervariables?name=sfdc_lead_source
Response Content:
{
"meta": {
"offset": 0,
"limit": 20,
"count": 0
},
"items": [],
...
}C. Does the Member Variable exist?
The call in step B: GET MemberVariable will determine if the Member Variable exists.
| If the Member Variable | Then |
|---|---|
| Exists | The
memberVariableId should be persisted for
subsequent usage.
|
| Does not exist | Create one with a POST request in step D: POST Member Variable. |
D. POST Member Variable
If the POST is successful, then the response code will be an HTTP 201. The Location response header will contain the URL to the created instance. Alternatively, you can repeat the earlier call to look it up by name.
Example: Create a new Member Variable
Request URL:
POST /membervariables
Request Body:
{
"name": "sfdc_lead_source",
"description": "The value of the Lead Source field from the associated contact record in Salesforce",
"source": "SFDC",
"type": "open",
"dataType": "text"
}E. Check for more Member Variables
Determine if there are any more target Member Variables and verify that they exist.
| If more Member Variables | Then |
|---|---|
| Exist | Return to step A: Select the target Member Variable. |
| Do not exist |
Proceed to step F: Select the member. |
F. Select the member
If you are ready to iterate through the list of members for which data will be pushed, pick a member from the list and proceed to step G: GET member by identifier.
G. GET member by identifier
When processing a member, you need to check to see if that member already exists.
Given the time-series nature of Member Values, the
email property will still match a member even if that
member has subsequently changed their email address. Because the email Member
Variable applies the
uniquePerMember constraint, the system will ensure
that a given Member Variable Value (such as the email address) is only ever
assigned to one member in your community.
Example: Member exists
Request URL:
GET /membervalues?memberVariableName=email&memberVariableValue=mytestuser1@example.org&fields=memberId&limit=1
Response Content:
{
"meta": {
"offset": 0,
"limit": 20,
"count": 1
},
"items": [
{
"memberId": "6ba974fd-4f41-4c24-ae8d-0ca9432a02c5"
}
],
...
}Example: Member does not exist
Request URL:
GET /membervalues?memberVariableName=email&memberVariableValue=mytestuser1@example.org&fields=memberId&limit=1
Response Content:
{
"meta": {
"offset": 0,
"limit": 20,
"count": 0
},
"items": [],
...
}H. Does the member exist?
| If the member | Then |
|---|---|
| Exists | Proceed to step K: Select the target Member Variable |
| Does not exist | Complete step I: Create a Member. |
I. Create member
A member is automatically created when you post a Member Value that includes an email address that has never been assigned to a member before. This will include assignment of a number of other Member Values for System Variables that can subsequently be retrieved. You can look up the new member ID by checking if a member exists (step G: GET member by identifier). Alternatively, the Location response header will include the URL to the Member Value instance created which would contain the member ID.
Furthermore, if you include the request header
X-WebApi-Return-Resource=true, then the HTTP 201
response on successful creation following the POST will also return the created
Member Value in the body of the response (preventing a subsequent GET).
Example
Request URL:
POST /membervalues
Request Body:
{
"memberVariableName": "uploadid",
"memberDataSetType": "Live",
"memberEmail": "mytestuser1@example.org",
"memberVariableValue": "SFDCImport_2016-06-20T11:11:21"
}J. Select target Member Variable
Once you know the member ID, select a Member Variable from the list you defined for which there is data for this member.
K. GET the latest Member Values
This step is not required from a functional perspective, since the time-series nature of Member Values will ensure that sending POST requests of the same data over and over again will produce the same result (i.e. idempotent) in terms of the resulting current or latest Member Value(s) for a given member. However, doing so affects the performance and data management overhead that is best avoided. For this reason, we recommend looking up the current or latest value first to avoid unnecessary POST requests
Example: Member Values exist
Request URL:
GET /membervalues/asof/9999?memberId=14dfcbeb-b17a-464b-8372-a62c0065a966&memberVariableId=bc55aa95-2a7f-4d75-86b4-a3780118a164&
fields=memberId,memberVariableValue,effectiveDate
Response Content:
{
"meta": {
"offset": 0,
"limit": 20,
"count": 1
},
"items": [
{
"memberId": "14dfcbeb-b17a-464b-8372-a62c0065a966",
"memberVariableValue": "Advertisement",
"effectiveDate": "2016-06-21T06:10:08.2715344Z"
}
],
...
}L. Does current target differ from current source?
| If | Then |
|---|---|
| The current target is different from the current source | Proceed to step M: Post new Member Values. |
| The current target is the same as the current source | Proceed to step N: More Member Variables? |
M. POST new Member Value(s)
If the current Member Value(s) for the member do not match the information coming from the source for the integration, then it will be necessary to update the Member Data Service with this information. This is done by sending a POST request to Member Values with the new information.
Example
Request URL:
POST /membervalues
Request Body:
{
"memberVariableId": "bc55aa95-2a7f-4d75-86b4-a3780118a164",
"memberDataSetType": "Live",
"memberId": "14dfcbeb-b17a-464b-8372-a62c0065a966",
"memberVariableValue": "Partner"
}N. More Member Variables?
If there are more Member Variables that have not been processed for this member, then loop back to step K: Select the target Member Variable , and repeat the process for the next variable. If not, move on to the next member.
O. More members?
If there are more members to process, then move on to the next one. If not, the process is complete.