Navigation :

Flows

The flow endpoint provides access to OCNCC ACS Control Plans in a JSON based format.

GET /api/flow/:flow_id

Retrieve details for a specific flow. Access to the flow ID is restricted based on the authenticated user.

This request supports the following parameters:

Parameter	Example	Description
`flow_id`	`12311`	[URL parameter], [Required] The ID of the flow to retrieve. This must always be a non-negative integer.
`fields`	`content`	[URL parameter], [Optional] The list of fields to include which would normally be excluded. The only valid value for this parameters at this stage is `content`. When included, `fields=content` will trigger the inclusion of the JSON flow definition. As this is is a costly operation, including the JSON content is not enabled by default.

Response Content

The response will be a single JSON hash with the following hash keys:

Key	Type	Description
`change_user`	String	The name of the last user to change the flow.
`change_date`	Date	The date at which the flow was last changed. The date will be provided as a string in ISO 8601 format.
`content`	Object	The flow, as a hash of `node_id -> node_details`. For details of node details see the N2FE Operation. This is included only if `fields=content` is added to the request arguments.
`customer_id`	Integer	The unique ID of the OCNCC customer that owns this flow.
`customer_name`	String	The name of the customer that owns this flow.
`id`	Integer	the unique ID of this flow.
`name`	String	The name given to the flow by the user.
`version`	Integer	The version of the flow as stored in the OCNCC database. Each time a flow is saved it will receive a new version number.

Examples

Request:

curl 'http://localhost/jarvis-agent/n2fe/api/flow/189351?customerId=50200' -H 'Cookie: N2FE_CGISESSID=48ac880f98504e81373207d62dd2f807'

Response:

{
  "change_date" : "2020-06-09T23:28:08Z",
  "change_user" : "Hannah",
  "customer_id" : "74969",
  "customer_name" : "N-Squared Software Ltd.",
  "id" : "189351",
  "is_active" : "0",
  "is_active_in_future" : "0",
  "is_alternative_call_plan" : "0",
  "name" : "Business Hours",
  "status" : "S",
  "structure_id" : "286707",
  "version" : "9"
}

Request:

curl 'http://localhost/jarvis-agent/n2fe/api/flow/189351?customerId=50200&fields=content' -H 'Cookie: N2FE_CGISESSID=48ac880f98504e81373207d62dd2f807'

Response:

{
   "change_user" : "Hannah",
   "structure_id" : "286707",
   "change_date" : "2020-06-09T23:28:08Z",
   "customer_id" : "50200",
   "version" : "9",
   "is_active_in_future" : "0",
   "status" : "S",
   "is_active" : "0",
   "name" : "Test Flow",
   "is_alternative_call_plan" : "0",
   "operations" : {
      "4" : {
         "base_node" : "4",
         "config" : {},
         "name" : "Start",
         "exits" : [
            3
         ],
         "notes" : [],
         "type" : "Start",
         "id" : "4"
      },
      "1" : {
         "config" : {
            "cause" : "31"
         },
         "base_node" : "1",
         "exits" : [],
         "name" : "End Call",
         "notes" : [],
         "id" : "1",
         "type" : "ReleaseCall"
      },
      "3" : {
         "base_node" : "3",
         "config" : {
            "exit_idx" : 0
         },
         "name" : "Switch",
         "exits" : [
            2,
            null
         ],
         "notes" : [],
         "type" : "Switch",
         "id" : "3"
      },
      "2" : {
         "id" : "2",
         "type" : "Switch",
         "notes" : [],
         "exits" : [
            1,
            null
         ],
         "name" : "Switch",
         "config" : {
            "exit_idx" : 1
         },
         "base_node" : "2"
      }
   },
   "id" : "189351",
   "customer_name" : "N-Squared"
}

GET /api/customer/:customer_id/flow

Retrieve a list of flows available to the customer with the ID given in the URL. As flows are intrinsically tied to customers, a flow list is only available by customer in this version of the application.

Using the dedup flag to return one flow record per flow name (i.e. the latest flow version only). By not including the dedup flag, all active flows will be returned.

Active flows are ones that:

Are either the latest version of a flow, orj
are not the latest version of a flow, but have a defined MF identifier,
are not the latest version of a flow, but is scheduled, and the schedule is either active now, or in the future.

This request supports the following parameters:

Parameter	Example	Description
`customer_id`	`74969`	[URL parameter], [Required] The ID of the customer whose list of flows should be retrieved. This must always be a non-negative integer.
`name`	`busin`	A substring to match against flow names. All flows that can partially match against this string will be returned (subject to other criteria). This match is case insensitive.
`fields`	`content`	The list of fields to include which would normally be excluded. The only valid value for this parameters at this stage is `content`. When included, `fields=content` will trigger the inclusion of the JSON flow definition. As this is is a costly operation, including the JSON content is not enabled by default and should be done rarely when retrieving all customer flows.
`includeAlternative`	`1`	Include this flag to include alternative flows in the list returned. Alternative flows are special flows that cannot be directly scheduled, but rather are used by the service logic when "alternative flows" are enabled at the customer level. Do not include this parameter, or set this parameter to a value other than 1 to exclude alternative flows.
`dedup`	`1`	Include this flag to deduplicate the response and include only one row per flow - suppressing the normal multi-version response details. Do not include this parameter, or set this parameter to a value other than 1 to include all active versions of a flow.

Response Content

The response will be a JSON array, the latest version of each flow the customer has stored against their account.

Each array object will respond with the same details as provided with the api/flow/:flow_id API endpoint.

Example

Request:

curl 'http://localhost/jarvis-agent/n2fe/api/customer/74969/flow' -H 'Cookie: N2FE_CGISESSID=48ac880f98504e81373207d62dd2f807'

Response:

[
    {
      "change_date" : "2020-06-09T23:28:08Z",
      "change_user" : "Hannah",
      "customer_id" : "74969",
      "customer_name" : "N-Squared Software Ltd.",
      "id" : "292164",
      "is_active" : "0",
      "is_active_in_future" : "0",
      "is_alternative_call_plan" : "0",
      "name" : "Business Hours",
      "status" : "S",
      "structure_id" : "286707",
      "version" : "9"
   }
]

POST /api/flow

Flows are never updated. Saving a flow always creates a new version of the flow in the database. When saving a flow, the server will validate the flow JSON before saving to the OCNCC database.

On saving to the OCNCC database, OCNCC will compile the flow into an internal representation. This build may fail, however this failure will not be reported back to the client in the PUT response as the build occurs out-of-band.

This request requires no URL parameters. All information must be provided in the PUT body as a JSON document. The body JSON must consist of a single JSON hash with the following keys:

Key	Type	Description
`name`	String	The name to give the flow being saved.
`customer_id`	Integer	The ID of the customer who will own the flow.
`flowJson`	Object	A flow, conforming to the syntax and semantics defined by the N2FE Operation guide.

Examples

Content of flow.json:

{
  "name":"0800NSQUARED",
  "customer_id":"74969",
  "flowJson":{
    "1":{
      "exits":[

      ],
      "id":"1",
      "base_node":"4",
      "type":"AttemptTerminate",
      "config":{
        "destinations":[
          {
            "address":"6421555555",
            "timeout_seconds":60
          }
        ]
      },
      "exitNames":[
        {
          "name":"Busy/No Answer"
        }
      ]
    },
    "2":{
      "id":"2",
      "base_node":"1",
      "type":"Start",
      "exits":[
        1
      ],
      "exitNames":[
        {
          "name":""
        }
      ]
    }
  }
}

Request:

curl 'http://localhost/jarvis-agent/n2fe/api/flow/221389' -H 'Content-Type: application/json;charset=utf-8' -T flow.json -H 'Cookie: N2FE_CGISESSID=48ac880f98504e81373207d62dd2f807'

Success Response

On success the system will return the following information structure in JSON, and in particular the new flow ID in the field returning[0].plan_id.

Response:

{
   "returning" : [
      {
         "plan_id" : "222603",
         "structure_id" : "217576"
      }
   ],
   "logged_in" : "1",
   "group_list" : "ACS_BOSS,CCS Superuser",
   "username" : "su",
   "error_string" : "",
   "modified" : 1,
   "success" : 1
}

Error Response

A flow update may fail. On failure the field success will be set to 0 and either the response will be provided in this format:

Response:

{
   "username" : "su",
   "logged_in" : "1",
   "group_list" : "ACS_BOSS,CCS Superuser",
   "message" : "[Fri May 18 14:02:02 2018] An error has occurred. Please contact Support and provide this error code: [8f89301b-537a-060b-af9c-376e9d940c0a].",
   "success" : 0,
   "error_string" : ""
}

or on a validation failure, the response will be provided as a single string:

[Node-1] No destination number defined at position 1.

In both cases the response is provided with a 500 Internal Server Error response.