Post processing with Forms
Post processing occurs when a submitted form invokes a separate, user-defined process after submission. Processes are used for any kind of update to user-defined data based on information provided by a user. For example, you have an annual verification process for your members. Use the post-processing feature to generate a new annual verification record for a member, so that their submission status for the prior year is reset to its initial state. Post processing displays a custom status message, designating success or failure after the process has been executed.
Post processing operates in one of the following ways:
- Process selector - Selects the page from where the Form script deploys. This process checks the existence of the targeted page and/or procedure.
- Process parameters - Identifies and passes two or three parameters when invoking a process that then updates the user defined data.
Post processing works differently depending on how a client is hosted:
- Cloud-hosted - A successful form submission invokes a script page in iMIS to execute a process using the REST API.
- On-premise - A successful form submission invokes either a script page or a SQL stored procedure.
Process parameters
In order for Post processing to execute properly, the following parameters must be included in the form in question:
- ID - The ID of the user who submitted the form, or the ID of the on Behalf of user. This field supports a maximum of 10 characters.
- Ordinal - The ordinal or sequence value of a multi-instance record updated by the user for a selected multi-instance source. If this option is selected, the multi-instance source must also be defined. This field supports integers only.
- FormName - The name of the form in question, as defined in the Form library.
Note: All parameter values are passed to the post processing script. However the value of Ordinal may be undefined, for example, when the form designer chooses to send only the ID and FormName to the post-processor. In this case, the Ordinal will not be displayed when referred to by the JavaScript method.
Creating Form Builder scripts
A JavaScript function designed to work with Form Builder has the following key attributes:
- The JavaScript ID must be:
- The script must consist of an asynchronous JavaScript function that accepts the following parameters: ID, Ordinal and FormName.
- The JavaScript function must return an object consisting of a boolean result and a string message:
result=true
for successresult=false
for failure- The script can optionally return a detailed message to the form for display in the success or failure message box. The returned object's "message" property may be undefined, null, an empty string, or a defined string constant. This message can be defined by the script and include dynamic information content.
<script id="formswebhook">
</script>
var returnedObject = { result: false, message: "Unknown error" };
Example scripts
Review the following examples to learn how to build your own scripts.
General template with comments
<script id="formswebhook">
// This script handles post-processing for forms
async function formswebhook(ID, Ordinal, FormName) {
// Initialize the returned object with default values
let returnedObject = { result: false, message: "Unknown error" };
// Post Processing Step to Add Cultivation activity
try {
let success = await processFormSubmission(ID, Ordinal, FormName);
if (success) {
returnedObject.result = true;
returnedObject.message = `Process success! ID: ${ID}, FormName: ${FormName}, Ordinal: ${Ordinal || 'N/A'}`;
}
} catch (error) {
console.error("Post-processing error:", error);
returnedObject.message = "Process failed: " + error.message;
}
return returnedObject;
}
// Define a sample function for processing form submissions
async function processFormSubmission(ID, Ordinal, FormName) {
// Example: Call an API endpoint to process the form
// Possible methods: "GET", "POST", "PUT", "DELETE"
let response = await iMISREST("POST", "CultivationActivity", "", JSON.stringify({ ID, Ordinal, FormName }));
return response ? true : false;
}
// Helper function for making REST API calls
function iMISREST(method, endpoint, record = "", data = null) {
return new Promise((resolve, reject) => {
let url = `${location.origin}/API/${endpoint}${record ? '/' + record : ''}`;
fetch(url, {
method: method,
body: data,
headers: {
"content-type": "application/json",
RequestVerificationToken: document.getElementById("__RequestVerificationToken").value,
},
})
.then((response) => {
if (response.ok) {
response.json().then((json) => resolve(json));
} else {
reject(new Error(`HTTP ${response.status}: ${response.statusText}`));
}
})
.catch((err) => reject(err));
});
}
</script>
Loop through query results to update party status
async function updateMultiInstanceFields(queryResults) {
for (const result of queryResults) {
await updatePanelField(result.ID, result.Ordinal);
}
}
async function updatePanelField(ID, Ordinal) {
let data = await iMISREST("GET", "MultiInstancePanel", ID);
data.Properties.$values.find((p) => p.Name === "FieldName").Value = "Updated Value";
await iMISREST("PUT", "MultiInstancePanel", ID, JSON.stringify(data));
}
Loop through query results to update party status
async function updatePartyStatuses(queryResults) {
for (const result of queryResults) {
await updatePartyStatus(result.ID);
}
}
async function updatePartyStatus(ID) {
let data = await iMISREST("GET", "Party", ID);
data.Status.PartyStatusId = "Unfinancial";
await iMISREST("PUT", "Party", ID, JSON.stringify(data));
}