ProcFormEdit

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

Update fields of a Form. Functions similarly to ProcFormAdd

Note: not used to edit actions, participants, notes or files. There are separate API calls for them.

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
    If both are provided the Name will be used.
  • (object) Form (required) – data that you want populated:
    • (string) Number (optional, required if ProcessID or ProcessName are provided) – unique number for this form.
      Used to identify the correct Form to Edit.
    • (string) FormID (optional, required if ProcessID, ProcessName are not provided) – UUID AlternateID 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, required if ProcessID, ProcessName and AlternateID are not provided) – 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) 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 set to blank 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) MarkUnreadAndNotify (optional, default: true) – have RPM generate notifications as necessary (since RPM 11).
  • (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.

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.

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

Identifying the Form:
You can identify the Form to Edit in three different ways:

  • Form ID.
  • Process Name + Form Number provide the process name and identify the form number inside the Form object.
  • Process ID + Form Number provide the process id and identify the form number inside the Form object.

Form ID

{
  "Form": {
    "FormID": <int>,
    "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
  • Setting the Owner to a Staff User that doesn’t have access to the process will fail silently. Check to confirm the changes.
%d bloggers like this: