Skip to content

Launch process

Endpoint

POST /organizations/{org_id}/runs

This endpoint launches a new process instance (run) based on a specified template (checklist/blueprint).

Request

Replace {org_id} with your Organization ID.

Headers

  • Authorization: Bearer {your_access_token}
  • Accept: application/json
  • X-Tallyfy-Client: APIClient
  • Content-Type: application/json

Body (JSON)

The request body requires a JSON object containing the details for the new process run.

Required Fields:

  • checklist_id (string): The ID of the template (blueprint) to launch from.
  • name (string): The name for this specific process instance.

Optional Fields (Refer to #definitions/createRunInput in Swagger):

  • summary (string): Description for this process instance.
  • owner_id (integer): User ID of the process owner.
  • is_public (boolean): Make the process accessible via a public link.
  • parent_id (string): Link this process as a sub-process of another run.
  • prerun (array): An array of objects to pre-fill kick-off form fields. The structure depends on the field type (see examples below).
  • tasks (object): Define overrides for task properties like assignees and deadlines for specific steps within this run. Keys are Step IDs from the template.
  • tags (array of strings): Tag IDs to apply to this process instance.
  • users (array of integers): User IDs assigned to the process.
  • groups (array of strings): Group IDs assigned to the process.
  • roles (array of objects): Role assignments (structure defined in Swagger).
  • folders (array of strings): Folder IDs where this process should appear.

Populating Kick-off Fields (prerun)

The prerun array takes objects where the key is the Kick-off Field ID (Prerun ID) and the value depends on the field type:

  • Text/Textarea: { "field_id_abc": "Your text value" }
  • Date: { "field_id_def": "2024-05-21T10:30:00.000Z" } (ISO 8601 format)
  • Radio Button: { "field_id_ghi": "Selected Radio Option Value" }
  • Dropdown: { "field_id_jkl": { "id": 2, "text": "Selected Option Text", "value": null } } (Provide the option object as defined in the template)
  • Checklist (Multi-select): { "field_id_mno": [{ "id": 1, "text": "Option 1 Text", "value": null, "selected": true }, { "id": 3, "text": "Option 3 Text", "value": null, "selected": true }] } (Array of selected option objects)
  • File/Image: { "field_id_pqr": [{ "id": "asset_id_123", "filename": "report.pdf", "version": 1, "url": "...", "uploaded_from": "ko_field", "subject": { "id": "template_id", "type": "Checklist" } }] } (Requires pre-uploading the file and using the returned asset object)

Overriding Task Properties (tasks)

The tasks object allows specifying assignees and deadlines per step for this specific run. The key is the Step ID from the template.

"tasks": {
    "step_id_from_template_1": {
        "position": 1, // Usually not needed unless reordering on launch
        "deadline": "2024-06-01T17:00:00Z",
        "users": [1001, 1002], // Assign specific users
        "groups": [],
        "guests": ["client@example.com"]
    },
    "step_id_from_template_2": {
        "users": [], // Explicitly unassign users/groups/guests
        "groups": [],
        "guests": [],
        "assign_run_starter": false // Ensure launcher isn't assigned either
    }
    // Add other step overrides as needed
}

Code Samples

const accessToken = 'YOUR_PERSONAL_ACCESS_TOKEN';
const orgId = 'YOUR_ORGANIZATION_ID';
const apiUrl = `https://api.tallyfy.com/organizations/${orgId}/runs`;


const launchPayload = {
  checklist_id: "TEMPLATE_ID_TO_LAUNCH",
  name: "Process Launched via JS Fetch",
  summary: "This instance was started programmatically.",
  // Example prerun data (replace with actual Prerun Field IDs)
  prerun: [
    { "kickoff_field_id_1": "Customer XYZ" },
    { "kickoff_field_id_2": "2024-06-15T12:00:00Z" }
  ],
  // Example task override (replace with actual Step IDs)
  tasks: {
    "step_id_abc": {
      "deadline": "2024-06-20T17:00:00Z",
      "users": [12345] // Assign to user 12345
    }
  }
};


const headers = new Headers();
headers.append('Authorization', `Bearer ${accessToken}`);
headers.append('Accept', 'application/json');
headers.append('X-Tallyfy-Client', 'APIClient');
headers.append('Content-Type', 'application/json');


fetch(apiUrl, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify(launchPayload)
})
.then(response => {
    if (!response.ok) {
        return response.json().then(errData => {
            throw new Error(`HTTP error! status: ${response.status}, message: ${JSON.stringify(errData)}`);
        }).catch(() => {
             throw new Error(`HTTP error! status: ${response.status}`);
        });
    }
    // Check for 200 OK or 201 Created
    console.log(`Process launch requested. Status: ${response.status}`);
    return response.json();
})
.then(data => {
    console.log('Successfully launched process:');
    console.log(JSON.stringify(data, null, 2));
})
.catch(error => {
    console.error('Error launching process:', error);
});

Response

A successful launch request returns a 200 OK or 201 Created status code and a JSON object containing the details of the newly created process run, including its unique id.

{
  "data": {
    "id": "newly_launched_run_id_xyz789",
    "increment_id": 5012,
    "checklist_id": "TEMPLATE_ID_TO_LAUNCH",
    "checklist_title": "Customer Onboarding",
    "name": "Process Launched via Python",
    "summary": "Instance started with requests library.",
    "status": "active", // Initial status
    "progress": {
        "complete": 0,
        "total": 15,
        "percent": 0
     },
    "started_by": 1001,
    "created_at": "2024-05-20T14:00:00.000Z",
    "last_updated": "2024-05-20T14:00:00.000Z",
    // ... other run properties ...
  }
}

Make note of the returned run id to manage this process instance later (e.g., get details, update, list its tasks).

Get in touch
About Tallyfy