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
If you wish to use the pre-built Wordpress Plugin to add this functionality to your website, please proceed to the Wordpress Plugin section.
Developer Documentation for JSON Submission to the Gnosis API
The following section is for developers who wish to implement the new record submission directly in code. If you want to use the WordPress Plugin, please proceed to that section.
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”: ""
}
WordPress Plugin
Installing the Plugin
The Worrdpress Plugin is attached to the bottom of this article. It is installed and activated in the normal manner for a plugin on a WordPress site. Save the attached gnosis-signup.zip package to add your plugin to WordPress.
The main settings for the plugin provide a place to add the Gnosis API EndPoint for your system.
http://YourOrganizationID.GnosisHosting.net/Connect4/Handlers/RemoteDataInput.ashx
NOTE: The "YourOrganizationID" acronym or name identifies your unique Gnosis system. You can find this name at the beginning of your Gnosis login URL, or you may request it from support.
Adding the Gnosis Signup Form Shortcode to Your Website
The Gnosis Signup plugin makes adding a signup form to your website easy so users can sign up for your Gnosis system. Here's how you can add the form to a page or post:
Step 1: Edit a Page or Post
- Log in to your WordPress admin area.
- Go to "Pages" or "Posts" and select the page or post where you want to add the signup form.
- Click "Edit" to open the page or post editor.
Step 2: Add the Shortcode
You have two options for adding the shortcode, depending on your WordPress version and editor:
-
Directly as Text (Classic Editor or Gutenberg):
- In the content editor, place your cursor where you want the signup form to appear.
- Type the following shortcode for the basic plugin:
[gnosis_signup]
-
Using the Shortcode Block (Gutenberg):
- In the content editor, click the "+" icon to add a new block.
- Search for "Shortcode" and click on the Shortcode block to add it to your content.
- In the Shortcode block, type or paste the Gnosis Signup shortcode:
[gnosis_signup]
Step 3: Add Custom Fields (Optional)
- If you want to add custom fields to the form, you can add attributes to the shortcode like this example showing the addition of a single additional attribute to the basic form:
[gnosis_signup custom_field_1="Newsletter|ckb|2078|Sign up for our newsletter"]
To add multiple custom fields (Gnosis Attributes) (up to 5 are permitted), you will use the following shortcode format (Note: new-lines must include the "\" continuation character on the previous line:
[gnosis_signup \
custom_field_1="Newsletter|ckb|2078|Sign up for our newsletter?" \
custom_field_2="Volunteer|ckb|2079|Do you wish to colunteer?" \
custom_field_3="Availability|date|2080|From what date will you be available?" \
]
Shortcode Custom Field Component Parts
The format for each attribute (custom field) is:
Label|Type|ID|Comment
- Label: The label for the field that will be displayed to the user.
- Type: The input field type (txt, nbr, date, ckb).
- ID: The ID of the attribute in your Gnosis system.
- Comment: (optional) An optional comment to display below the field.
Example:
[gnosis_signup custom_field_1="Phone Number|nbr|12345|Enter your phone number"]
This will create a form with a number input field labeled "Phone Number" with the ID 12345 and the comment "Enter your phone number."
Using The Plugin
Once the plugin shortcode is correctly added to a page or post, and the page is shown in preview or view modes, you will see the Gnosis Form on the page where it was placed.
Styling the Plugin
You may apply styling to the plugin by editing its default CSS, which is provided as part of the plugin installation. Ensure that you keep a copy of any modified CSS file so that you can restore your modifications after any plugin update is installed later.
Here is an example of the plugin with standard styling. If you require a different configuration of the main WordPress plugin fields (such as date of birth or phone numbers), please make a request to Gnosis support.
WORDPRESS PLUGIN DOWNLOAD:
Comments
0 comments
Please sign in to leave a comment.