Canvases | OCP® Learning Center

Get Canvas

GET	{{baseUrl}}/orchestrator/api/canvases/<canvas_id>/	Gets the canvas by uuid.

Click to see the details

URL Parameters

Name	Description	Example
`canvas_id`	The canvas uuid.	'930157b3-671c-4a81-a5d5-315fa63c6172'

Response (Success)

HTTP/1.1 200 OK

Returns the Canvas object.

Example

{
    "content": {
        "nodes": [
            {
                "title": "ia_iandronis_announcement",
                "node_id": "758d7ab6-5eba-47e7-8d29-749fb79bf346",
                "component_id": "827aa8e8-351c-4622-9e11-722d38efdcfe.ia_iandronis_announcement.Announcement.MiniApps.iandronis",
                "configuration": {
                    "reset_on_intent": false,
                    "input_fields": {},
                    "output_fields": [
                        {
                            "miniapp_name": "AnnouncementResult",
                            "local_name": "ia_iandronis_announcement_0_output",
                            "optional": false,
                            "locked": true
                        }
                    ],
                    "referents": []
                },
                "x_value": 83.0,
                "y_value": 86.0,
                "type": "miniApp",
                "miniapp_type": "Announcement"
            },
            {
                "title": "ia_iandronis_intent",
                "node_id": "98668bc3-f857-44f1-943e-99281a5d55d5",
                "component_id": "827aa8e8-351c-4622-9e11-722d38efdcfe.ia_iandronis_intent.Banking.MiniApps.iandronis",
                "configuration": {
                    "reset_on_intent": false,
                    "input_fields": {},
                    "output_fields": [
                        {
                            "miniapp_name": "Intent",
                            "local_name": "Intent",
                            "optional": false,
                            "locked": true
                        }
                    ],
                    "referents": []
                },
                "x_value": 201.0,
                "y_value": 265.0,
                "type": "miniApp",
                "miniapp_type": "Banking"
            }
        ],
        "edges": [
            {
                "id": "3221acbe-9d52-472f-a144-1fe8784d98d7",
                "source": "758d7ab6-5eba-47e7-8d29-749fb79bf346",
                "target": "98668bc3-f857-44f1-943e-99281a5d55d5",
                "conditions": [],
                "condition_operator": "AND",
                "port": "out"
            }
        ]
    }
}

Response (Failed)

HTTP/1.1 404 NOT_FOUND

Get Canvas Available Fields

GET	{{baseUrl}}/orchestrator/api/canvases/<canvas_id>/available_fields/	Returns the list of available fields for the current canvas.

Click to see the details

URL Parameters

Name	Description	Example
`canvas_id`	The canvas uuid.	'930157b3-671c-4a81-a5d5-315fa63c6172'

Response (Success)

HTTP/1.1 200 OK

Example

[
    {
        "name": "Ani",
        "readonly": false
    },
    {
        "name": "Dnis",
        "readonly": true
    },
    {
        "name": "Locale",
        "readonly": false
    },
    {
        "name": "SessionChannel",
        "readonly": true
    },
    {
        "name": "ia_iandronis2_announcement-0-output",
        "readonly": false
    },
    {
        "name": "FailSource",
        "readonly": true
    },
    {
        "name": "FailExitReason",
        "readonly": false
    }
]

Parameter	Type	Description
`name`	string	The field's name.
`readonly`	boolean	Reproduced if field is read_only.

Response (Failed)

HTTP/1.1 404 NOT_FOUND

Get Canvas Available Fields (per Node)

GET	{{baseUrl}}/orchestrator/api/canvases/<canvas_id>/nodes/<node_id>/available_fields/	Given a `node id`, returns all available fields at this point. It sums up all the output fields from the node's parents and return a list of them.

In case when miniApp is followed by conditional node, the additional LastFailReason field is returned as available conditional field. This field handles the errors produced by miniApp, allowing the application flow to continue.

Keep in mind that the response will also include some constant build-in variables that are always available from the DiaManTⓇ (for example, Ani, Dnis).

Click to see the details

URL Parameters

Name	Description	Example
`canvas_id`	The canvas uuid.	'930157b3-671c-4a81-a5d5-315fa63c6172'
`node_id`	The node uuid.	'930157b3-671c-4a81-a5d5-315fa63c6172'

Response (Success)

HTTP/1.1 200 OK

Returns the list of available fields' string value.

Example

[
    "output1",
    "output2",
    "Ani",
    "Dnis"
]

Response (Failed)

HTTP/1.1 400 BAD_REQUEST

The failed status is returned if the given node_id does not exist within the graph.

Example

{
    "detail": "The given node_id (030157b3-671c-4a81-a5d5-315fa63c6172) does not exist."
}

Export DiaManT XML files

GET	{{baseUrl}}/orchestrator/api/canvases/<canvas_id>/export/	Given a `canvas id`, generates XML files that a DiaManTⓇ application needs to run.

Click to see the details

URL Parameters

Name	Description	Example
`canvas_id`	The canvas uuid.	'930157b3-671c-4a81-a5d5-315fa63c6172'

Response (Success)

HTTP/1.1 200 OK

This endpoint returns a ZIP file with the name {app_name}.zip. The ZIP file contains:

ApplicationOptions.xml
DialogTargetsList.xml
DiaManT_App_Config.xml
DiaManT_Audio_Config.xml
DiaManT_Logging_Config.xml
DiaManT_Scoring_Config.xml
DiaManT_System_Config.xml
FieldList.xml
SubDialogs.xml
EventTrackers.xml

Response (Failed)

HTTP/1.1 400 BAD_REQUEST

The failed status is returned if something goes wrong with the export (usually there is a warning pending).

Example

{
    "detail": "Your App can not be deployed because it contains problems: Multiple roots found on the graph. Please connect or remove disconnected components."
}

Update Canvas

PUT	{{baseUrl}}/orchestrator/api/canvases/<canvas_id>/	Updates the root canvas of an application. Also, applies validations regarding the graph.

Click to see the details

URL Parameters

Name	Description	Example
`canvas_id`	The canvas uuid.	'930157b3-671c-4a81-a5d5-315fa63c6172'

Request payload

A Canvas object.

Example

{
    "content": {
        "nodes": [
            {
                "title": "ia_iandronis_announcement",
                "node_id": "758d7ab6-5eba-47e7-8d29-749fb79bf346",
                "component_id": "827aa8e8-351c-4622-9e11-722d38efdcfe.ia_iandronis_announcement.Announcement.MiniApps.iandronis",
                "configuration": {
                    "reset_on_intent": false,
                    "input_fields": {},
                    "output_fields": [
                        {
                            "miniapp_name": "AnnouncementResult",
                            "local_name": "ia_iandronis_announcement_0_output",
                            "optional": false,
                            "locked": true
                        }
                    ],
                    "referents": []
                },
                "x_value": 83.0,
                "y_value": 86.0,
                "type": "miniApp",
                "miniapp_type": "Announcement"
            },
            {
                "title": "ia_iandronis_intent",
                "node_id": "98668bc3-f857-44f1-943e-99281a5d55d5",
                "component_id": "827aa8e8-351c-4622-9e11-722d38efdcfe.ia_iandronis_intent.Banking.MiniApps.iandronis",
                "configuration": {
                    "reset_on_intent": false,
                    "input_fields": {},
                    "output_fields": [
                        {
                            "miniapp_name": "Intent",
                            "local_name": "Intent",
                            "optional": false,
                            "locked": true
                        }
                    ],
                    "referents": []
                },
                "x_value": 201.0,
                "y_value": 265.0,
                "type": "miniApp",
                "miniapp_type": "Banking"
            }
        ],
        "edges": [
            {
                "id": "3221acbe-9d52-472f-a144-1fe8784d98d7",
                "source": "758d7ab6-5eba-47e7-8d29-749fb79bf346",
                "target": "98668bc3-f857-44f1-943e-99281a5d55d5",
                "conditions": [],
                "condition_operator": "AND",
                "port": "out"
            }
        ]
    }
}

Response (Success)

HTTP/1.1 200 OK

Returns the updated Canvas object.

Example

{
    "content": {
        "nodes": [
            {
                "title": "ia_iandronis_announcement",
                "node_id": "758d7ab6-5eba-47e7-8d29-749fb79bf346",
                "component_id": "827aa8e8-351c-4622-9e11-722d38efdcfe.ia_iandronis_announcement.Announcement.MiniApps.iandronis",
                "configuration": {
                    "reset_on_intent": false,
                    "input_fields": {},
                    "output_fields": [
                        {
                            "miniapp_name": "AnnouncementResult",
                            "local_name": "ia_iandronis_announcement_0_output",
                            "optional": false,
                            "locked": true
                        }
                    ],
                    "referents": []
                },
                "x_value": 83.0,
                "y_value": 86.0,
                "type": "miniApp",
                "miniapp_type": "Announcement"
            },
            {
                "title": "ia_iandronis_intent",
                "node_id": "98668bc3-f857-44f1-943e-99281a5d55d5",
                "component_id": "827aa8e8-351c-4622-9e11-722d38efdcfe.ia_iandronis_intent.Banking.MiniApps.iandronis",
                "configuration": {
                    "reset_on_intent": false,
                    "input_fields": {},
                    "output_fields": [
                        {
                            "miniapp_name": "Intent",
                            "local_name": "Intent",
                            "optional": false,
                            "locked": true
                        }
                    ],
                    "referents": []
                },
                "x_value": 201.0,
                "y_value": 265.0,
                "type": "miniApp",
                "miniapp_type": "Banking"
            }
        ],
        "edges": [
            {
                "id": "3221acbe-9d52-472f-a144-1fe8784d98d7",
                "source": "758d7ab6-5eba-47e7-8d29-749fb79bf346",
                "target": "98668bc3-f857-44f1-943e-99281a5d55d5",
                "conditions": [],
                "condition_operator": "AND",
                "port": "out"
            }
        ]
    }
}

Response (Failed)

HTTP/1.1 400 BAD_REQUEST

The failed status is returned if:

a required field is missing

Example

{
    "content": {
        "nodes": [
            {
                "node_id": [
                    "This field is required."
                ]
            },
            {}
        ],
        "edges": [
            {
                "source": [
                    "This field is required."
                ]
            }
        ]
    }
}

there’s a duplicate node_id inside the graph.nodes

Example

{
    "detail": "Multiple nodes with the same node id have been detected. Duplicate ids: ['2', '1']."
}

cycles are detected on the graph

Example

{
    "detail": "Found cycles on the graph"
}

the number of edges from a node exceeds the maximum allowed one

Example

{
    "detail": "The following nodes contain more children than it is allowed. Violations: [('2', 1, 0)]"
}

Warnings

Click to see the details

There may be cases where the response includes an error field indicating some warnings to be showed to the user. These warnings can be the following:

multiple root nodes have been detected on the graph

Example

{
  [...]
  "errors": {
    "node_errors": [
      {
        "node_id": "505981d1-a61b-466b-9fb6-560d2f60f9fd",
        "errors": [
          {
            "type": "WARNING",
            "code": "MULTIPLE_ROOTS_FOUND",
            "message": "Multiple roots found on the graph. Please connect or remove disconnected components."
          }
        ]
      },
      {
        "node_id": "00f4ae02-3c01-476b-8733-ba3d8600e09c",
        "errors": [
          {
            "type": "WARNING",
            "code": "MULTIPLE_ROOTS_FOUND",
            "message": "Multiple roots found on the graph. Please connect or remove disconnected components."
          }
        ]
      }
    ]
  }
}

found a node component in the canvas, which belongs to a different group than its root's (Application or Flow). This applies to the root canvas but also to error handlers (in case of an Application).

Example

{
  [...]
  "errors": {
    "node_errors": [
      {
        "node_id": "ac5d325c-1326-4cec-9e84-07fc38924132",
        "errors": [
          {
            "type": "WARNING",
            "code": "INVALID_GROUP",
            "message": "Component found on the graph with invalid group.",
            "groups": {
              "graph": "orc",
              "component": "iandronis"
            }
          }
        ]
      }
    ]
  }
}

there are some invalid condition fields. In other words, under a condition, there is a field declared, which is not included in the available fields.

Example

{
  [...]
  "errors": {
    "node_errors": [
      {
        "node_id": "bc1d36c1-ac06-485e-93f9-22c7263c29c1",
        "errors": [
          {
            "type": "WARNING",
            "code": "UNKNOWN_FIELD_REFERENCED",
            "message": "Unknown field is referenced at node configuration.",
            "field": {
              "field_type": "input",
              "name": "ia_orc_announcement_0_output"
            }
          }
        ]
      }
    ]
  }
}

there is a condition block being used, which has more than one default condition edge (where default is an edge with empty condition criteria)

Example

{
  [...]
  "errors": {
    "node_errors": [
      {
        "node_id": "bc1d36c1-ac06-485e-93f9-22c7263c29c1",
        "errors": [
          {
            "type": "WARNING",
            "code": "MAXIMUM_NO_CONDITION_EDGE_COUNTER",
            "message": "More than one default condition edge have been found."
          }
        ]
      }
    ]
  }
}

there is an Intelli or a WebService miniApp that has been configured without any output field

Example

{
  [...]
  "errors": {
    "node_errors": [
      {
        "node_id": "bc1d36c1-ac06-485e-93f9-22c7263c29c1",
        "errors": [
          {
            "type": "WARNING",
            "code": "NONE_MINIAPP_OUTPUT_FIELDS",
            "message": "No output fields have been found. Please declare at least one output field."
          }
        ]
      }
    ]
  }
}

there is a SetField node with empty configuration values

Example

{
  [...]
  "errors": {
    "node_errors": [
      {
        "node_id": "bc1d36c1-ac06-485e-93f9-22c7263c29c1",
        "errors": [
          {
            "type": "WARNING",
            "code": "EMPTY_SETFIELD_CONFIG",
            "message": "SetField node found with empty configuration. Please add at least one field to change."
          }
        ]
      }
    ]
  }
}

"Anything else?" block is used in Flow, but Flow doesn't contain Intent miniApp, and Intent is not set as input and output

Example 1

{
  [...]
  "errors": {
    "node_errors": [
      {
        "node_id": "bc1d36c1-ac06-485e-93f9-22c7263c29c1",
        "errors": [
          {
            "type": "WARNING",
            "code": "FLOW_INPUTS_INTENT_MISCONFIGURATION"
            "message": "Intent is not used in this Flow and not configured as this Flow's input. To use \"Anything else?\" block in this Flow you need to have Intent as Flow input field."
          }
        ]
      }
    ]
  }
}

Example 2

{
  [...]
  "errors": {
    "node_errors": [
      {
        "node_id": "bc1d36c1-ac06-485e-93f9-22c7263c29c1",
        "errors": [
          {
            "type": "WARNING",
            "code": "FLOW_OUTPUTS_INTENT_MISCONFIGURATION"
            "message": "Intent is not used in this Flow and not configured as this Flow's output. To use \"Anything else?\" block in this Flow you need to have Intent as Flow output field."
          }
        ]
      }
    ]
  }
}

"Anything else?" block is the only block in Flow

Example

{
  [...]
  "errors": {
    "node_errors": [
      {
        "node_id": "bc1d36c1-ac06-485e-93f9-22c7263c29c1",
        "errors": [
          {
            "type": "WARNING",
            "code": "ORPHANED_REASK_NODE"
            "message": "\"Anything else?\" block can not be the only block of the Flow graph. You must have at least one more preceding (not conditional) block to use it."
          }
        ]
      }
    ]
  }
}

property field has been used by a no-miniApp Node

Example

{
  [...],
  "errors": {
      "node_errors": [
          {
              "node_id": "9909fe1c-416a-47d0-9294-b708fcadddfb",
              "errors": [
                  {
                      "type": "WARNING",
                      "code": "INVALID_PROPERTY_USE",
                      "message": "Properties can only be used by miniApp Nodes."
                  }
              ]
          }
      ]
  }
}

property field has an invalid value (the property is not a valid one or its value is an empty string)

Example

{
  [...],
  "errors": {
      "node_errors": [
          {
              "node_id": "9909fe1c-416a-47d0-9294-b708fcadddfb",
              "errors": [
                  {
                      "type": "WARNING",
                      "code": "INVALID_PROPERTY_VALUE",
                      "message": "Invalid property value has been detected.",
                      "field": {
                        "field_type": "miniApp property",
                        "name": "fantastic_property",
                      }
                  }
              ]
          }
      ]
  }
}