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:

Updating Tasks within a Process

To update individual tasks (assignees, deadlines, form fields) within a running process, use the Update Task endpoint (PUT /organizations/{org}/runs/{run_id}/tasks/{task_id}) instead.

Replacing Arrays (Tags/Folders)

Providing the owners object replaces all existing assignees with the ones specified in the users, groups, and guests arrays within the object. To remove all assignees, provide empty arrays for all three.

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

Javascript

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);
});

Python

import requests
import json
import os

access_token = os.environ.get('TALLYFY_ACCESS_TOKEN', 'YOUR_PERSONAL_ACCESS_TOKEN')
org_id = os.environ.get('TALLYFY_ORG_ID', 'YOUR_ORGANIZATION_ID')
run_id = 'PROCESS_RUN_ID_TO_UPDATE'
api_url = f'https://go.tallyfy.com/api/organizations/{org_id}/runs/{run_id}'

headers = {
    'Authorization': f'Bearer {access_token}',
    'Accept': 'application/json',
    'X-Tallyfy-Client': 'APIClient',
    'Content-Type': 'application/json'
}

# Note: Sending 'tags' or 'folders' replaces the existing list.
# Get the current process run first if you need to add/remove incrementally.
update_payload = {
    'name': 'Python Updated Process Name',
    'summary': 'Updated via Python requests.',
    # Example: Replace tags
    'tags': ['tag_id_new', 'tag_id_existing']
}

response = None
try:
    response = requests.put(api_url, headers=headers, json=update_payload)
    response.raise_for_status() # Raises HTTPError for bad responses (4xx or 5xx)

    updated_process = response.json()
    print(f'Successfully updated process {run_id}:')
    print(json.dumps(updated_process, indent=4))

except requests.exceptions.HTTPError as http_err:
    print(f"HTTP error occurred updating process {run_id}: {http_err}")
    if response is not None:
        print(f"Response Body: {response.text}")
except requests.exceptions.RequestException as req_err:
    print(f"Request failed updating process {run_id}: {req_err}")
except json.JSONDecodeError:
    print(f"Failed to decode JSON response for process update {run_id}")
    if response is not None:
        print(f"Response Text: {response.text}")
except Exception as err:
     print(f"An unexpected error occurred: {err}")

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.io.IOException;
// Requires a JSON library like Jackson or Gson
// import com.fasterxml.jackson.databind.ObjectMapper;
// import java.util.Map;
// import java.util.HashMap;
// import java.util.List;

public class UpdateProcess {
    public static void main(String[] args) {
        String accessToken = System.getenv().getOrDefault("TALLYFY_ACCESS_TOKEN", "YOUR_PERSONAL_ACCESS_TOKEN");
        String orgId = System.getenv().getOrDefault("TALLYFY_ORG_ID", "YOUR_ORGANIZATION_ID");
        String runId = "PROCESS_RUN_ID_TO_UPDATE";
        String apiUrl = String.format("https://go.tallyfy.com/api/organizations/%s/runs/%s", orgId, runId);

        // --- Payload Construction ---
        // Using Jackson/Gson recommended:
        /*
        ObjectMapper mapper = new ObjectMapper();
        Map<String, Object> updateData = new HashMap<>();
        updateData.put("name", "Java Updated Run Name");
        updateData.put("tags", List.of("tag1", "tag2")); // Replaces existing tags
        String jsonPayload;
        try {
            jsonPayload = mapper.writeValueAsString(updateData);
        } catch (Exception e) {
            System.err.println("Failed to serialize JSON: " + e.getMessage());
            return;
        }
        */
        // Simple manual JSON string for example:
        String jsonPayload = "{\"summary\": \"Java updated summary notes.\"}";
        // --- End Payload ---

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(apiUrl))
                .header("Authorization", "Bearer " + accessToken)
                .header("Accept", "application/json")
                .header("X-Tallyfy-Client", "APIClient")
                .header("Content-Type", "application/json")
                .PUT(HttpRequest.BodyPublishers.ofString(jsonPayload))
                .build();

        try {
            HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

            if (response.statusCode() == 200) {
                System.out.println("Successfully updated process " + runId + ":");
                System.out.println(response.body());
                // TODO: Consider parsing JSON response
            } else {
                System.err.println("Failed to update process " + runId + ". Status: " + response.statusCode());
                System.err.println("Response Body: " + response.body());
            }
        } catch (IOException | InterruptedException e) {
            System.err.println("Request failed: " + e.getMessage());
            Thread.currentThread().interrupt();
        } catch (Exception e) {
             System.err.println("An unexpected error occurred: " + e.getMessage());
             e.printStackTrace();
        }
    }
}

Go

package main

import (
  "bytes"
  "encoding/json"
  "fmt"
  "io/ioutil"
  "net/http"
  "os"
    "time"
)

func main() {
  accessToken := os.Getenv("TALLYFY_ACCESS_TOKEN")
    if accessToken == "" { accessToken = "YOUR_PERSONAL_ACCESS_TOKEN" }
  orgId := os.Getenv("TALLYFY_ORG_ID")
    if orgId == "" { orgId = "YOUR_ORGANIZATION_ID" }
    runId := "PROCESS_RUN_ID_TO_UPDATE"
    apiUrl := fmt.Sprintf("https://go.tallyfy.com/api/organizations/%s/runs/%s", orgId, runId)

    // Note: Sending 'tags' or 'folders' replaces the existing list.
  updateData := map[string]interface{}{
    "name": "Go Updated Process",
        "owner_id": 1005, // Example: change owner
  }

  jsonData, err := json.Marshal(updateData)
  if err != nil {
        fmt.Printf("Error marshalling JSON: %v\n", err)
        return
    }

  client := &http.Client{Timeout: 15 * time.Second}
  req, err := http.NewRequest(http.MethodPut, apiUrl, bytes.NewBuffer(jsonData))
    if err != nil {
        fmt.Printf("Error creating update process request for run %s: %v\n", runId, err)
        return
    }

  req.Header.Set("Authorization", "Bearer "+accessToken)
  req.Header.Set("Accept", "application/json")
  req.Header.Set("X-Tallyfy-Client", "APIClient")
  req.Header.Set("Content-Type", "application/json")

  resp, err := client.Do(req)
    if err != nil {
        fmt.Printf("Error executing update process request for run %s: %v\n", runId, err)
        return
    }
  defer resp.Body.Close()

  body, err := ioutil.ReadAll(resp.Body)
    if err != nil {
        fmt.Printf("Error reading update process response body for run %s: %v\n", runId, err)
        return
    }

  if resp.StatusCode != http.StatusOK {
    fmt.Printf("Failed to update process %s. Status: %d\nBody: %s\n", runId, resp.StatusCode, string(body))
    return
  }

  fmt.Printf("Successfully updated process %s:\n", runId)
    // Pretty print JSON response
    var prettyJSON bytes.Buffer
    if err := json.Indent(&prettyJSON, body, "", "  "); err == nil {
        fmt.Println(prettyJSON.String())
    } else {
      fmt.Println(string(body))
    }
  // TODO: Unmarshal JSON if needed
}

C++

#include <iostream>
#include <string>
#include <cpprest/http_client.h>
#include <cpprest/json.h>

using namespace web;
using namespace web::http;
using namespace web::http::client;
using namespace web::json;

pplx::task<void> UpdateTallyfyProcess(const utility::string_t& runId, const value& updatePayload)
{
    utility::string_t accessToken = U("YOUR_PERSONAL_ACCESS_TOKEN");
    utility::string_t orgId = U("YOUR_ORGANIZATION_ID");
    utility::string_t apiUrl = U("https://go.tallyfy.com/api/organizations/") + orgId + U("/runs/") + runId;

    http_client client(apiUrl);
    http_request request(methods::PUT);

    request.headers().add(U("Authorization"), U("Bearer ") + accessToken);
    request.headers().add(U("Accept"), U("application/json"));
    request.headers().add(U("X-Tallyfy-Client"), U("APIClient"));
    request.headers().set_content_type(U("application/json"));
    request.set_body(updatePayload);

    return client.request(request).then([runId](http_response response)
    {
        utility::string_t runIdW = runId;
        return response.extract_json().then([response, runIdW](pplx::task<value> task)
        {
            try {
                value const & body = task.get();
                if (response.status_code() == status_codes::OK) {
                    std::wcout << L"Successfully updated process " << runIdW << L":\n" << body.serialize() << std::endl;
                } else {
                    std::wcerr << L"Failed to update process " << runIdW << L". Status: " << response.status_code() << L"\nResponse: " << body.serialize() << std::endl;
                }
            } catch (const http_exception& e) {
                 std::wcerr << L"HTTP exception during update process: " << e.what() << std::endl;
            } catch (const std::exception& e) {
                std::wcerr << L"Exception during update process response handling: " << e.what() << std::endl;
            }
        });
    });
}

int main() {
    try {
        value payload = value::object();
        payload[U("name")] = value::string(U("C++ Updated Process Name"));
        payload[U("summary")] = value::string(U("Updated via C++"));
        // Example: Replace tags (get current first if adding/removing)
        value tagsArray = value::array();
        tagsArray[0] = value::string(U("tag_id_cpp"));
        payload[U("tags")] = tagsArray;

        UpdateTallyfyProcess(U("PROCESS_RUN_ID_TO_UPDATE"), payload).wait(); // Replace with actual Run ID
    } catch (const std::exception &e) {
        std::cerr << "Error in main: " << e.what() << std::endl;
    }
    return 0;
}
// Requires C++ REST SDK (Casablanca)

C#

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;
using System.Text.Json.Serialization; // For JsonIgnoreCondition
using System.Threading.Tasks;

public class TallyfyProcessUpdater
{
    private static readonly HttpClient client = new HttpClient();

    public class ProcessUpdatePayload
    {
        // Include only fields to update. Use JsonIgnore to send only non-null fields.
        [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
        public string Name { get; set; }

        [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
        public string Summary { get; set; }

        [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
        public int? OwnerId { get; set; }

        // Remember: Sending Tags/Folders REPLACES the existing list.
        [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
        public List<string> Tags { get; set; }

        [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
        public List<string> Folders { get; set; }

        [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
        public bool? PreventGuestComment { get; set; }

        // Add other updatable fields like Prerun if needed
        // public List<Dictionary<string, object>> Prerun { get; set; }
    }

    public static async Task UpdateProcessAsync(string runId, ProcessUpdatePayload payload)
    {
        var accessToken = Environment.GetEnvironmentVariable("TALLYFY_ACCESS_TOKEN") ?? "YOUR_PERSONAL_ACCESS_TOKEN";
        var orgId = Environment.GetEnvironmentVariable("TALLYFY_ORG_ID") ?? "YOUR_ORGANIZATION_ID";
        var apiUrl = $"https://go.tallyfy.com/api/organizations/{orgId}/runs/{runId}";

        try
        {
            using var request = new HttpRequestMessage(HttpMethod.Put, apiUrl);
            request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);
            request.Headers.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
            request.Headers.Add("X-Tallyfy-Client", "APIClient");

            // Serialize payload, ignoring nulls
            var options = new JsonSerializerOptions { DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull };
            string jsonPayload = JsonSerializer.Serialize(payload, options);
            request.Content = new StringContent(jsonPayload, Encoding.UTF8, "application/json");

            HttpResponseMessage response = await client.SendAsync(request);
            string responseBody = await response.Content.ReadAsStringAsync();

            if (response.IsSuccessStatusCode) // Expect 200 OK
            {
                Console.WriteLine($"Successfully updated process {runId}:");
                try {
                    using var doc = JsonDocument.Parse(responseBody);
                    Console.WriteLine(JsonSerializer.Serialize(doc.RootElement, new JsonSerializerOptions { WriteIndented = true }));
                } catch (JsonException) {
                    Console.WriteLine(responseBody);
                }
            }
            else
            {
                Console.WriteLine($"Failed to update process {runId}. Status: {response.StatusCode}");
                Console.WriteLine($"Response: {responseBody}");
            }
        }
        catch (HttpRequestException e)
        {
            Console.WriteLine($"Request Exception updating process {runId}: {e.Message}");
        }
        catch (JsonException jsonEx)
        {
             Console.WriteLine($"JSON Serialization Error: {jsonEx.Message}");
        }
        catch (Exception ex)
        {
            Console.WriteLine($"An unexpected error occurred: {ex.Message}");
        }
    }

    // Example Usage:
    // static async Task Main(string[] args)
    // {
    //     var processUpdate = new ProcessUpdatePayload {
    //         Summary = "Updated C# summary.",
    //         Tags = new List<string> { "tag_cs_1", "tag_cs_2" } // Replaces existing
    //     };
    //     await UpdateProcessAsync("PROCESS_RUN_ID_TO_UPDATE", processUpdate);
    // }
}

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.

---

Related articles

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.

Templates > Update template

Modify the details of an existing process template (blueprint).

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.

Edit Processes > Edit tasks and process properties

Running processes in workflow management systems can be edited through their settings panel where users can modify properties like process name owner deadline tags folder location and notes while also accessing options to archive export or delete the process.