Process Input Parameters
When working with Factorial Code processes, you can configure input parameters to gather information from users before starting an on-demand or scheduled (cron job) execution. Input parameters also play a role in defining webhook bodies.
The process edition includes a JSON editor which is used to define the process input parameter form.
In your process source code, you can access the provided input parameters using the following helper:
const { context: { parameters },} = fcode;parameters = fcode.context.parametersWith parameters defined, you can request any information needed to run your process. Forms can range from simple:
…to more complex configurations:
File Inputs and Factorial Code Storage
Section titled “File Inputs and Factorial Code Storage”When a form field is configured as a file input, submitted files are automatically uploaded to Factorial Code Storage before your process starts.
That means your process receives a storage reference for each uploaded file, so you can directly download or process files with fcode.storage helpers.
A parameter is a file when it declares x-fcode-file, with the extensions it takes in
accept. A form also needs "ui:widget": "file" to render a file picker, so a file field in a form
carries both:
{ "title": "Upload Form", "type": "object", "properties": { "inputFile": { "title": "Upload a file", "type": "string", "x-fcode-file": { "accept": [".csv", ".xlsx"] }, "ui": { "ui:widget": "file", "ui:options": { "accept": ".csv,.xlsx" } } } }, "required": ["inputFile"]}x-fcode-fileis data: it tells the platform, and anything else that reads the schema — such as the Factorial One assistant — that the parameter takes a file. It belongs to the property itself, next totype.x-fcode-file.acceptlists the file extensions the parameter takes, each with its leading dot, compared without regard to case. Name them: they are also what tells the Factorial One assistant what the parameter takes. A parameter that really takes any file says so with an empty list,"accept": []; a missing list means the same. Only extensions count: a MIME type such asimage/*matches no file name. When Factorial uploads a file for an action, a file whose name matches none of them is refused.ui:widgetandui:optionsare presentation: they only tell the form how to draw the field.ui:options.acceptfilters the browser’s file picker; it restricts nothing on the platform.
After the file is uploaded, the execution input parameters will contain the storage path of the uploaded file, and you can access it using the fcode.storage.download() helper. See the Factorial Code Storage documentation for more details.
Parameters Definition
Section titled “Parameters Definition”We use the JSON Schema form specification, and the library we use to render the form is react-jsonschema-form.
This allows you to use advanced configurations, such as dependencies, which enable you to change fields based on entered data.
Additionally, Factorial Code offers extra attributes to enhance your experience:
Sensitive Properties
Section titled “Sensitive Properties”Properties marked as sensitive are treated as passwords. They are stored encrypted in the database and won’t be shown in the UI.
"ui:widget": "password" on its own only hides the characters on screen; it does not make the property sensitive. When you push a process, the CLI warns about every parameter that uses that widget, or whose name or title looks like a secret (a token, password, API key, client secret, private key or credentials), without "isSensitive": true.
Here you have an example of a simple form with a sensitive property:
{ "title": "Input parameters", "type": "object", "properties": { "apiKey": { "title": "The API Key", "type": "string", "isSensitive": true } }, "required": ["apiKey"]}The value of a sensitive property never comes back from the platform. When a form is served — to an
embedded form, the Factorial UI or an agent reading its fields — Factorial Code removes the default,
examples and const of every property marked isSensitive (and of anything nested under it), even
when a preRenderProcess put the
stored value there. Wherever the property sits in the schema (properties, items, oneOf,
dependencies, #/variables…), the form shows it empty.
Sensitive values in settings forms
Section titled “Sensitive values in settings forms”A settings form that re-opens with the saved configuration therefore shows every secret empty. Treat an empty secret on submit as “keep the value already saved”: the process that receives the form is responsible for that, the platform does not merge the old value back in.
async function main() { const { siteUrl, apiToken } = fcode.context.parameters; const saved = JSON.parse((await fcode.datastore.get("settings")) || "{}");
await fcode.datastore.set( "settings", JSON.stringify({ siteUrl, // Empty means the user left the secret untouched. apiToken: apiToken || saved.apiToken, }) );}Do not mark a secret as required in a settings form: the form would refuse to submit until the user
types the secret again, every time they change any other setting. Check instead, in the process, that a
secret is present either in the submission or in what is already saved, and fail with a clear message
when neither has it (typically on the first save).
Transient properties
Section titled “Transient properties”Transient properties are only available for the execution and won’t be stored in the database. An execution which receives transient parameters cannot be rerun,
as these type of parameters won’t be available. They are shown with [transient] in the UI.
Here you have an example of a simple form with a transient property:
{ "title": "Input parameters", "type": "object", "properties": { "fileContent": { "title": "The content of the file", "type": "string", "isTransient": true } }, "required": ["fileContent"]}Validation
Section titled “Validation”Validation is supported by this form specification and is checked upon form submission.
Content Customization
Section titled “Content Customization”To provide greater flexibility to the forms and the content they display (titles, descriptions, help messages), we have improved and extended the schema to support markdown rendering using markdown.
Field markdown covers inline formatting (links, emphasis, images, lists). Block content — a markdown.before/after block around a field, or the message a process execution returns — additionally supports GitHub Flavored Markdown, including tables and code blocks.
With this functionality, you can format text in a simple and easy way to make it more readable. Here you have one sample:
"oneStringField": { "title": " *[fcode](https://code.factorial.dev)* form title", "description": "[fcode](https://code.factorial.dev) form description", "type": "string" },Full sample
Section titled “Full sample”Here’s a complete example of a Form schema:
{ "title": "Full [fcode forms](https://code.factorialhr.com) form sample", "description": "This is a sample form specification showing all available attribute types for [fcode forms](https://code.factorialhr.com)", "type": "object", "properties": { "oneStringField": { "title": " *[fcode](https://code.factorialhr.com)* form title", "description": "Visit [fcode](https://code.factorialhr.com) form description", "type": "string" }, "onePasswordField": { "title": "One password field", "type": "string", "description": "Password shoul be: \n 1. At least 12 characters long \n 2. Include a combination of uppercase and lowercase letters \n 3. At least one special character such as @, #, $, %", "isSensitive": true, "ui": { "ui:placeholder": "Use a secure password" } }, "oneHiddenField": { "title": "One hidden field", "type": "string", "ui": { "ui:widget": "hidden" } }, "oneIntegerField": { "title": "One integer field with range", "description": "Values must be between 0 and 500", "type": "integer", "minimum": 0, "maximum": 500 }, "oneBooleanField": { "title": "One boolean field with [link](https://code.factorialhr.com)", "type": "boolean" }, "oneEmailField": { "title": "One email field", "type": "string", "format": "email" }, "oneTextAreaField": { "title": "One textarea field", "type": "string", "description": "> Block quote description", "ui": { "ui:widget": "textarea" } }, "oneColorField": { "title": "One color field", "type": "string", "ui": { "ui:widget": "color" } }, "oneFileField": { "title": "One file field", "type": "string", "x-fcode-file": { "accept": [ ".pdf" ] }, "ui": { "ui:widget": "file" } }, "oneObjectField": { "title": "One object field", "description": "This sample has two nested fields.", "required": [ "anotherString", "anotherInteger" ], "type": "object", "properties": { "anotherString": { "type": "string" }, "anotherInteger": { "type": "number", "minimum": -180, "maximum": 180 } } }, "oneStringArrayField": { "title": "One string array field", "type": "array", "items": { "type": "string" } }, "oneObjectsArrayField": { "title": "One object array field", "type": "array", "items": { "type": "object", "properties": { "oneProperty": { "description": "One property", "type": "string" }, "anotherProperty": { "description": "Another property", "type": "string" } } } }, "oneRadioField": { "title": "One string radio field", "type": "string", "ui": { "ui:widget": "radio" }, "oneOf": [ { "const": "option-1", "title": "Option 1 Label" }, { "const": "option-2", "title": "Option 2 Label" }, { "const": "option-3", "title": "Option 3 Label" } ] }, "oneCheckboxField": { "title": "One string checkboxes field", "type": "array", "ui": { "ui:widget": "checkboxes" }, "items": { "type": "string", "enum": [ "option 1", "option 2", "option 3" ] }, "uniqueItems": true }, "oneSelectField": { "title": "One string select field", "type": "string", "ui": { "ui:placeholder": "Pick one option" }, "enum": [ "option 1", "option 2", "option 3" ] }, "oneJsonParameter": { "title": "A JSON field", "description": "Block quote description", "type": "object", "ui": { "ui:field": "json" } }, "anotherBooleanField": { "title": "A input that shows other inputs", "type": "boolean" } }, "dependencies": { "anotherBooleanField": { "oneOf": [ { "properties": { "anotherBooleanField": { "enum": [ true ] }, "aDependencyValueProperty": { "title": "This is shown when anotherBooleanField is true", "type": "string" } } }, { "properties": { "anotherBooleanField": { "enum": [ false ] }, "aDependencyValueProperty": { "title": "This is shown when anotherBooleanField is false", "type": "string" } } } ] } }, "required": [ "oneStringField" ], "ui": { "ui:submitButtonOptions": { "submitText": "Click me!" } }, "embedFormOptions": { "loadingOverlayContent": "Creating new user...", "theme": "dark", "themeStylesheet": "", "loadingOverlayDisabled": false, "locale": "es" }}