Initiate a User Workflow

In this example, we initiate the single user workflow returned in the flows array in the Start the Attestation Process topic.

The request:

uses the businessProcess object reference to identify the user workflow to execute
uses attestationProcessId inside processVariables to identify the specific Attestation process initiated by the employee who started the attestation process

Note: Pass all of the properties in params inside processVariables in the request payload for each user workflow you initiate.

Example request

Call the Execute Business Process (POST /v1/platform/workflow/business_processes/execute) operation with the following request payload.

{
  "businessProcess": {
    "id": 10509
  },
  "processVariables": {
    "attestationProcessId": 9
  }
}

Request model property notes

processVariables is a list of key-value pairs that represent the process variables associated with the business process to execute. If a key matches a defined process variable, the value is passed and accepted by the process variable. If a key does not match a defined process variable, a new process variable is created using the passed key-value pair. This property is optional. Pass all of the properties in params inside processVariables in the request payload for each user workflow you initiate.
businessProcess contains the ID or qualifier of the business process to execute. Use the Retrieve Business Process (GET /v1/platform/workflow/business_processes) operation to return valid business processes. This property is required. If both ID and qualifier are provided then ID is processed and qualifier is ignored.

Example response

A success response returns HTTP status code 200 and a response body similar to the following example.

{
  "formStructureData": "{\"modelLocaleKey\":\"SimpleQuestionFormv2\",\"processDefinitionId\":\"SimpleQuestionFormv2:1:10512\",\"metadata\":{},\"variables\":[],\"tabs\":[],\"customFieldsValueInfo\":{\"next\":{\"type\":\"string\",\"value\":\"value\"},\"cancel_button\":{\"type\":\"string\",\"value\":\"value\"},\"submit\":{\"type\":\"string\",\"value\":\"value\"},\"show_my_timecard\":{\"type\":\"string\",\"value\":\"value\"},\"header\":{\"type\":\"string\",\"value\":\"value\"},\"dynamic_radio_buttons\":{\"type\":\"string\",\"value\":\"value\"},\"dynamic_dropdown\":{\"type\":\"string\",\"value\":\"value\"}},\"processDefinitionName\":\"Simple Question Form v2\",\"className\":\"\",\"processDefinitionKey\":\"SimpleQuestionFormv2\",\"taskDefinitionKey\":\"simple_form\",\"outcomes\":[],\"javascriptEvents\":[],\"name\":\"Simple question form\",\"globalDateFormat\":\"D-M-YYYY\",\"taskName\":\"simple_form\",\"id\":3003,\"fields\":[{\"col\":-1,\"minLength\":0,\"regexPattern\":null,\"className\":null,\"type\":\"container\",\"required\":false,\"colspan\":1,\"optionType\":null,\"restUrl\":null,\"minValue\":null,\"tab\":null,\"dateDisplayFormat\":null,\"options\":null,\"id\":\"1524058561284\",\"placeholder\":null,\"row\":-1,\"value\":null,\"restResponsePath\":null,\"maxValue\":null,\"visibilityCondition\":null,\"readOnly\":false,\"layout\":null,\"hasEmptyValue\":null,\"restLabelProperty\":null,\"sizeX\":2,\"numberOfColumns\":2,\"name\":\"Label\",\"overrideId\":false,\"restIdProperty\":null,\"fields\":{\"1\":[{\"col\":-1,\"minLength\":0,\"regexPattern\":null,\"className\":null,\"type\":\"radio-buttons\",\"required\":true,\"colspan\":1,\"optionType\":null,\"restUrl\":null,\"minValue\":null,\"endpoint\":null,\"tab\":null,\"dateDisplayFormat\":null,\"options\":[{\"name\":\"positive answer\",\"id\":\"positive_answer\"},{\"name\":\"negative answer\",\"id\":\"negative_answer\"}],\"id\":\"questiontextplaceholder\",\"placeholder\":null,\"row\":-1,\"value\":null,\"restResponsePath\":null,\"maxValue\":null,\"visibilityCondition\":null,\"readOnly\":false,\"params\":{\"maxColspan\":2,\"existingColspan\":1},\"layout\":{\"colspan\":1,\"column\":-1,\"row\":-1},\"hasEmptyValue\":null,\"restLabelProperty\":null,\"sizeX\":1,\"requestHeaders\":null,\"name\":\"Question text placeholder\",\"overrideId\":false,\"restIdProperty\":null,\"fieldType\":\"RestFieldRepresentation\",\"maxLength\":0,\"sizeY\":1}],\"2\":[]},\"fieldType\":\"ContainerRepresentation\",\"maxLength\":0,\"sizeY\":1},{\"col\":-1,\"minLength\":0,\"regexPattern\":null,\"className\":null,\"type\":\"container\",\"required\":false,\"colspan\":1,\"optionType\":null,\"restUrl\":null,\"minValue\":null,\"tab\":null,\"dateDisplayFormat\":null,\"options\":null,\"id\":\"1524058567030\",\"placeholder\":null,\"row\":-1,\"value\":null,\"restResponsePath\":null,\"maxValue\":null,\"visibilityCondition\":null,\"readOnly\":false,\"layout\":null,\"hasEmptyValue\":null,\"restLabelProperty\":null,\"sizeX\":2,\"numberOfColumns\":2,\"name\":\"Label\",\"overrideId\":false,\"restIdProperty\":null,\"fields\":{\"1\":[{\"col\":-1,\"minLength\":0,\"regexPattern\":null,\"className\":null,\"type\":\"next\",\"required\":false,\"colspan\":1,\"optionType\":null,\"restUrl\":null,\"minValue\":null,\"tab\":null,\"dateDisplayFormat\":null,\"options\":null,\"id\":\"submitanswer\",\"placeholder\":null,\"row\":-1,\"value\":null,\"restResponsePath\":null,\"maxValue\":null,\"visibilityCondition\":null,\"readOnly\":false,\"params\":{\"maxColspan\":2,\"existingColspan\":1},\"layout\":{\"colspan\":1,\"column\":-1,\"row\":-1},\"hasEmptyValue\":null,\"restLabelProperty\":null,\"sizeX\":1,\"name\":\"Submit answer\",\"overrideId\":false,\"restIdProperty\":null,\"fieldType\":\"FormFieldRepresentation\",\"maxLength\":0,\"sizeY\":1}],\"2\":[{\"col\":-1,\"minLength\":0,\"regexPattern\":null,\"className\":null,\"type\":\"cancel_button\",\"required\":false,\"colspan\":1,\"optionType\":null,\"restUrl\":null,\"minValue\":null,\"tab\":null,\"dateDisplayFormat\":null,\"options\":null,\"id\":\"cancel\",\"placeholder\":null,\"row\":-1,\"value\":null,\"restResponsePath\":null,\"maxValue\":null,\"visibilityCondition\":null,\"readOnly\":false,\"params\":{\"maxColspan\":1,\"existingColspan\":1},\"layout\":{\"colspan\":1,\"column\":-1,\"row\":-1},\"hasEmptyValue\":null,\"restLabelProperty\":null,\"sizeX\":1,\"name\":\"Cancel\",\"overrideId\":false,\"restIdProperty\":null,\"fieldType\":\"FormFieldRepresentation\",\"maxLength\":0,\"sizeY\":1}]},\"fieldType\":\"ContainerRepresentation\",\"maxLength\":0,\"sizeY\":1}],\"taskId\":\"7031\",\"gridsterForm\":false}",
  "formValueData": "{\"formValues\":[{\"scope\":\"local\",\"name\":\"server_name\",\"type\":\"string\",\"value\":\"kacd01-pip40-ins01-wfm70-bck-620282837-1.int.acd.mykronos.com\"},{\"scope\":\"local\",\"name\":\"resourceId\",\"type\":\"string\",\"value\":\"20335\"},{\"scope\":\"local\",\"name\":\"web_server_name\",\"type\":\"string\",\"value\":\"kacd01-pip40-ins01-wfm70-bck-620282837-1.int.acd.mykronos.com\"},{\"scope\":\"local\",\"name\":\"server_language\",\"type\":\"string\",\"value\":\"en\"},{\"scope\":\"local\",\"name\":\"initiator\",\"type\":\"string\",\"value\":\"20335\"},{\"scope\":\"local\",\"name\":\"originator_kreference\",\"type\":\"string\",\"value\":\"longDateFormat=M/dd/yyyy;timeFormat=h:mm a;language=EN;country=US;variant=;shortDatePattern=E M/dd;longDatePattern=M/dd/yyyy;timePattern=H:mm;dayMonthPattern=M/dd;durationsInColonFormat=false;timeIn12HourFormat=false;durationConvertUseTbl=true;daysBasedAccrualInColonFomat=true;successIndicator=h:mm aserverDatePattern=EEEE, MMMM dd, yyyy\"},{\"scope\":\"local\",\"name\":\"originator\",\"type\":\"string\",\"value\":\"20335\"},{\"scope\":\"local\",\"name\":\"employee\",\"type\":\"string\",\"value\":\"20335\"},{\"scope\":\"local\",\"name\":\"ext_tenantId\",\"type\":\"string\",\"value\":\"tkc_atx_tk17210281_nonprd_01\"},{\"scope\":\"local\",\"name\":\"wfc_url\",\"type\":\"string\",\"value\":\"http://kacd01-pip40-ins01-wfm70-bck-620282837-1.int.acd.mykronos.com:8080/wfc\"},{\"scope\":\"local\",\"name\":\"WFD_X_Forwarded_For\",\"type\":\"string\",\"value\":\"10.239.0.190\"},{\"scope\":\"local\",\"name\":\"application_context\",\"type\":\"string\",\"value\":\"wfc\"},{\"scope\":\"local\",\"name\":\"server_port\",\"type\":\"string\",\"value\":\"8080\"},{\"scope\":\"local\",\"name\":\"web_server_protocol\",\"type\":\"string\",\"value\":\"http\"},{\"scope\":\"local\",\"name\":\"attestationProcessId\",\"type\":\"string\",\"value\":\"9\"},{\"scope\":\"local\",\"name\":\"kronos_tid\",\"type\":\"string\",\"value\":\"540d94b23f52465f830ecc881ceb90e7\"},{\"scope\":\"local\",\"name\":\"isReassignable\",\"type\":\"string\",\"value\":\"false\"},{\"scope\":\"local\",\"name\":\"server_protocol\",\"type\":\"string\",\"value\":\"http\"}]}",
  "message": "The business process initiated successfully.",
  "processInstance": {
    "id": 7009
  },
  "task": {
    "id": 7031
  }
}

Response analysis

Note that the response model is identical between the Execute Business Process response in this step and the Submit Business Process Form Data response in the next step.

The formStructureData object returns a JSON string that must be parsed and transformed into a representation of the attestation form for your application's UI. Extract the portions relevant for the flow and use them as input for the next call, where they are used in the fields array in the request payload when you Submit an Attestation Form.

The formValueData response property represents the status of all the execution variables. formValueData is not returned by default, but can be returned if the request payload Boolean returnProcessVariables is set to true and the workflow action is SubmitAndNext for a multiuser task model.