Canvases

Get Canvas

GET /api/canvases/<canvas_id>/

URL params

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

Successful status: 200 OK

Return the Canvas object.

Example:

JSON

{
    "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"
            }
        ]
    }
}

Failed status: 404 NOT_FOUND

Get Canvas Available Fields

GET /api/canvases/<canvas_id>/available_fields/

Return list of available fields for the current canvas.

URL params

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

Successful status: 200 OK

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

Example:

JSON

[
    {
        "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
    }
]

Failed status: 404 NOT_FOUND

Get Canvas Available Fields (per Node)

Given a node id, this endpoint 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).

GET /api/canvases/<canvas_id>/nodes/<node_id>/available_fields/

URL params

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

Successful status: 200 OK

A list of available fields' string value.

Example:

JSON

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

Failed status: 400 BAD_REQUEST

If the given node_id does not exist within the graph.

Example:

JSON

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

Export DiaManT XML files

Given a canvas id, this endpoint generates the xml files a DiaManTⓇ application needs to run.

GET /api/canvases/<canvas_id>/export/

URL params

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

Successful status: 200 OK

The 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

Failed status: 400 BAD_REQUEST

When something goes wrong with the export (usually there is a warning pending).

Example:

JSON

{
    "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

A PUT request to update the root canvas of an application. This request also applies validations regarding the graph.

PUT /api/canvases/<canvas_id>/

URL params

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

Request payload

A Canvas object.

Example:

JSON

{
    "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"
            }
        ]
    }
}

Successful status: 201 CREATED

The updated Canvas object.

Example:

JSON

{
    "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"
            }
        ]
    }
}

Failed status: 400 BAD_REQUEST

a required field is missing

Example:

JSON

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

duplicate node_id inside the graph.nodes

Example:

JSON

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

cycles are detected on the graph

Example:

JSON

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

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

Example:

JSON

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

Warnings

There are cases where the response includes an error field indicating some warnings to be showed to the user:

multiple root nodes have been detected on the graph

Example:

JSON

{
  [...]
  "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 for the root canvas but also for the error handlers (in case of an Application).

Example:

JSON

{
  [...]
  "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:

JSON

{
  [...]
  "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:

JSON

{
  [...]
  "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:

JSON

{
  [...]
  "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:

JSON

{
  [...]
  "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:

JSON

{
  [...]
  "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:

JSON

{
  [...]
  "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:

JSON

{
  [...]
  "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:

JSON

{
  [...],
  "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:

JSON

{
  [...],
  "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",
                      }
                  }
              ]
          }
      ]
  }
}