Submit Request

Creates a new workflow request for the given workflow name. A request id is generated and associated with each submitted workflow request which can be used later for retrieving any information about the request.

Before you begin

Before attempting to submit a request with this API, you must ensure that the following permissions are available:

Service Requests > Action > View all requests
Service Requests > Action > View my requests

You can check this in the Platform module under IDENTITY > Role > Authorized functions.

Request Structure


Endpoint:	`/visualworkflow-submit-request`
Type:	`POST`
Sample URL:	`https://<IP/HostName/TenantName>:<GWPORT>/avxapi/visualworkflow-submit-request?gwsource=external` To understand the elements of the sample URL, click here.
Headers:
Content-Type:	application/json

Table 1. Input Parameters
Name	Description
sessionID `Header`	(Mandatory) Use session ID retrieved from login API is required if username and password are not provided. Example: "sessionId": "ce7f1a14-2bf9-4e4a-89a8-bc780a255813"
username `Header`	(Mandatory) AppViewX login username is required if sessionId is not provided. Example: "admin"
password `Header`	(Mandatory) AppViewX login password is required if sessionId is not provided.. Example: "AppViewX@123"
Content-Type `Header`	(Mandatory) The parameter should be set to `application/json` to specify the nature of the data in the payload. Example: "application/json"
gwsource `Query`	(Mandatory) Source from which the request is triggered. The values can be: web external
Payload `String`	(Mandatory) Input data for request body in application/json format. For payload details, see Payload section. Any one of the following: `Service Task Payload` `User Task Payload`

Task Specific Information

Service Task Payload

Service tasks will not have any user input for submitting the request.


Name	Description
workflowName `Header Payload`	(Mandatory) The workflow for which the request is submitted. Type: `String` Example: "servicenow Test"

Sample Request/Response

Use Case

Submit a request for the workflow servicenow Test.

Request URL

https://<IP/HostName/TenantName>:<GWPORT>/avxapi/visualworkflow-submit-request?gwsource=external

Request Payload

{
  "payload": {
    "header": {
      "workflowName": "servicenow Test"
    }
  }
}

Sample Response

{
  "response": {
    "workorderId": "0",
    "message": "Workflow Request is created with Id 401 . Request submitted to workflow engine for processing workorder.",
    "requestType": "default",
    "requestId": "401",
    "workflowVersion": "master",
    "status": "In Progress",
    "statusCode": 0
  },
  "message": null,
  "appStatusCode": null,
  "tags": null
}

User Task Payload


Name	Description
workflowName `Header Payload`	(Mandatory) The workflow for which the request is submitted. Type: `String` Example: "Sample 2"
Input Payload
input `Data Payload`	(Mandatory) The input data for the user task. Type: `String`
requestData `Request Data Payload`	(Mandatory) The request data for which the request is submitted. List of Request Data Payloads.
Request Data Payload
scenario `Request Data Payload`	(Mandatory) The scenario name for the form. Type: `String` Example: "scenario"
sequenceNo `Request Data Payload`	(Mandatory) The sequence number of the scenario. Type: `Integer` Example: "2"
fieldInfo `Request Data Payload`	(Mandatory) The field info configured in the form. The value should be key value, field id and its value. Type: `Json` Example: "deviceName": "ADC"
task_action `Data Payload`	(Mandatory) Action to be performed on the task. Type: `Integer` Constraints: 1 for success case and 2 for reject case. Example: "1"

Sample Request/Response - Form Task

Use Case

Submit a request for the workflow with the first task as Form.

Note: When using the visualworkflow-submit-request API for a form task, any regex pattern provided by the user will be validated on the server side. It is essential that users provide a valid value in the payload.

Request URL

https://<IP/HostName/TenantName>:<GWPORT>/avxapi/visualworkflow-submit-request?gwsource=external

Request Payload

{
  "payload": {
    "header": {
      "workflowName": "Sample 2"
    },
    "data": {
      "input": {
        "requestData": [
          {
            "scenario": "scenario",
            "sequenceNo": 1,
            "fieldInfo": {
              "deviceName": "ADC"
            }
          },
          {
            "scenario": "scenario2",
            "sequenceNo": 2,
            "fieldInfo": {
              "deviceName": "A10"
            }
          }
        ]
      },
      "task_action": 1
    }
  }
}

Sample Response

{
  "response": {
    "workorderId": "0",
    "message": "Workflow Request is created with Id 55 . Request submitted to workflow engine for processing workorder.",
    "requestType": "default",
    "requestId": "401",
     "workflowVersion": "master",
    "status": "In Progress",
    "statusCode": 0
  },
  "message": null,
  "appStatusCode": null,
  "tags": null
}

Sample Request/Response - Grid Task

Use Case

Submit a request for the workflow with the first task as Grid.

Request URL

https://<IP/HostName/TenantName>:<GWPORT>/avxapi/visualworkflow-submit-request?gwsource=external

Request Payload

{
"payload": {
    "data": {
      "input": {
        "columnLabels": {
          "IP": "IP",
          "Device Name": "Device Name"
        },
        "gridData": [
          {
            "IP": "","Device Name": ""
          }
        ]
      },
      "globalData" : { "gridData": [
          {
            "IP": "192.168.15.35",
            "Device Name": "Device F5"
          },
          {
            "IP": "192.168.15.40",
            "Device Name": "Device AVI"
          }
        ]},
      "task_action": 1
    },
    "header": {
      "workflowName": "Grid"
    }
  }
}

Note: Global Variable <%gridData%> should be present in the “values” section in Grid Task.

Sample Response

{
  "response": {
    "workorderId": "0",
    "message": "Workflow Request is created with Id 24 . Request submitted to workflow engine for processing workorder.",
    "requestType": "default",
    "requestId": "401",
     "workflowVersion": "master",
    "status": "In Progress",
    "statusCode": 0
  },
  "message": null,
  "appStatusCode": null,
  "tags": null
}

Sample Request/Response - Script Task

Use Case

Submit a request for the workflow with the first task as Script.

Request URL

https://<IP/HostName/TenantName>:<GWPORT>/avxapi/visualworkflow-submit-request?gwsource=external

Request Payload

{
  "payload": {
    "data": {
      "globalData":{"script" : "Device 25"},
      "task_action": 1
    },
    "header": {
      "workflowName": "script"
    }
  }
}

Note: Values can be passed to available Global variables present inside the Script task.

Sample Response

{
  "response": {
    "workorderId": "0",
    "message": "Workflow Request is created with Id 26. Request submitted to workflow engine for processing workorder.",
    "requestType": "default",
    "requestId": "401",
     "workflowVersion": "master",
    "status": "In Progress",
    "statusCode": 0
  },
  "message": null,
  "appStatusCode": null,
  "tags": null
}

Sample Request/Response - YAML Task

Use Case

Submit a request for the workflow with the first task as YAML.

Request URL

https://<IP/HostName/TenantName>:<GWPORT>/avxapi/visualworkflow-submit-request?gwsource=external

Request Payload

{
  "payload": {
    "data": {
      "input": {
        "editorContent": "<%yaml%>",
        "type": "YAML"
      },
      "globalData":{"yaml" : "---\n-\n    name: Manage BIG-IP APM policy or APM access profile imports\n    hosts: localhost\n    tasks:\n         - name: Import APM profile\n           bigip_apm_policy_import:\n             name: new_apm_profile"},
      "task_action": 1
    },
    "header": {
      "workflowName": "yaml"
    }
  }
}

Note: Global Variable <%yaml%> should be present in the YAML task.

Sample Response

{
  "response": {
    "workorderId": "0",
    "message": "Workflow Request is created with Id 26 . Request submitted to workflow engine for processing workorder.",
    "requestType": "default",
    "requestId": "401",
     "workflowVersion": "master",
    "status": "In Progress",
    "statusCode": 0
  },
  "message": null,
  "appStatusCode": null,
  "tags": null
}

Response Structure

Status Code: 200 OK
Message: Success
Headers:
- Content-Type: application/json

Table 2. Response Parameters
Name	Description
response `Key value pair`	Contains the response params for the search object request. For more `response` details.
message `String`	Success message or failure description in case of error.
appStatusCode `String`	Application specific status code for the response, will be non-null for failure response.
tags `NA`	More info in case of failure response.

Table 3. Response
Name	Description
requestID `String`	Unique identifier for the request.
workflowVersion `String`	Version of the workflow.
message `String`	The message with the status and request number for the request.
status `String`	Status of the request.
statusCode `Integer`	Status code of the request
requestType `String`	The type of the request.
workorderId `String`	The workoderId for the request. If there is no workorder the value will be 0.

Status Codes


HTTP Code	appStatusCode	Message and Remediation
200 OK	NA	Success
400 Bad request	avx-common-028	Invalid/Incorrect payload. Possible Remediation: Check and ensure if a valid value is given in request payload field - input.
401 Unauthorized	WORKFLOW_1679	User is not authorized. Possible Remediation: LoggedIn user is not authorized to access the workflow.
404 Not Found	engine-db-015	Workflow not found. Possible Remediation: Invalid workflow data.
409 Conflict	WORKFLOW_1475	Given workflow is not in enabled state. Possible Remediation: Given workflow is not in enabled state.
500 Internal Server Error	WORKFLOW_1617	Invalid form data. Please provide all mandatory data. Possible Remediation: Check and ensure if a valid value is given in request payload field - input.
500 Internal Server Error	NA	Error while processing. Possible Remediation: Task is already completed. Task is being processed by another user.

Reference

Understanding the sample URL

IP/HostName/TenantName: Replace with the actual IP address, hostname, or tenant name based on the specific configuration in AppViewX.
- IP: A unique identifier assigned to each device connected to a computer network that uses the Internet Protocol for communication
  The IP address will be included in the endpoint URL for an on-prem deployment.
- HostName: A human-readable label assigned to a device (host) on a network
  The hostname will be included in the endpoint URL for an on-prem deployment.
- TenantName: An identifier label for a tenant given to indicate which tenant's data the API request will access/modify
  The tenant name will be included in the endpoint URL for a SaaS deployment.
GWPORT: AppViewX gateway port
A gateway port refers to a network port through which data is sent and received to communicate with a gateway in an on-prem deployment.
Example: 31443
avxapi: Path parameter value (static) that is part of the endpoint's URL
Endpoint: Endpoint of the API, for example: execute-hook
gwsource: Source or origin of a gateway, for example: external.