PingOne Platform APIs

DaVinci Admin Flow Versions

The PingOne DaVinci Admin Flow Versions service provides endpoints to read, update, and delete DaVinci flow versions. This service also includes endpoints to export, revert, and see details about a flow version.

The flow version update operation applies only to the alias property to add or change the user-friendly name associated with the flow version.

Assigning admin roles and permissions to this service

Admin role assignments determine access to PingOne APIs. When assigning admin roles to this service, refer to PingOne Permissions by Service for the service-specific permissions.

You can also choose to assign admin roles based on particular service resources. Refer to PingOne Permissions by Resource when assigning admin roles per service resources.

Admin assignments to roles are set by:

Refer to Roles Management for more information.

DaVinci admin flow versions data model properties

Property Type Required Mutable Description

alias

String

Optional

Mutable

The user defined flow version alias.

clonedFrom

Number

Optional

Immutable

The version number from which this flow version was cloned or created.

connectors

Array[object]

Optional

Mutable

An array of connectors that apply to the flow.

connectors[].id

String

Optional

Mutable

The connector ID (or IDs) associated with the flow. Example connectors are httpConnector, functionsConnector, pingOneVerifyConnector, and annotationConnector.

createdAt

Time

N/A

Read only

The timestamp when the flow was created.

deployedAt

Time

N/A

Read only

The stamp when the flow was last deployed.

description

String

Optional

Mutable

The description of the flow.

enabled

Boolean

Optional

Immutable

Specifies the state of the flow. This can be stored as its own value in the database or it can reflect an existing flowStatus.

environment

Object

N/A

Read only

The DaVinci company ID (environment ID) object.

environment.id

String

N/A

Read only

The DaVinci company ID, which is the PingOne environment ID.

graphData

Object

Optional

Mutable

The graph-based representation of the flow depicted in the UI. Refer to the Flow versions graph data property data model table for details.

flow

Object

Required

Immutable

The flow object associated with this flow version.

flow.id

String

Required

Immutable

The flow ID of the flow associated with this flow version.

flow.name

String

Required

Immutable

The name of the flow associated with this flow version.

includeSubFlows

Boolean

Optional

Mutable

Specifies whether the exported flow version should include subflows.

includeVariableValues

Boolean

Optional

Mutable

Specifies whether the exported flow version should include variable values.

outputSchema

Object

Required

Mutable

The JSONschema output object of the flow.

updatedAt

Date

N/A

Read only

The timestamp when the flow was updated or saved.

version

Number

Required

Mutable

The version number of the flow instance represented by this object.

Flow versions details property data model

The following table lists the supported flow versions details settings properties.

Property Type Required Mutable Description

color

String

Optional

Mutable

The color of the flow.

connectors

Array[object]

Optional

Mutable

An array of connectors that apply to the flow.

connectors.id

String

Optional

Mutable

The connector ID (or IDs) associated with the flow.

description

String

Optional

Mutable

The description of the flow.

enabled

Boolean

Optional

Immutable

Specifies the state of the flow.

graphData

Object

Optional

Mutable

The graph-based representation of the flow depicted in the UI. Refer to the Flow versions graph data property data model table for details.

inputSchema

Array[object]

Optional

Mutable

The flow input parameters in an array of JSONschema objects.

name

String

Required

Mutable

The name of the flow.

outputSchema

Object

Required

Mutable

The JSONschema output object of the flow.

settings

Object

Optional

Mutable

Flow settings saved by the user. Refer to the Settings property data model table for details.

trigger

Object

Optional

Mutable

The flow trigger object.

trigger.type

String

Optional

Mutable

If the trigger type is set to AUTHENTICATION, you invoke the flow through PingOne OpenID Connect or SAML endpoints.

trigger.configuration

Object

Optional

Mutable

The configuration object for session reuse.

trigger.configuration.pwd

Object

Optional

Mutable

The configuration object for password session reuse.

trigger.configuration.pwd.enabled

Boolean

Optional

Mutable

Specifies whether this configuration must be used to check for existing sessions.

trigger.configuration.pwd.lastSignOn

Integer

Optional

Mutable

An integer that specifies the duration (in seconds) that an active session can be reused.

trigger.configuration.mfa

Object

Optional

Mutable

The configuration object for MFA session reuse.

trigger.configuration.mfa.enabled

Boolean

Optional

Mutable

Specifies whether this configuration must be used to check for existing sessions.

trigger.configuration.mfa.lastSignOn

Integer

Optional

Mutable

An integer that specifies the duration (in seconds) that an active session can be reused.

updates

Array

N/A

Read only

String of actions taken to generate this version from the previous version.

Flow versions graph data property data model

The following table lists the supported flow versions graph data settings properties.

Property Type Required Mutable Description

graphData

Object

Optional

Mutable

The graph-based representation of the flow depicted in the UI.

graphData.elements

Object

Required

Mutable

If graphData is set, the graphData.elements object must be defined.

graphData.elements.nodes[]

Array[Object]

Required

Mutable

If graphData.elements is set, the graphData.elements.nodes[] object must be defined.

graphData.elements.nodes[].data

Object

Required

Mutable

The node item data associated with the flow version. If graphData.elements.nodes[] is set, the graphData.elements.nodes[]].data object must be defined.

graphData.elements.nodes[].data.nodeType

String

Required

Mutable

The node type associated with the node item.

graphData.elements.nodes[].data.connectionId

String

Optional

Mutable

The connection ID associated with the node item.

graphData.elements.nodes[].data.connectorId

String

Optional

Mutable

The connector ID associated with the node item.

graphData.elements.nodes[].data.name

String

Optional

Mutable

The name of the node item.

graphData.elements.nodes[].data.label

String

Optional

Mutable

The label associated with the node item.

graphData.elements.nodes[].data.status

String

Optional

Mutable

The status of the node item.

graphData.elements.nodes[].data.capabilityName

String

Optional

Mutable

The name of the capability associated with the node item.

graphData.elements.nodes[].data.type

String

Optional

Mutable

The type associated with the node item.

graphData.elements.nodes[].data.properties

Object

Optional

Mutable

The properties associated with the node item.

graphData.elements.nodes[].data.properties.nodeTitle

Object

Optional

Mutable

The node title object.

graphData.elements.nodes[].data.properties.nodeTitle.value

String

Required

Mutable

The node title text.

graphData.elements.nodes[].data.properties.code

Object

Optional

Mutable

The node item code object.

graphData.elements.nodes[].data.properties.code.value

String

Required

Mutable

The code associated with the node item.

graphData.elements.nodes[].data.properties.type

Object

Optional

Mutable

The node type object.

graphData.elements.nodes[].data.properties.type.value

String

Required

Mutable

The node type.

graphData.elements.nodes[].data.properties.customCSS

Object

Optional

Mutable

The node’s stylesheet object.

graphData.elements.nodes[].data.properties.customCSS.value

String

Required

Mutable

The node’s CSS.

graphData.elements.nodes[].data.properties.customHTML

Object

Optional

Mutable

The node’s HTML object.

graphData.elements.nodes[].data.properties.customHTML.value

String

Required

Mutable

The node’s custom HTML.

graphData.elements.nodes[].data.properties.customScript

Object

Optional

Mutable

The node’s script object.

graphData.elements.nodes[].data.properties.customScript.value

String

Required

Mutable

The node’s custom scripts.

graphData.elements.nodes[].data.properties.backgroundColor

Object

Optional

Mutable

The node’s background color object.

graphData.elements.nodes[].data.properties.backgroundColor.value

String

Required

Mutable

The node’s background color.

graphData.elements.nodes[].data.properties.inputSchema

Object

Optional

Mutable

The node’s input schema object.

graphData.elements.nodes[].data.properties.inputSchema.value

String

Required

Mutable

The node’s input schema.

graphData.elements.nodes[].data.properties.outputSchema

Object

Optional

Mutable

The node’s output schema object.

graphData.elements.nodes[].data.properties.outputSchema.value

String

Required

Mutable

The node’s output schema.

graphData.elements.nodes[].data.properties.message

Object

Optional

Mutable

The node’s message object.

graphData.elements.nodes[].data.properties.message.value

String

Required

Mutable

The node’s message text.

graphData.elements.nodes[].data.properties.showContinueButton

Object

Optional

Mutable

The node’s show continue button object.

graphData.elements.nodes[].data.properties.showContinueButton.value

Boolean

Required

Mutable

Specifies whether to show the node’s continue text.

graphData.elements.nodes[].data.properties.saveVariables

Object

Optional

Mutable

The node’s save variables object.

graphData.elements.nodes[].data.properties.saveVariables.value

Array[Object]

Required

Mutable

An array of variables that are saved.

graphData.elements.nodes[].data.properties.formFieldList

Object

Optional

Mutable

The node’s form fields object.

graphData.elements.nodes[].data.properties.formFieldsList.value

Array[Object]

Required

Mutable

An array of form fields associated with the node.

graphData.elements.nodes[].data.properties.variableInputList

Object

Optional

Mutable

The node’s variable input list object.

graphData.elements.nodes[].data.properties.variableInputList.value

Array[Object]

Required

Mutable

An array of input variables associated with the node.

graphData.elements.nodes[].data.properties.additionalProperties

Array[Object]

Optional

Mutable

An array of additional properties allowed by the node.

graphData.elements.nodes[].data.additionalProperties

Array[Object]

Optional

Mutable

An array of additional properties allowed in the Item definition.

graphData.elements.nodes[].position

Object

Required

Mutable

The node’s position object.

graphData.elements.nodes[].position.x

Number

Required

Mutable

The node’s x-axis position.

graphData.elements.nodes[].position.y

Number

Required

Mutable

The node’s y-axis position.

graphData.elements.nodes[].group

String

Required

Mutable

The node’s group.

graphData.elements.nodes[].removed

Boolean

Required

Mutable

Specifies whether the node can be removed.

graphData.elements.nodes[].selected

Boolean

Required

Mutable

Specifies whether the node can be selected.

graphData.elements.nodes[].selectable

Boolean

Required

Mutable

Specifies whether the node is selectable.

graphData.elements.nodes[].locked

Boolean

Required

Mutable

Specifies whether the node is locked.

graphData.elements.nodes[].grabbable

Boolean

Required

Mutable

Specifies whether the node is grabbable.

graphData.elements.nodes[].pannable

Boolean

Required

Mutable

Specifies whether the node can be moved.

graphData.elements.nodes[].classes

String

Optional

Mutable

The classes associated with the node.

graphData.elements.edges[]

Array[Object]

Required

Mutable

The object that describes the graph data element edges.

graphData.elements.edges[].data

Object

Required

Mutable

The object that describes the edges data.

graphData.elements.edges[].data.id

String

Required

Mutable

The edges element ID.

graphData.elements.edges[].data.source

String

Required

Mutable

The edges element source.

graphData.elements.edges[].data.target

String

Required

Mutable

The edges element target.

graphData.elements.edges[].position

Object

Required

Mutable

The edge’s position object.

graphData.elements.edges[].position.x

Number

Required

Mutable

The edge’s x-axis position.

graphData.elements.edges[].position.y

Number

Required

Mutable

The edge’s y-axis position.

graphData.elements.edges[].group

String

Required

Mutable

The edge’s group.

graphData.elements.edges[].removed

Boolean

Required

Mutable

Specifies whether the edge can be removed.

graphData.elements.edges[].selected

Boolean

Required

Mutable

Specifies whether the edge can be selected.

graphData.elements.edges[].selectable

Boolean

Required

Mutable

Specifies whether the node is selectable.

graphData.elements.edges[].locked

Boolean

Required

Mutable

Specifies whether the edge is locked.

graphData.elements.edges[].grabbable

Boolean

Required

Mutable

Specifies whether the edge is grabbable.

graphData.elements.edges[].pannable

Boolean

Required

Mutable

Specifies whether the edge can be moved.

graphData.elements.edges[].classes

String

Optional

Mutable

The classes associated with the item.

graphData.data

String

Required

Mutable

The data associated with the element.

graphData.zoomingEnabled

Boolean

Required

Mutable

Specifies whether zooming is enabled for the element.

graphData.userZoomingEnabled

Boolean

Required

Mutable

Specifies whether user zooming is enabled for the element.

graphData.zoom

Number

Required

Mutable

The zoom number.

graphData.minZoom

Number

Optional

Mutable

The minimum zoom number.

graphData.maxZoom

Number

Optional

Mutable

The maximum zoom number.

graphData.panningEnabled

Boolean

Required

Mutable

Specifies whether the element can be moved.

graphData.userPanningEnabled

Boolean

Required

Mutable

Specifies whether the element can be moved by the user.

graphData.pan

Object

Required

Mutable

The panning object.

graphData.pan.x

Number

Required

Mutable

The element’s x-axis position.

graphData.pan.y

Number

Required

Mutable

The element’s y-axis position.

graphData.boxSelectionEnabled

Boolean

Required

Mutable

Specifies whether box selection is enabled.

graphData.renderer

Object

Required

Mutable

The renderer object.

graphData.renderer.name

String

Required

Mutable

The renderer name.

Response codes

Code Message

200

Successful operation.

201

Successfully created.

204

Successfully removed. No content.

400

The request could not be completed.

401

You do not have access to this resource.

403

You do not have permissions or are not licensed to make this request.

404

The requested resource was not found.

DaVinci flow version errors

In addition to the general error codes, DaVinci flow version operations can return the following errors:

HTTP status Top‑level code Detail code When it happens and what the response contains

400

INVALID_DATA

REQUIRED_VALUE, EMPTY_VALUE, INVALID_VALUE, or OUT_OF_RANGE

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A POST /environments/{envID}/flows/{davinciFlowID}/versions or a PUT /environments/{envID}/flows/{davinciFlowID}/versions/{davinciFlowVersionID} request supplies a body that violates the data model: an omitted version on create, a name longer than 256 characters, a blank or null name, a name whose first non-whitespace character is outside the allowed set or that contains a < or a ${ sequence, a trigger that is not an object or that omits type, a trigger.type value other than AUTHENTICATION, or a name, description, color, graphData, inputSchema, outputSchema, settings, skcomponents, or enabled value of the wrong JSON type

Details: One detail per validation error, each with the failing property path as the target. must have required property 'version' with target version when the create request omits version. must not be empty or blank for a blank name. must be string, must be object, must be array, or must be boolean for a property of the wrong JSON type, for example must be string for a null name. must NOT have more than 256 characters for a name longer than 256 characters. must match pattern "<pattern>", where the pattern is the JSON schema pattern for the property, for a name whose first non-whitespace character is outside the allowed set or that contains a < or a ${ sequence. must be object for a trigger that is not an object. must have required property 'type' with target trigger when trigger omits type. must be one of the values: AUTHENTICATION with target trigger.type for an unknown or unsupported trigger.type value.

400

INVALID_DATA

REQUIRED_VALUE, EMPTY_VALUE, INVALID_VALUE, or OUT_OF_RANGE

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A PUT /environments/{envID}/flows/{davinciFlowID}/versions/{davinciFlowVersionID}/alias request supplies a body that violates the data model: an omitted alias, a blank alias, an alias longer than 256 characters, an alias that starts with a whitespace or unsupported character or that contains a < or a ${ sequence, or an alias value that is not a string

Details: One detail per validation error, each with the failing property path as the target. must have required property 'alias' with target alias when the request omits alias. must not be empty or blank for a blank alias. must be string for an alias that is not a string. must NOT have more than 256 characters for an alias longer than 256 characters. must match pattern "<pattern>", where the pattern is the JSON schema pattern for the property, for an alias that starts with a whitespace or unsupported character or that contains a < or a ${ sequence.

400

INVALID_DATA

INVALID_VALUE

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A request to a flow version endpoint other than the create POST supplies a versionId path parameter that the service cannot parse as a version number, for example a value that is not a number or a <flowId>-<version> value whose flow ID does not match the flow ID in the request path

Details: must be a number for a versionId value that is not a number, or Flow ID in the version ID does not match the flow ID in the request path when the flow ID embedded in the versionId value does not match the flowId path parameter. The target is versionId, or version when the request body includes a version property.

400

INVALID_DATA

INVALID_VALUE

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A POST export request supplies includeSubFlows, includeVariableValues, or includeForms with a value that is not a boolean, a POST revert request includes a request body property, or a DELETE request includes a query parameter

Details: must be boolean with the property name as the target for an export property that is not a boolean, or must NOT have additional properties with the rejected body property or query parameter as the target.

400

INVALID_DATA

INVALID_PARAMETER

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A GET all flow versions request or a GET one flow version request includes any query parameter, or a GET flow version details request includes an expand value other than skcomponents or a query parameter other than expand

Details: must NOT have additional properties with the rejected query parameter as the target, or must be one of the values: skcomponents with target expand for an unsupported expand value.

400

REQUEST_FAILED

CONSTRAINT_VIOLATION

Message: The request could not be completed. There was an issue processing the request.

When and details

When: A POST create or PUT update request specifies a version number that is less than zero

Details: Flow version should be zero or greater than zero. The target is version on create and versionId on update.

400

REQUEST_FAILED

CONSTRAINT_VIOLATION

Message: The request could not be completed. There was an issue processing the request.

When and details

When: A POST create request specifies a version number that already exists for the flow

Details: Flow version already exists. The target is version.

400

REQUEST_FAILED

CONSTRAINT_VIOLATION

Message: The request could not be completed. There was an issue processing the request.

When and details

When: A DELETE request targets the flow’s current version

Details: Can not delete current flow version. No target is returned.

400

REQUEST_FAILED

ITEM_LIMIT_EXCEEDED

Message: The request could not be completed. There was an issue processing the request.

When and details

When: A POST create, PUT update, or POST revert request creates a new flow version after the flow has reached the maximum number of flow versions allowed and the service cannot free an existing version

Details: Flow version limit is exceeded. No target is returned.

403

ACCESS_FAILED

None

Message: The request could not be completed. You do not have access to this resource.

When and details

When: The actor lacks the davinci:read:flowVersions permission (GET operations), the davinci:update:flowVersions permission (the create POST, the update PUT, or the alias PUT), the davinci:delete:flowVersions permission (DELETE), the davinci:export:flowVersions permission (the export POST), or the davinci:revert:flowVersions permission (the revert POST)

Details: None

404

NOT_FOUND

None

Message: The request could not be completed. The requested resource was not found.

When and details

When: Any operation references a DaVinci flow ID that does not exist in the environment, or a GET one, GET details, update PUT, alias PUT, DELETE, revert, or export request references a flow version that does not exist for the flow

Details: None

415

INVALID_REQUEST

None

Message:

The server is refusing to service the request because the entity of the request is in a format not supported by the requested resource for the requested method.
When and details

When: A POST /environments/{envID}/flows/{davinciFlowID}/versions/{davinciFlowVersionID} request uses a Content-Type header value other than application/vnd.pingidentity.flowversion.revert+json or application/vnd.pingidentity.flowversion.export+json, or omits the header

Details: None

500

UNEXPECTED_ERROR

None

Message: There was an unexpected error with the service. Please try again later.

When and details

When: The service encounters an unexpected internal failure while processing the request, for example a revert that cannot create the new flow version

Details: None