Like Validations, Procedures are run server-side. However, while validations are triggered automatically when a submission is created or updated, Procedures are triggered manually with a POST Request. Procedures use the same server-side API as Validations do, both generally the same as the client-side API. Most of the same objects are available in all three formats. This page has information on the API for writing the procedure scripts themselves. For information on the procedure editor, see the feature documentation.
If you enable Development Mode, the output of console.log will be returned in an array with the request's response. You can view it from the Networking tab of any modern browser's developer console (F12).
DEVELOPMENT = true;
Calling Procedures
If a procedure is triggered from a client-side or server-side script, it will be called as the currently logged-in user.
Procedure.run("procedure_name", { ... parameters ... }).done(function(response) {
console.log(response);
});
Procedures can also be called with the REST API. See Getting Started with the REST API for information on calling procedures with an authorized user account.
POST https://{{organization}}.sonadier.io/api/rest/v1/forms/{{form}}/procedures/{{procedure_endpoint}}
An optional submission parameter can be passed with the request, containing a submission's permalink. If the permalink is valid, its Submission object will be set to the self variable. Procedures are not limited to a single submission, and can query or trigger integrations.
Procedure Errors
If there's an issue that prevents the procedure server from functioning, an error will be returned with the Development Mode log output. Procedure Server error messages are listed below:
- The procedure server timed out: Your custom script took too long, or was not resolved using the render method. Scripts are currently limited to 10 seconds.
- The procedure server could not be reached: The procedure server is down or inaccessible. If this message appears, contact support@sonadier.com.
params()
The params method returns an object containing the parameters passed with the procedure's request. Both GET (query) and POST (data) parameters are included.
POST https://{{organization}}.sonadier.io/api/rest/v1/forms/{{form}/procedures/{{procedure_endpoint}}?foo=bar
params().foo == "bar"
render(options = {})
The render method sets the response for the request made to trigger the procedure. By default it will render with HTTP status 200 "OK", and an empty response body. You are required to call it when your script is finished, or it will time out.
// Renders a response with the HTTP Status 200 "OK" and an empty body
render();
render({ status: "ok" });
// Renders a response with the HTTP Status 400 "Bad Request", and the body in the format given.
render({ status: "bad_request", json: { error: "Invalid Parameters" } });
render({ status: 400, xml: "<error>Invalid Parameters</error>" });
The response's body and format are given by passing the format as a key and the body as a value. The response types "html", "json", "xml", "text", "yaml", and "csv" are supported.
render({ status: "ok", html: "<html><head><title>Page Title</title></head><body>HTML Response</body></html>" });
render({ status: "ok", json: { message: "JSON Response" } });
render({ status: "ok", xml: "<message>XML Response</message>" });
render({ status: "ok", csv: "1,CSV Response,Another Column" });
Rendering Status Codes
The render method's options takes a "status" parameter which controls the HTTP status code returned with the procedure's response. It accepts either code numbers or snake_case names derived from the status name. The accepted values are derived from Ruby on Rails standard status code list. A full list of the accepted status codes is available below, and the name or number can be used interchangeably.
100 continue
101 switching_protocols
102 processing
200 ok
201 created
202 accepted
203 non_authoritative_information
204 no_content
205 reset_content
206 partial_content
207 multi_status
208 already_reported
226 im_used
300 multiple_choices
301 moved_permanently
302 found
303 see_other
304 not_modified
305 use_proxy
307 temporary_redirect
308 permanent_redirect
400 bad_request
401 unauthorized
402 payment_required
403 forbidden
404 not_found
405 method_not_allowed
406 not_acceptable
407 proxy_authentication_required
408 request_timeout
409 conflict
410 gone
411 length_required
412 precondition_failed
413 payload_too_large
414 uri_too_long
415 unsupported_media_type
416 range_not_satisfiable
417 expectation_failed
422 unprocessable_entity
423 locked
424 failed_dependency
426 upgrade_required
428 precondition_required
429 too_many_requests
431 request_header_fields_too_large
500 internal_server_error
501 not_implemented
502 bad_gateway
503 service_unavailable
504 gateway_timeout
505 http_version_not_supported
506 variant_also_negotiates
507 insufficient_storage
508 loop_detected
510 not_extended
511 network_authentication_required
self
Procedures can be passed an optional "submission" parameter with a submission's permalink.
If the permalink is valid and permitted, a Submission object will be provided for it.
The submission can be accessed with the self variable using the same syntax as client-side scripts.
POST https://{{organization}}.sonadier.io/api/rest/v1/forms/{{form}}/procedures/{{procedure_endpoint}}?submission=ABCDEFGHIJ
self.permalink(); // "ABCDEFGHIJ"
self.fields.field_name.value();
submission
The submission object is an alias for the self object.