Skip to content

Update process

Endpoint

PUT /organizations/{org_id}/runs/{run_id}

This endpoint allows you to update certain properties of an existing process instance (run).

Request

Replace {org_id} with your Organization ID and {run_id} with the ID of the process run to update.

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 process properties you wish to modify. You only need to include the fields you want to change.

Refer to the #definitions/createRunInput schema (often similar for updates) in Swagger. Common updatable fields include:

  • name (string): New name for the process instance.
  • summary (string): New summary/description.
  • owner_id (integer): Change the process owner.
  • tags (array of strings): Replaces the current list of tag IDs associated with the process.
  • folders (array of strings): Replaces the current list of folder IDs.
  • prerun (array): Update kick-off form field values (structure depends on field type, see Launch Process).
  • prevent_guest_comment (boolean): Enable/disable guest comments.

Updating form fields using taskdata

To update form field values, include a taskdata object in the request body. The keys within taskdata are the Form Field IDs (Capture IDs), and the values depend on the field type:

Example Body:

{
  "name": "Onboarding - Globex Corp (Updated)",
  "summary": "Updated summary notes for this run.",
  "tags": ["tag_id_urgent", "tag_id_onboarding"],
  "prevent_guest_comment": true
}

Code Samples

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


const updateData = {
  name: "JS Updated Process Name",
  summary: "Adding more details here.",
  prevent_guest_comment: true,
  // Replace tags (get current tags first if adding/removing incrementally)
  // tags: ["tag_id_1", "tag_id_2"]
  // owner_id: 1005
};


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: 'PUT',
    headers: headers,
    body: JSON.stringify(updateData)
})
.then(response => {
    return response.json().then(data => { // Attempt to parse JSON regardless of status
        if (!response.ok) {
            console.error(`Failed to update process ${runId}:`, data);
            throw new Error(`HTTP error! status: ${response.status}`);
        }
        return data; // Pass successful data along
    });
})
.then(data => {
    console.log(`Successfully updated process ${runId}:`);
    console.log(JSON.stringify(data, null, 2));
})
.catch(error => {
    console.error(`Error updating process ${runId}:`, error.message);
});

Response

A successful request returns a 200 OK status code and a JSON object containing the full details of the process run after the update.

{
  "data": {
    "id": "PROCESS_RUN_ID_TO_UPDATE",
    "name": "Onboarding - Globex Corp (Updated)", // Updated name
    "summary": "Updated summary notes for this run.", // Updated summary
    "tags": ["tag_id_urgent", "tag_id_onboarding"], // Updated tags
    // ... other process properties reflecting the current state ...
    "last_updated": "2024-05-21T22:00:00Z", // Timestamp reflects the update
    "notes": "Updated process notes."
  }
}

If the run ID is not found, you lack permission, or the request body is invalid, an appropriate error status code (404, 403, 400, 422) will be returned.

Tasks > Update task

The API endpoint enables updating task properties like title summary deadline assignees and form field values through a PUT request while handling both process-run tasks and standalone one-off tasks with appropriate response validation.

Tags > Update tag

The PUT endpoint enables updating an existing tag’s properties like title and color within an organization by sending a JSON request with the new values and receiving the updated tag details in response.
Get in touch
About Tallyfy