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.