Enroll Certificate and Push

This API is used to create a certificate and push it to the selected device.

Before you begin

Before attempting to trigger these service requests, ensure that:

The workflow is enabled.

Note: For more information on how to enable a workflow, refer the section on Managing Certificates using Automation Workflows.
The API user has the necessary RBAC permissions to trigger the workflow. 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, if username and password are not provided) Session ID received after login. Type: String
username `Header`	(Mandatory if sessionId is not provided) AppViewX login username. Type: String Constraint: Required if sessionId is not provided.
password `Header`	(Mandatory if sessionId is not provided) AppViewX login password. Type: String Constraint: Required if sessionId is not provided.
gwsource `Query`	(Mandatory) Source from which the request is triggered Type: String
Payload `Body`	Contains all the parameters to be sent in the request body for the put request. Type: Payload

Payload

Table 2. Payload
Name	Description
validity_value	(Mandatory) Validity value for the certificate Type: String
validity_unit	(Mandatory) Unit of validity for the certificate Type: String Possible values: Days, Months, Years
user_email	(Mandatory) Email address for sending notification of the status of certificate creation and push Type: String
uris	(Mandatory only for EJBCA, Microsoft Enterprise CA, and Microsoft Standalone CA) Uniform Resource Identifier for the certificate Type: String
upload_csr	(Mandatory only ifinput_method is upload_csr) CSR for the new certificate Type: String
state	(Optional) State in which the organization is located Type: String
san	(Optional) Subject Alternative Name of the certificate Type: String Possible values: DNS, IP Address
rfc822names	(Mandatory only for EJBCA, Microsoft Enterprise CA, and Microsoft Standalone CA)Email address(es) of the user(s) to whom the certificate is issued Type: String
renew_before	(Mandatory only if auto_renew is enabled) The renewal request will be triggered prior to the expiry date as per the selected renew_before days. Type: String
registered_ids	(Mandatory only for Microsoft Enterprise CA and Microsoft Standalone CA) Registered id of the certificate Type: String
regenerate_before	(Mandatory only if auto_regenerate is enabled) The regenerate request will be triggered prior to the expiry date as per the selected regenerate_before days. Type: String
push_devices	(Mandatory) Contains all device fields Type: Array of attributes
othernames	(Mandatory only for Microsoft Enterprise CA and Microsoft Standalone CA) Other names for the certificate Type: String
organization_unit	(Optional) Organization unit requesting the certificate Type: String
organization	(Mandatory only for AppViewX CA, EJBCA, and Microsoft Enterprise CA) Name of the organization requesting the certificate Type: String
microsoft_enterprise_template_name	(Mandatory for Microsoft Enterprise CA) Template name for Microsoft Enterprise Type: String
mail_address	(Optional) Email address of the organization Type: String
locality	(Optional) Locality in which the organization is situated Type: String
key_type	(Mandatory only ifinput_method is Manual or Policy Based) Key type for the certificate Type: String Possible values: RSA, DSA, EC
ip_addresses	(Optional) IP values Type: String Example: 192.16x.xx.x Constraints: Multiple values must be separated by a comma (,).
input_method	(Mandatory) Certificate creation method Type: String Possible values: Manual, Policy Based, Upload CSR
hash_function	(Mandatory) Hash function for the certificate Type: String Possible Values: SHA256
entrust_additional_emails	(Mandatory only for the Entrust CA) Additional email address(es) Type: String
elliptic_curve	(Mandatory if key_type = EC) Elliptic curve value for the certificate Type: String
ejbca_issuer_common_name	(Mandatory for EJBCA) Common name of the EJBCA issuer Type: String
ejbca_end_entity_user_name	(Mandatory for EJBCA) User name of the EJBCA end entity Type: String
ejbca_end_entity_profile_name	(Mandatory for EJBCA) Profile name of the EJBCA end entity Type: String
ejbca_certificate_profile_name	(Mandatory for EJBCA) Profile name associated with the EJBCA certificate Type: String
dns_names	(Optional) DNS values Type: String Example: www.appviewx.com Constraints: Multiple values must be separated by a comma (,).
division	(Mandatory only for DigiCert CA) Division values for DigiCert Type: String
directory_names	(Mandatory for EJBCA, Microsoft Enterprise CA, and Microsoft Standalone CA) Directory names for the certificate Type: String
digicert_server_type	(Mandatory only for DigiCert CA) DigiCert server type value Type: String
device_type	(Mandatory) Type of device to which the certificate will be pushed Type: String Possible values: ADC, Server
description	(Optional) Description of the certificate Type: String
country	(Optional) Country in which the organization is located Type: String
common_name	(Mandatory) Common name of the certificate Type: String
check_attribute	(Optional) Certificate attribute values Type: String Possible values: True, False Constraints: The certificates_attributes field will be passed only if check_attribute = true.
challenge_password	(Optional) Password to access the certificate Type: String
certificate_group	(Mandatory) Specifies the group under which the created certificate needs to be tagged Type: String
certificate_authority	(Mandatory) Name of the certificate authority that will issue the certificate Type: String
cert_type	(Mandatory for DigiCert CA) Cert Type values for DigiCert and Entrust Type: String
cert_category	(Mandatory) Specifies the certificate category Type: String Possible values: Server, Client
cert_attributes	Array of certificate attributes Type: Array of cert_attributes
ca_account	(Mandatory) CA account name of certificate authority Type: String
bit_length	(Mandatory only ifinput_method is Manual or Policy Based) Bit length for the certificate Type: String Possible values: 4096, 2048
auto_renew	(Mandatory) If enabled, renewal will be scheduled to trigger before expiry based on renew_before days. Type: String
auto_regenerate	(Mandatory) If enabled, regenerate will be scheduled to trigger before expiry based on regenerate_before days. Type: String

Table 3. cert_attributes
Name	Description
attribute	(Optional) Certificate attribute name Type: String
attribute_value	(Optional) Corresponding certificate attribute value Type: String

Table 4. Attributes for push_devices
Name	Description
device_vendor	(Mandatory) Device vendor type based on selection of device type Type: String Possible values: F5, LinuxServer, Citrix
device	(Mandatory) Device name for the selected device vendor Type: String
linux_actions	(Mandatory) Linux action for the selected device vendor Type: String Possible values: Default, Create KDB label (.kdb), Certificate Overwrite (.kdb)
selected_profiles	(Mandatory) Profile name for the device Type: String
apache_custom_new	(Mandatory for Apache devices) Provision to opt for pushing the certificate to a custom location Type: String Possible values: Yes, No
apache_certificate_location	(Mandatory if apache_custom_new = Yes) Certificate path created by the user Type: String
apache_key_location	(Mandatory if apache_custom_new = Yes) Certificate Key path created by the user Type: String
password	(Mandatory if linux_actions = Default) Password for accessing the KDB file Type: String
push_cert_type	(Mandatory) Certificate type being pushed Type: String

Response Structure

200 OK returns string of type application/json with the following body params:

Table 5. Response Structure
Name	Description
response	Contains the response params for the search object request. Type: Response
message	Success message or failure description in case of error. Type: String
appStatusCode	Application specific status code for the response Will be non-null for failure response Type: String
tags	More information in case of a failure response Type: NA

Table 6. Response
Name	Description
requestId	Unique identifier for the request Type: String
workflowVersion	Version of the workflow Type: String
message	The message with the status and request number for the request Type: String
status	Status of the request Type: String
stausCode	Status code for the request Type: String
requestType	Request type Type: String
workorderId	The ID of the work order for the request If there is no workorder, the value will be 0. Type: String

Status Codes

Table 7. Status codes
HTTP Code	appStatusCode	Response Message
200 OK	NA	Success Remediation: NA
400 Bad Request	avx-common-028	Invalid/ Incorrect payload Remediation: Check and ensure if a valid value is given in the request payload field - input.
401 Unauthorized	WORKFLOW_1679	User is not authorized. Remediation: Ensure that logged-in user is authorized to access the workflow.
404 Not Found	engine-db-015	Workflow not found. Remediation: Ensure the workflow data is valid.
409 Conflict	WORKFLOW_1475	Given workflow is not in enabled state. Remediation: Enable the workflow.
500 Internal Server Error	WORKFLOW_1617	Invalid form data. Please provide all mandatory data Remediation: Ensure a valid value is given in the request payload field - input.
500 Internal Server Error	NA	Error while processing Remediation: NA

Sample Request/Response

Sample Request

{
  "payload": {
    "header": {
      "workflowName": "Certificate Create and Push"
    },
    "data": {
      "input": {
        "requestData": [
          {
            "sequenceNo": 1,
            "scenario": "scenario",
            "fieldInfo": {
              "info": "",
              "cert_category": "Server,Client,Code Signing",
              "certificate_group": "<mandatory field>",
              "certificate_authority": "DigiCert,Entrust,Ejbca,Microsoft Enterprise,Microsoft Standalone",
              "ca_account": "<mandatory field>",
              "division": "<mandatory field>",
              "cert_type": "",
              "auto_renew": "Off,On",
              "renew_before": "<mandatory field>",
              "auto_regenerate": "Off,On",
              "regenerate_before": "<mandatory field>",
              "input_method": "Manual,Policy Based,Upload CSR",
              "upload_csr": "<mandatory field>",
              "common_name": "<mandatory field>",
              "san": "DNS,IP Address",
              "directory_names": "",
              "dns_names": "",
              "rfc822names": "",
              "ip_addresses": "",
              "registered_ids": "",
              "uris": "",
              "othernames": "",
              "organization": "",
              "organization_unit": "",
              "locality": "",
              "state": "",
              "country": "",
              "mail_address": "",
              "postal_code": "",
              "validity_unit": "Days,Months,Years",
              "validity_value": "1",
              "challenge_password": "",
              "hash_function": "<mandatory field>",
              "key_type": "EC",
              "bit_length": "<mandatory field>",
              "elliptic_curve": "<mandatory field>",
              "attributes_available": "true",
              "cert_attributes": [
                {
                  "attribute": "",
                  "attribute_value": ""
                }
              ],
              "digicert_server_type": "<mandatory field>",
              "ejbca_end_entity_profile_name": "<mandatory field>",
              "ejbca_end_entity_user_name": "",
              "ejbca_issuer_common_name": "<mandatory field>",
              "ejbca_certificate_profile_name": "<mandatory field>",
              "entrust_additional_emails": "",
              "microsoft_enterprise_template_name": "<mandatory field>",
              "device_type": "ADC,Server",
              "push_devices": [
                {
                  "device_vendor": "<mandatory field>",
                  "device": "<mandatory field>",
                  "linux_action": "Default,Create KDB label (*.kdb),Certificate Overwrite (*.kdb)",
                  "selected_profiles": "<mandatory field>",
                  "password": "<mandatory field>",
                  "push_cert_type": "<mandatory field>"
                }
              ],
              "user_email": ""
            }
          }
        ]
      },
      "globalData": {},
      "task_action": 1
    }
  }
}

Note: Please refer to the request structure to identify the changeable values.

Sample Response

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

References

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.