Factorial Documentation

Appearance

Plugins ​

  Table of Contents

New to plugins? Follow Writing Your First Plugin to configure the CLI, create a template, and upload it to Factorial.

Factorial is a programmable system, letting organizations tailor Factorial to their use case. Plugins can do things like sync data to and from other systems, enforce business rules transactionally, and automate common tasks. We built plugins with AI in mind, and provide skills, docs, and AI integration to make writing plugins easier.

A plugin has a collection of scripts and optional secrets. Scripts must be written in a Python subset called Starlark. Plugins can be individually enabled/disabled. They are versioned, and go through a configurable approval process before they can be enabled. Uploading an existing draft with the same name and version replaces that draft. If the existing version is not in draft, the upload fails; either return the version to draft or increment the version in the plugin manifest. Existing versions remain available for inspection. Plugins are tracked in audit history so that there is complete traceability on when plugins were enabled. Scripts within the same plugin all share the same namespace, so code can be reused within plugins.

There are four script types: hooks, receivers, jobs, and actions. Every script exposes a main(args) entrypoint, and each script file must represent only one entrypoint type.

Hooks ​

Hook scripts subscribe to a specific event in plugin.yaml. Factorial calls the script's main(args) function with a tuple of standardized HookEvent values. Each event provides a subject_id and an event name:

python
def main(args):
    for event in args:
        print(event.subject_id)
        print(event.event)

Manifest subscriptions use a composite name such as comment_create. The corresponding hook input uses the standardized event name comments_create:

python
HookEvent(
    subject_id="subject-id",
    event="comments_create",
)

A hook invocation may contain multiple events. Hook scripts can send HTTP requests, raise validation errors or warnings, send notifications, schedule work, and modify custom fields.

Receivers ​

Receiver scripts register an endpoint at yoursubdomain.factorialhq.com/receivers/{plugin-name}/{endpoint}, and main(args) is invoked when that endpoint receives a POST request. args contains the request body. This can be useful for using Factorial as a receiver of webhooks. For example to sync parts from a PLM in realtime, the PLM may have a webhook where it sends the part information to a configurable endpoint every time a new part is created. The receiver script would then be invoked with the payload from the POST request and create the part in Factorial. The request is automatically authenticated and API keys for the rest of the Factorial API are valid for these receiver endpoints.

Jobs ​

Jobs run a script periodically on a certain schedule. Factorial invokes main(args) with args set to None. Jobs can import data from other systems, export Factorial data, close stale tasks, or send reminders.

Set a job's schedule in plugin.yaml to one of the following values:

  • every_15_min
  • every_2_hours
  • every_4_hours
  • every_8_hours
  • every_1_day
  • every_7_days

Actions ​

Actions are invoked through slash commands to the command bar anywhere in the app. An action script has a configured input schema, which is a set of typed fields. When a user invokes the slash command, a modal appears with the fields they must enter, and Factorial invokes main(args) with the submitted values. The script is run with the permissions of the user who invoked it. This can help automate routine tasks, for example, if a certain rework process requires scheduling three separate work orders, a slash command could be written that collects the inventory that needs work, and an assignee, and schedules all three work orders in one command.

Testing Scripts ​

All script types support running them manually with a mocked payload, side effects will be listed in the execution so you can see what they would have done if enabled. External requests are not run by default.

Execution Logs ​

Script execution logs are available in app for debugging purposes. Detailed log execution data is only maintained for the last 30 days by default.

AI Integration ​

Our CLI can create plugins itself, empowering AI agents to read/write/edit plugins. A plugin-writing skill is available in our open-source skills repository which helps make agents more successful when writing scripts for Factorial. All script-writing pages also have a "Copy Narkdown" button that delivers relevant skill guidance, documentation, existing code, and types into one prompt that can be easily transported and pasted into an AI conversation.

Example Use Case: Pedigree ​

COMING SOON

Reference ​

Coming Soon