New article
Recently updated
Navigating a RESTConnect Payload
Who is this article for?
Administrators and Users
Access to Module Builder as a Developer or Module Viewer and RESTConnect
This document explains the relationship between the module definition and the JSON payload of a RESTConnect request. The module definition contains the data structure and the business logic for a given module. Each module is unique and modified to address each customer's needs.
The module layout is separated into two sections:
- The Level Section (green)
- The Field Section (orange)
The Level Section
The Level section (green surrounding on the image above) will always contain a header level (H code, surrounded in blue). A simple module may only contain a header level.
The Level section may or may not contain one or multiple child level(s) (C# code surrounding in purple).
Header level fields are associated with the payload root and JSON objects.
{ <-- JSON Root
"headerField1Key": "headerField1Value", <-- JSON Key/Value element
"headerField2Key": "headerField2Value",
"headerField3Key": "headerField3Value",
...
}
Child level fields are associated with the payload root and as JSON arrays.
{ <-- JSON Root>
"ChildLevel1": [ <-- Child Level as an array of JSON objects
{ <-- JSON object
"childLevel1Field1Key": "childLevel1Field1Value", <-- JSON Key/Value element
"childLevel1Field2Key": "childLevel1Field2Value",
"childLevel1Field3Key": "childLevel1Field3Value",
...
},
{ <-- JSON object
"childLevel2Field1Key": "childLevel2Field1Value", <-- JSON Key/Value element
"childLevel2Field2Key": "childLevel2Field2Value",
"childLevel2Field3Key": "childLevel2Field3Value",
...
},
...
]
}
When selecting a level (green), the field section (orange) will display the list of the fields associated with the chosen level.
The Field Section
(The orange surrounding on the image above)
The field section defines the fields associated with the selected level of the module. The code will always start with the code matching the selected level.
Field Types
- Virtual fields are not relevant for REST. Those fields are for Platform internal usage (virtual HTML, character, numeric, picklist, reference, etc...).
- Character Field
- Character Small: a small character field cannot contain more than 250 characters
- Character Lager: a large character field cannot contain more than 4000 characters
- Character Large with overflow: a large character with an overflow field cannot contain more than 100,000 characters
{
"character1FieldKey": "Lorem ipsum dolor sit amet, fabellas menandri no vel, eu tation vocent comprehensam cum. Mei ea consul admodum, et solet eligendi eam. Vis et sonet interpretaris, oporteat eleifend disputando et his. Cum solet iuvaret facilisis ad. Iriure deseruisse mei ea, his affert putent in. Ne alia ceteros reprimique eum, vis et quas omnes libris, deserunt patrioque an pro."
}
- Picklist is an array of values such as active, inactive, yes, or no.
-
- The picklist value (Active, Inactive, Enabled, Disabled, etc.) When using the picklist value such as Active or Inactive, any change to the value requires an update on the JSON payload, or it will create an error.
{
"picklistFieldKey": "Active"
}-
- The picklist codes are not human-friendly but are less prone to changes, making them easier to manage. When using the picklist code (such as "PD-PER-P1-1"), any picklist value changes will continue to work, regardless of the new value. "PD-PER-P1-1" could be set from Active to Enable. The payload still points to "PD-PER-P1-1" and not the actual value.
- Deleting a picklist option will create an error whether the value or code is being used.
{
"picklistFieldKey": "PD-PER-P1-1" <-- Same as Active
}
- A checkbox is a non-true binary value. A checkbox can be null, empty, "N" for no or not being selected, "Y" for being selected. The lack of "Y" in the checkbox value indicates that the checkbox has not been selected.
{
"checkBoxFieldKey": "Y" <-- Only true indication of the checkbox being checked
}
or
{
"checkBoxFieldKey": "N"
}
or
{
"checkBoxFieldKey": ""
}
or
{
"checkBoxFieldKey": null
}
- A Integer is a numerical value
{
"integerKeyValue": 123456
}
- All internal Dates are using the "YYYY-MM-DD" format (ISO 8601). The fields in the UI can display the date in a different format (see the field property of a field date).
{
"dateKeyValue": "2021-12-31"
}
- The Time alldates are using the "HH:MM" format.
{
"timeKeyValue": "14:45"
}
- References: references relating to a secondary module.
- For example, a person can be assigned to a manager. The manager himself is a person.
- For example, a person can be assigned to an organization. The organization information is stored in a different module (organization module).
- A reference always requires a module code, even if the reference only refers to a single module.
- A reference can refer to an existing object using its identifier.
- A reference can also create a new entry, as long as the reference contains all the necessary fields to create the new entry. The lack of an identifier indicates the creation of a new entry.
- A reference can have many other fields:
- Characters
- Picklist
- Checkboxes
- Integer
- Date
- Time
- Reference which could also have a reference etc.
- An array of references will have the same basic structure. Some fields may not be necessary for all entries within the same array. A person record may not have the telephone number of each person.
{
"referenceField": {
"ModuleCode": "PD-PER", <-- Person Module
"Identifier": "PPER-2021-0001"
}
}
{
"referenceField": {
"ModuleCode": "PD-ORG", <-- Organization Module
"Identifier": "ORG-2021-0001"
}
}
{
"referenceField": {
"ModuleCode": "DWAY-PER", <-- Person Module
"Identifier": "PD-2021-0001",
"character1FieldKey": "characterFieldValue",
"picklistFieldKey": "Active",
"checkBoxFieldKey": "Y",
"dateKeyValue": "2021-12-31",
"timeKeyValue": "14:45",
"referenceField": { <-- Reference Within A Reference
"ModuleCode": "PD-ORG", <-- Organization Module
"Identifier": "ORG-2021-0001"
}
}
}
Differences between Header and Child level
As stated above, the child-level fields represent an array of JSON objects at the root, while the header-level fields represent JSON objects at the root.
- Header Level Reference:
{ <-- Header Level (JSON Object root)
"referenceField": { <-- Reference Field
"ModuleCode": "PD-ORG", <-- Organization Module
"Identifier": "ORG-2021-0001"
}
}
- Child Level Reference:
{ <-- JSON object root
"ChildLevel1": [ <-- Child Level (JSON Array at the root)
{ <-- JSON Object
"referenceField": { <-- Reference Field
"ModuleCode": "PD-ORG", <-- Organization Module
"Identifier": "ORG-2021-0001"
}
},
{ <-- JSON Object
"referenceField": { <-- Reference Field
"ModuleCode": "PD-ORG", <-- Organization Module
"Identifier": "ORG-2021-0002"
}
}
]
}
- Header Level Data:
{ <-- Header Level (JSON Object root)
"character1FieldKey": "characterFieldValue",
"character2FieldKey": "characterField2Value",
"picklistFieldKey": "Active",
"checkBoxFieldKey": "Y",
"dateKeyValue": "2021-12-31",
"timeKeyValue": "14:45"
}
- Child Level Data:
{ <-- JSON object root
"ChildLevel1": [ <-- Child Level (JSON Array at the root)
{ <-- JSON Object
"childCharacter1FieldKey": "characterField1Value",
"childCharacter2FieldKey": "characterField2Value",
"childPicklistFieldKey": "Active",
"childCheckBoxFieldKey": "Y",
"childDateKeyValue": "2021-12-31",
"childTimeKeyValue": "14:45"
},
{ <-- JSON Object
"childCharacter1FieldKey": "characterField1Value",
"childCharacter2FieldKey": "characterField2Value",
"childPicklistFieldKey": "Inactive",
"childCheckBoxFieldKey": "N",
"childDateKeyValue": "2020-12-31",
"childTimeKeyValue": "13:45"
}
]
}
All other types of fields will have the same logic:
- Header Level Character Field
{ <-- JSON object root
"character1FieldKey": "Lorem ipsum dolor sit amet, fabellas menandri no vel, eu tation vocent comprehensam cum. Mei ea consul admodum, et solet eligendi eam. Vis et sonet interpretaris, oporteat eleifend disputando et his. Cum solet iuvaret facilisis ad. Iriure deseruisse mei ea, his affert putent in. Ne alia ceteros reprimique eum, vis et quas omnes libris, deserunt patrioque an pro."
}
- Child Level Character Field
{ <-- JSON object root
"ChildLevel1": [ <-- Child Level (JSON Array at the root)
{ <-- JSON Object
"character1FieldKey": "Lorem ipsum dolor sit amet, fabellas menandri no vel, eu tation vocent comprehensam cum. Mei ea consul admodum, et solet eligendi eam. Vis et sonet interpretaris, oporteat eleifend disputando et his. Cum solet iuvaret facilisis ad. Iriure deseruisse mei ea, his affert putent in. Ne alia ceteros reprimique eum, vis et quas omnes libris, deserunt patrioque an pro."
},
{ <-- JSON Object
"character1FieldKey": "Lorem ipsum dolor sit amet, fabellas menandri no vel, eu tation vocent comprehensam cum. Mei ea consul admodum, et solet eligendi eam. Vis et sonet interpretaris, oporteat eleifend disputando et his. Cum solet iuvaret facilisis ad. Iriure deseruisse mei ea, his affert putent in. Ne alia ceteros reprimique eum, vis et quas omnes libris, deserunt patrioque an pro."
}
]
}
The permutation of header and child-level are combined into a single JSON object.
{ <-- JSON object root
"character1FieldKey": "characterField1Value",
"character2FieldKey": "characterField2Value",
"picklistFieldKey": "Active",
"checkBoxFieldKey": "Y",
"dateKeyValue": "2021-12-31",
"timeKeyValue": "14:45",
"referenceField": { <-- Reference Object at the root (header level)
"ModuleCode": "DWAY-PER", <-- Person Module
"Identifier": "PD-2021-0001",
"characterFieldKey": "characterFieldValue",
"picklistFieldKey": "Active",
"checkBoxFieldKey": "Y",
"dateKeyValue": "2021-12-31",
"timeKeyValue": "14:45",
"referenceField": { <-- Reference Within A Reference
"ModuleCode": "PD-ORG", <-- Organization Module
"Identifier": "ORG-2021-0001"
}
},
"ChildLevel1": [ <-- Child Level (JSON Array at the root)
{ <-- JSON Object
"referenceField": { <-- Reference Field
"ModuleCode": "PD-ORG", <-- Organization Module
"Identifier": "ORG-2021-0001"
}
},
{ <-- JSON Object
"referenceField": { <-- Reference Field
"ModuleCode": "PD-ORG", <-- Organization Module
"Identifier": "ORG-2021-0002"
}
}
],
"ChildLevel2": [ <-- Child Level (JSON Array at the root)
{ <-- JSON Object
"referenceField": { <-- Reference Field
"ModuleCode": "PD-PER", <-- Person Module
"Identifier": "PER-2021-0001"
},
"childCharacter1FieldKey": "characterField1Value",
"childCharacter2FieldKey": "characterField2Value",
"childPicklistFieldKey": "Active",
"childCheckBoxFieldKey": "Y",
"childDateKeyValue": "2021-12-31",
"childTimeKeyValue": "14:45"
},
{ <-- JSON Object
"referenceField": { <-- Reference Field
"ModuleCode": "PD-PER", <-- Person Module
"Identifier": "PER-2021-0002"
},
"childCharacter1FieldKey": "characterField1Value",
"childCharacter2FieldKey": "characterField2Value",
"childPicklistFieldKey": "Inactive",
"childCheckBoxFieldKey": "N",
"childDateKeyValue": "2020-12-31",
"childTimeKeyValue": "13:45"
}
],
"ChildLevel3": [ <-- Child Level (JSON Array at the root)
{ <-- JSON Object
"childCharacter1FieldKey": "characterField1Value",
"childCharacter2FieldKey": "characterField2Value",
"childPicklistFieldKey": "Inactive",
"childCheckBoxFieldKey": "N",
"childDateKeyValue": "2020-12-31",
"childTimeKeyValue": "13:45"
}
]
}
Creating references within the main object.
When creating a record, RESTConnect will only return the unique ID (Identifier) of the main object created.
- Depending on the JSON structure, the user can create as many references as needed within the main object.
- The user will not get any feedback on the success or the failure of the reference data (reference of the reference),
- RESTConnect will only return the main identifier in the response header (the root). Therefore, the user will have to query the created object to verify if all references were successfully created.
- Failure to create a reference will not automatically have a cascading effect failing the main object.
Business Logic
The business logic of the module can interfere with the data sent through RESTConnect.
Any required fields could prevent the creation of objects if the JSON payload does not match the module requirements. The module could also contain a flag and set of rules to ignore the business logic in certain circumstances.