ProcFormEdit

ProcFormEdit(
    int    ProcessID,
    string ProcessName,
    object Form,
    bool   WebhookEvaluate,
    bool   OverwriteWithNull
)

Update a Form incuding Fields. Functions similarly to ProcFormAdd

Notes:

Not used to edit actions, participants, notes or files. There are separate API calls for them.
Fields not provided are untouched, their value is kept as it was before the request
If OverwriteWithNull is true, fields sent with “Value” equal to null or “” will be cleared
Fields sent without “Value” key is unsupported and may behave inconsistently, alway send explicit “Values” or don’t send the field at all

Request

Request Data:
The form data to be populated is formatted the same way as ProcFormAdd.

(int) ProcessID or (string) ProcessName (optional) identify the process by
Name or ID, this is used along with Form.Number to find the form.
If both are provided the Name will be used.
(object) Form (required) – data that you want populated:
- (string) Number (optional) – unique number for this form.
  Used to identify the correct Form to Edit along with the Process or ProcessID.
- (string) FormID (optional) – unique ID number for this form.
  Used to identify the correct Form to Edit.
  If provided, then ProcessID, ProcessName and Form.Number will be ignored.
- (string) AlternateID (optional) – client-provided ID for the form to edit
  Used to identify the correct Form to Edit.
  If provided, then FormID, ProcessID, ProcessName and Form.Number will be ignored.
- (string) Owner (optional) the Name of the owner for this form.
  Will default to the API user if not provided.
  If the name provided is not a valid User, it will default to the API user.
  The new owner will be added as a participant.
- (string) Status (optional) the Status for the form. Has to be one of the valid status
  names. Will be the default status if not provided.
- (string) StatusID (optional) the Status for the form, identified by the internal ID.
  Has to be one of the valid status IDs. Will be the default status if not provided. (If provided at the
  same time as “Status”, StatusID will be used)
- (array) Fields (optional) list of field to be filled in.
  Any field not specified will be left untouched.
  Any field value sent as empty string will be cleared on the Form.
  Any field that does not exist in the process template will be ignored.
  Changes to field values will fire any applicable status triggers
(bool) WebhookEvaluate (optional, default: false) – whether RPM should issue webhook requests
(since RPM 11).
(bool) OverwriteWithNull (optional, default: false) – whether RPM should clear a field when the value set is null (since RPM 16). Does not apply to: table fields and yes no lists as these field’s values are complex.
Important: when using this option we recommend using null as the value for the fields to be cleared, check our guilde to learn all the quirks of this options.

Notes

The value for Percent fields has to be sent using a percent sign, for example: 50%, 0.5% and 123.456%
The value for Yes/no fields follows a strict rule: send “0”, “no”, “n” for “No”. Everything else is interpreted as “Yes”
Status level changes will fire any applicable global actions or approvals.
To delete rows from free rows table exclude the row from the data payload.When working with tables it’s recommended that API users first fetch the form’s complete data using ProcForm and then modify the data inside the tables to ensure that untouched rows do not get deleted by mistake.

Identifying which form to edit

This endpoint allows for multiple ways of identifying the form to edit, if the request provides multiple data items to ID the form the API will use them in the following order:

AlternateID (since RPM24) – provide the user-generated AlternateID inside the Form object
FormID – provide the Form ID inside the Form object
Process Name + Form Number – provide the Process key at the top level and FormNumber inside the Form object
Process ID + Form Number – provide the ProcessID key at the top level and FormNumber inside the Form object

Form ID

{
  "Form": {
    "AlternateID": <string>,
    "Owner": <string>,
    "Status": <string>,
    "Fields": [
      {
        "Field": <string>,
        "Value": <string>
      }
      ... <more field definitions>
    ]
  }
}

AlternateID

{
  "Form": {
    "AlternateID": <string>,
    "Owner": <string>,
    "Status": <string>,
    "Fields": [
      {
        "Field": <string>,
        "Value": <string>
      }
      ... <more field definitions>
    ]
  }
}

Process Name + Form Number

{
  "Process": <string>,
  "Form": {
    "Number": <string>,
    "Owner": <string>,
    "Status": <string>,
    "Fields": [
      {
        "Field": <string>,
        "Value": <string>
      }
      ... <more field definitions>
    ]
  }
}

Process ID + Form Number

{
  "ProcessID": <int>,
  "Form": {
    "Number": <string>,
    "Owner": <string>,
    "Status": <string>,
    "Fields": [
      {
        "Field": <string>,
        "Value": <string>
      }
      ... <more field definitions>
    ]
  }
}

Response

On success, the response will contain the complete Form, see the JSON Formatting for Forms.

Errors

“Process not found” – If the process Name or ID is not found
“Form not found” – If the form could not be identified through Process + Form.Number or FormID. Also, since RPM25 this same error will be returned if the form being edited is in the trash.
Setting the Owner to a Staff User that doesn’t have access to the process will fail silently. Check to confirm the changes.