POST Workflow Instances Instance ID Signals

The POST /WorkflowClosed A workflow is a series of steps necessary to complete a process. In the context of Keyfactor Command, it refers to the workflow builder, which allows you automate event-driven tasks when a certificate is requested or revoked./Instances/{instanceId}/Signals method is used to input signals to the workflow instance with the specified GUID. This endpointClosed An endpoint is a URL that enables the API to gain access to resources on a server. returns 204 with no content upon success.

Note:  If a workflow instance is initiated for a workflow definition that has more than one step requiring input (signals), a user can only provide that input (e.g. approve or deny a require approval request) at the step in the workflow instance where the workflow instance was suspended pending input. The user cannot jump ahead and provide input for future steps in the workflow that have not yet occurred.
Note:  A locking conflict may occur if two (or more) users attempt to provide input to a workflow instance (e.g. approve a request) at exactly the same time. If this happens, input from only one of the users will be reflected in the Management Portal, and the workflow instance will not be moved along to the next step if it should have been with input from the two users. The other input is still accepted, however, and there is a scheduled task that runs daily and attempts to continue all suspended workflows that may be eligible to continue but have not done so due to locking conflicts.
Tip:  The following permissions (see Security Roles and Claims) are required to use this feature:

The user executing the request must hold at least one security role ID configured in the workflow definition step for which signal data is being input.

Table 837: POST Workflow Instances {instanceid} Signals Input Parameters

Name In Description
instanceId Path

Required. A string indicating the Keyfactor Command reference GUID of the workflow instance to which to input a signal.

Use the GET /Workflow/Instances method (see GET Workflow Instances) to retrieve a list of all the workflow instances to determine the GUID.

SignalKey Body

Required. A string indicating the key for the signal. This is made up of the unique name for the step within the definition plus the signal type, separated by a period (UniqueName.SignalType). For a Require Approval step, the key input type will be ApprovalStatus, so the full SignalKey will look something like:

RequireApproval1.ApprovalStatus

Use the GET /Workflow/Definitions/{definitionid} method (see GET Workflow Definitions Definition ID) to return workflow details including the workflow steps to determine the UniqueName of the step for which you want to input a signal or one of the GET methods for workflow instances (see GET Workflow Instances, GET Workflow Instances AssignedToMe, or GET Workflow Instances My) to return the CurrentStepUniqueName.
Data Body

Required. An object providing the input information for the signal. The key(s) will vary depending on the signal. ClosedShow RequireApproval signal data details.

For example, to approve a Require Approval step called RequireApproval1 with a comment:

Copy 
{
   "SignalKey": "RequireApproval1.ApprovalStatus",
   "Data": {
      "Approved": "True",
      "Comment": "Here is my comment."
   }
}
Tip:  See the Keyfactor API Reference and Utility which provides a utility through which the Keyfactor APIClosed A set of functions to allow creation of applications. Keyfactor offers the Keyfactor API, which allows third-party software to integrate with the advanced certificate enrollment and management features of Keyfactor Command. endpoints can be called and results returned. It is intended to be used primarily for validation, testing and workflow development. It also serves secondarily as documentation for the API. The link to the Keyfactor API Reference and Utility is in the dropdown from the help icon () at the top of the Management Portal page next to the Log Out button.