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	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.
is_scheduled	Boolean	Privided as an integer, 1 if the flow is scheduled against a service number. 0 otherwise. The flow may not be active even if this is 1 as the flow may be supersceeded by another scheduled 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/211262' -H 'Cookie: N2FE_CGISESSID=48ac880f98504e81373207d62dd2f807'

Response:

{
   "version" : "1",
   "name" : "0800677828",
   "change_user" : "SMF",
   "is_scheduled" : "1",
   "customer_id" : "67009",
   "change_date" : "2016-05-05T05:04:50Z",
   "customer_name" : "N-Squared Software",
   "id" : "211262"
}

Request:

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

Response:

{
    "content" : {
      "1" : {
         "exits" : [
            null
         ],
         "type" : "AttemptTerminate",
         "base_node" : "4",
         "config" : {
            "destinations" : [
               {
                  "timeout_seconds" : 15,
                  "address" : "6463581140"
               }
            ]
         },
         "id" : "1"
      },
      "2" : {
         "type" : "Start",
         "base_node" : "1",
         "id" : "2",
         "exits" : [
            1
         ]
      }
   },
   "version" : "1",
   "name" : "0800677828",
   "change_user" : "SMF",
   "is_scheduled" : "1",
   "customer_id" : "67009",
   "change_date" : "2016-05-05T05:04:50Z",
   "customer_name" : "N-Squared Software",
   "id" : "211262"
}

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.

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.
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.

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" : "2016-05-05T13:43:36Z",
      "id" : "221389",
      "change_user" : "SMF",
      "version" : "1",
      "name" : "08005551235",
      "customer_id" : "74969",
      "customer_name" : "Bob's Buildings",
      "is_scheduled" : "1"
   },
   {
      "customer_id" : "74969",
      "name" : "08005551234",
      "is_scheduled" : "1",
      "customer_name" : "1Bob's Buildings",
      "change_user" : "SMF",
      "version" : "1",
      "change_date" : "2016-05-05T13:43:33Z",
      "id" : "221388"
   }
]

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" : "ORA-01400: cannot insert NULL into (\"ACS_ADMIN\".\"ACS_CALL_PLAN_STRUCTURE\".\"NAME\") (DBD ERROR: error possibly near <*> indicator at char 126 in 'INSERT INTO\n            acs_call_plan_structure (name, version, loops_allowed, customer, build)\n        VALUES (\n            :<*>p1,\n            (SELECT NVL (m, 1) FROM (SELECT MAX (version) + 1 m FROM acs_call_plan_structure WHERE RTRIM (name) = :p2)),\n            1,\n            :p3,\n            'B')\n        RETURNING id INTO :p4')",
   "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. at /home/jlove/Code/official/n2fe.hg/lib/N2/ControlPlan.pm line 1048.

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