Overview
New person information may be submitted to your Gnosis database by submitting JSON encoded person data to the following URL on your portal site:
http://YourOrganizationID.GnosisHosting.net/Connect4/Handlers/RemoteDataInput.ashx
Adding a Basic Person Record
An example of the JSON encoded information required to successfully add a person to the database along with a minimal set of fields - such as signing up for a newsletter is shown below:
{
"RequestType": "NewPerson",
"EEmailAddress": "stephensaddress@company.com",
"PFirstName": "Stephen",
"PLastName": "Hall",
"Attribute (comment:2078=newsletter request):2078": true
}
The attribute field shown above in this example is for adding a boolean user-defined attribute representing newsletter signup requests. The Attribute ID number to use if any (2078 in this example) will be supplied by the user organization’s database administrator.
Adding a Full Person Record
An example of the JSON encoded information to successfully add a person to the database along with all of the person’s available fields is shown below:
{
"RequestType": "NewPerson",
"ExistingRecordToken": "",
"EEmailAddress": "",
"PTitle": "",
"PFirstName": "Stephen",
"PMidName": "",
"PLastName": "Hall",
"PSuffix": "",
"PPrefName": "Steve",
"PMemberPassword": "",
"PReferredBy": 0,
"PDOB_fixed": "1999-11-01",
"PGender": "M",
"PType": 509,
"PStatus": 511,
"TPhoneNumberBus": "408-404-1591 x101",
"TPhoneNumberHome": "",
"TPhoneNumberMobile": "",
"TPhoneNumberOther": "",
"AAddress1": "PO Box 320656",
"AAddress2": "",
"ACity": "Los Gatos",
"AState": "CA",
"AZip": "95032",
"ACountry": "USA",
"Attribute (optional comment):2078": true,
"Attribute (optional comment):1882": "Text to insert in attribute"
"Attribute (optional comment):1855": “ListOptionAliasName”
}
- RequestType is a required field and should be added to the JSON request as shown above. For new records, this field will have a value of "NewPerson". To update existing data, this value should be "UpdatePerson" and an ExistingRecordToken must also be provided.
- ExistingRecordToken is used when submitting data to update an existing record. When submitting new data, this field is optional. See below the section on "Testing For an Existing Record" for more information.
- EEmailAddress is a mandatory field.
- PFirstName is a mandatory field.
- PLastName is a mandatory field.
- PGender (if used) must be “M”, “F”, or an empty string.
- PType (if used), must contain an integer ID of a valid record type for a person.
- PStatus (if used), must contain an integer ID of a valid membership status for a person.
- To add attributes for the new person record, format the attribute field name as follows (Note: See the section below on Utilizing an Attribute Definition List for more information on attributes to include):
- Keyword “Attribute”
- followed by an optional description of the attribute
- a colon delimiter
- The Attribute ID number in your Gnosis database.
- Data to be entered for the attribute should be provided as follows:
- For boolean types - either “true” or “false”
- For numeric or text types - the numeric or text content
- For a “select from” list - The alias name (value) of the option to be selected
- For a date, we recommend using international format - "2012-12-31"
- Other field types may be included with string values.
Return Acknowledgement
The “Remote Data Input” page will return the following JSON acknowledgment:
{
"ResponseID" : "1234",
"ResponseText" : "Saved.",
"DataInputSucceeded" : true,
“HTTPStatusCode” : 201
}
If the “ResponseID” is a positive number, it contains the ID number of the new person record entered. If the “ResponseID” is negative, the submission failed and the reason is contained in the “ResponseText” field. “DataInputSucceeded” is a boolean field that indicates success or failure.
Implementing On a PHP Driven Page
If you are running WordPress or any other environment using PHP, the following is an example of implementing the JSON Post described above.
Firstly, collect the fields on your web page using something like the following:
<form id="emailForm">
<input type="text" placeholder="First name" name="firstName" id="firstName" />
<input type="text" placeholder="Last name" name="lastName" id="lastName" /><br />
<input type="text" placeholder="Enter email address for updates" name="emailAddress"
id="emailAddress" />
<input value="true" type="checkbox" name="updates" id="newsletter" checked="checked">
<input value="true" type="checkbox" name="updates" id="othernews" checked="checked">
<input type="submit" value="Register" />
</form>
Then, on postback processing, execute the something like following javascript:
function email_signup($firstName,
$lastName, $emailAddress, $newsletter, $othernews) {
// Build the json string, cURL to gnosis, then return the result.
$newEmailAddress = array( 'RequestType' = > 'NewPerson',
'EEmailAddress' = > $emailAddress,
'PFirstName' = > $firstName,
'PLastName' = > $lastName );
if ($newsletter) {
$newEmailAddress['Attribute:1234'] = true;
}
if ($othernews) {
$newEmailAddress['Attribute:5678'] = true;
}
$handle = curl_init("http://YourOrganizationID.GnosisHosting.net/Connect4/Handlers/RemoteDataInput.ashx");
curl_setopt($handle, CURLOPT_RETURNTRANSFER, true);
curl_setopt($handle, CURLOPT_HTTPAUTH, CURLAUTH_ANY);
curl_setopt($handle, CURLOPT_POST, true);
curl_setopt($handle, CURLOPT_POSTFIELDS, json_encode($newEmailAddress));
$response = curl_exec($handle);
curl_close($handle);
if ($response) {
//$responseData = new SimpleXmlElement($response, LIBXML_NOCDATA);
return array('result' = > $response,
'sent-data' = > $newEmailAddress);
}
else {
return "ERROR";
}
}
Utilizing An Attribute Definition List
When a large or potentially dynamic list of attributes needs to be used, the list of attributes to be added to the form can be obtained by requesting the attribute list JSON from:
https://YourOrganizationID.GnosisHosting.net/gnosis-api/v1/attributes/list
You may request either as a get with a query string param ( ?group=[GroupName] ) or as a JSON post ( {group: "[GroupName]"} ).
| Name | Type | Desc |
| group | string | what attribute group to display (not to be confused with category) |
| includeMasterCats | boolean | includes the top-level categorization |
JSON Post Example
{"group":"{GroupNameHere}"}
The {GroupNameHere} list name must be pre-configured by request to Gnosis Support before it can be used. The call will return a list of JSON attributes to be included in the order that they should be displayed on the form.
The example below illustrates each of the 9 attribute types that must be allowed for :
Sample JSON (excluding master category [see below])
[
{
"Name": "The Name of the first category",
"Attributes": [
{
"REID": 1024,
"Name": "This is the prompt text",
"AttType": "l",
"Required": false,
"AttOptions": [
{
"DisplayText": "This is the first list option",
"Value": "ListOption1Value"
},
{
"DisplayText": "This is the second list option",
"Value": "ListOption2Value"
}
]
},
{
"REID": 1025,
"Name": "This is the prompt text",
"AttType": "lcsv",
"Required": false,
"AttOptions": [
{
"DisplayText": "This is the first list option",
"Value": "ListOption1Value"
},
{
"DisplayText": "This is the second list option",
"Value": "ListOption2Value"
}
]
},
{
"REID": 1026,
"Name": "This is the prompt text",
"AttType": "b",
"Required": false
}
]
},
{
"Name": "The Name of the second category",
"Attributes": [
{
"REID": 1027,
"Name": "This is the prompt text",
"AttType": "y",
"Required": false
},
{
"REID": 1028,
"Name": "This is the prompt text",
"AttType": "s",
"Required": false
},
{
"REID": 1029,
"Name": "This is the prompt text",
"AttType": "m",
"Required": false
},
{
"REID": 1030,
"Name": "This is the prompt text",
"AttType": "i",
"Required": false
},
{
"REID": 1031,
"Name": "This is the prompt text",
"AttType": "c",
"Required": false
},
{
"REID": 1032,
"Name": "This is the prompt text",
"AttType": "d",
"Required": false
}
]
}
]
Each of these JSON elements and attributes returned is described below:
REID |
The ID of the category |
Name |
The display name of the attribute |
Categories |
An array of attribute category items for the master category |
REID |
The ID of the category |
Name |
The display name of the attribute |
Attributes |
An array of attributes for the category |
REID |
The ID of the attribute | ||||||||||||||||||
Name |
The display name of the attribute | ||||||||||||||||||
AttType |
The type of data the attribute holds
|
||||||||||||||||||
Required |
Boolean - Is the attribute required | ||||||||||||||||||
|
|
An array of options if type l or lcsv
|
Configuring Issue/Enquiry Tracking Setup & Sending a Communication Item
New person entries received via the remote data input can also trigger a new Issue/Inquiry record to be created to enable easy followup for the new record, and optionally trigger a communications item to be sent.
The details of new Issue/Enquiry records to be created are configured by the system preference & settings preference: "Web and API \ RDI New Person Actions". This preference is stored as a JSON array and if edited, the structure must be maintained.
The JSON Array contains one or more records that define a condition specifying which data input sources trigger the corresponding action and an "IssueTracking" action that defines the content of the record to be created. The example below shows that an Issue Tracking record will be created whenever a new record is entered with Attribute ID 4034 containing the text "Kiosk":
{
"Communications":{
"TokenResponseCommsID":1281,
"SendTokenBySMS": true,
"SMSTextOverride":"Here is your login token {{token}}"
},
"Actions":[
{
"Condition":{
"AttributeID":4034,
"Contains":"Kiosk"
},
"IssueTracking":{
"Category":2826,
"SubCategory":2827,
"Subject":"{Attrib_4034} Registration",
"Status":1792,
"EventNote":"Kiosk Reg. via {Attrib_4034}"
},
"Communication":{
"NewRecordCommsID":1282,
"UpdatedRecordCommsID":1283
}
}
]
}
Communication |
Common Communication settings across all configurations/actions | |
TokenResponseCommsID |
The communications item ID of the communication item that contains the Token for the recipient to provide to authenticate them. | |
SendTokenBySMS |
If true will allow sending tokens by SMS (Text Messaging) if the person has SMS available | |
SMSTextOverride |
If specified will override the default SMS text, use {{token}} as a placeholder for the token. | |
Actions |
An array of action configurations, see the "Action Description" below for more information |
Condition |
Determines on which condition this action is run (omit for default) | |
AttributeID |
The id of the attribute to check | |
Contains |
If the submitted attribute value exists and contains (anywhere in the value) the specified value (for list items this is the Alias Name)
Note: Omit this value or set to empty string, and it will match any value. |
|
RunOn |
This condition should run on either
|
|
IssueTracking |
Add an issue tracking (inquiry) item | |
|
|
|
The REID of the category for the new item |
|
|
The REID of the sub-category for the new item (a child of the category ref data item) | |
|
|
The REID of the status for the new item | |
|
|
The text to place in the subject, you can insert the value of any attribute submitted here if desired by adding {Attrib_4034} where 4034 is the id of the submitted attribute. Eg: "{Attrib_4034} Registration" |
|
|
|
The text to place in the tracking event, you can insert the value of any attribute submitted here if desired by adding {Attrib_4034} where 4034 is the id of the submitted attribute. Eg: "Online Kiosk Registration via {Attrib_4034}" |
|
Communication |
|
Send a communications item to the person being registered |
NewRecordCommsid |
The communications item ID of the communication item to be sent if a new record is successfully submitted. |
|
UpdatedRecordCommsID |
The communications item ID of the communication item to be sent if an existing record is successfully updated. |
Testing For an Existing Record
If you wish to test for whether the person already has a record in the database based on first name and phone number or email address, Gnosis provides an option via the same API endpoint used for submitting the data that will allow you to check for an existing record:
{
"RequestType": "CheckPerson",
"PFirstName": "Stephen",
"EEmailAddress": "myemail@servername.com",
"TPhoneNumberMobile": "408-404-1591 x101",
}
After submitting the "CheckPerson" request, the “Remote Data Input” API will return the following JSON response:
{
"RecordExists" : true,
"MatchedEmailAddress" : true,
"MatchedPhone" : true,
“TokenEmailTo”: "g...i@h...l.com",
“TokenSMSTo”: "******524",
“ErrorMessage”: ""
"TokenExpiresUTC": "2020-01-01T00:00:00Z"
}
If a record is found in the system with a matching first name (matches with both first name and preferred name) and either an existing mobile phone or email address, then:
- The "RecordExists" boolean will return true
- MatchedEmailAddress will show true to indicate an authentication token has been sent to the person's email on file indicated in the TokenEmailTo masked value.
- MatchedPhone will show true to indicate an authentication token has been texted (SMS) to the person's mobile number on file and indicated in the TokenSMSTo masked value.
- TokenEmailTo contains the masked value of the email address an authentication token has been sent to.
- TokenSMSTo contains the masked value of the phone number an authentication token has been sent to.
- TokenExpiresUTC is the UTC date-time the token will expire at
- ErrorMessage will contain the text of errors such as
- multiple records found
- email of token failed
- SMS of token failed
If a record already exists, and you wish to overwrite the existing data with the newly submitted data, you must include the "ExistingRecordToken" provided by the person submitting the data and change the "RequestType" to "UpdatePerson"
If an existing record is not found, the API will return the following JSON response:
{
"RecordExists" : false,
“ErrorMessage”: ""
}
.
Comments
0 comments
Please sign in to leave a comment.