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