Provisioning¶

Administrators¶

The CSV files to be imported for any administrator account should have the following format:

username

A unique string that is the user name for this user. Limit of 64 characters. Can contain only lowercase characters, numbers, or underscores.

role_id

A string that defines the type of administrator that is being created. Accepted values are:

• platform_owner

• service_provider:<service_provider_name>

• subscriber:<service_provider_name>:<subscriber_name>

first_name (optional)

A string that is the first name of this user. Limit of 250 characters.

last_name (optional)

A string that is the last name of this user. Limit of 250 characters.

email (optional)

A string that is the email address for this user. Limit of 250 characters.

permissions (optional)

An array of permission groups that this user is a member of. Permissions are dependent on the specified role_id of the created administrator.

Service Providers¶

The CSV files to be imported for Service Providers should have the following format:

name

A unique string that is the name of this Service Provider. Limit of 64 characters.

display_name (optional)

An unconstrained string used as a display name. Limit of 250 characters.

first_name (optional)

A string that is the first name of a contact for this Service Provider. Limit of 250 characters.

last_name (optional)

A string that is the last name of a contact for this Service Provider. Limit of 250 characters.

email (optional)

A string that is the email address of this Service Provider, where notifications and password reset requests will be sent. Limit of 250 characters.

address (optional)

A string that is the physical address of this Service Provider. Limit of 250 characters.

phone (optional)

A string that is the primary phone number of this Service Provider. Limit of 250 characters.

Subscribers¶

The CSV files to be imported for Subscribers, should have the following format:

service_provider_name

A unique string that is the name of the Service Provider for this Subscriber. Must match an existing Service Provider.

name

A unique string that is the name of this Subscriber. Limit of 64 characters.

display_name (optional)

An unconstrained string used as a display name. Limit of 250 characters.

address (optional)

A string that is the physical address of this Subscriber. Limit of 250 characters.

first_name (optional)

A string that is the first name of a contact for this Subscriber. Limit of 250 characters.

last_name (optional)

A string that is the last name of a contact for this Subscriber. Limit of 250 characters.

email (optional)

A string that is the email address of this Subscriber, where notifications and password reset requests will be sent. Limit of 250 characters.

phone (optional)

A string that is the primary phone number of this Subscriber. Limit of 250 characters.

pin

A string that is the PIN used by this Subscriber to log in to the IVR interface.

timezone (optional)

A string that is the time zone used by the Subscriber to determine call forwarding.

default_number (optional)

A string that is the number calls will be forwarded to when no plans are active.

account_lock (optional)

A boolean value that determines whether this Subscriber account is locked after entering an invalid PIN too many times.

call_manager (optional)

A boolean value that determines whether this Subscriber can access additional features such as creating acceptance lists and forwarding schedules.

schedules (optional)

An array of entries that define the forwarding schedule for this Subscriber containing the following parameters:

entries:

start: A string that is the start time for the schedule, in HH:MM.

end: A string that is the end time for the schedule, in HH:MM.

day: A string that are the days of the week this schedule applies to. Accepted values are MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, and SUNDAY.

number: A string that is the number all calls are forwarded to during the time that this schedule is active.

active: A boolean value that determines whether the forwarding schedule is active for this Subscriber.

acceptance_lists (optional)

An array of entries that define the acceptance list for this Subscriber, which are numbers that will always be forwarded regardless of the applied routing rules, containing the following parameters:

entries: An array numbers that are in the caller acceptance list.

active: A boolean value that determines whether the call acceptance list is active for this Subscriber.

speed_call_numbers (optional)

An array of speed call numbers that this Subscriber commonly forwards calls to.

forward_plan (optional)

An array of entries that defines the current forwarding plan for this Subscriber with a new forwarding number and a duration defining how long calls should be forwarded to the specified number.

screening (optional)

A JSON object defining call screening behavior containing the following parameters:

active: A boolean value that determines whether call screening is active for this Subscriber.

pin: A 4-digit string that a caller must dial to be forwarded.

params (optional)

A JSON object of always active routing parameters for this Subscriber.

notes (optional)

A string that is a free-form notes field. Limit of 2048 characters.

Import a CSV file¶

Import Using the Web UI

Whether the database operation to import records from a file is available depends on which page is currently displayed.

1. Click Import on the task bar.

2. Click Choose File to browse for a CSV file to import.

3. Click Start Import.

The file is uploaded and the import begins and runs in the background.

The status of an import can be found on the My Account page under Job Logs.

Import Using the API

To import data with the API, the user sends a POST command to the specific object.

The example below shows a Service Provider importing a Subscriber.

curl -X POST \
 -H "Content-Type:ecf/json" localhost/ecf/api/job/service_provider:ecf_service_provider?executable=restworkx-ecf \
 -H "Authorization:Basic <secure-access-token>" \
 -d '{"job_type":"import","in_file":"/var/opt/xpressworkx/app-manager/ecf/media/upload/subscriber-import.csv","object":"subscriber","service_provider_name":"ecf_service_provider"}'

Which would return a message such as:

"meta": {
        "executable": "restworkx-ecf",
        "code": 200,
        "encoding": "ascii",
        "scope": "success",
        "records_shown": 1,
        "message": "",
        "authorization": "Basic <secure-access-token>"
},
"data": [{
        "scope": "job",
        "meta": {
                "modified_by": "system",
                "txnid": null,
                "modified": "2022-04-07 11:39:44.724128",
                "created_by": "system",
                "created": "2022-04-07 11:39:44.724102"
        },
        "links": {
                "self": {
                        "scope": "job",
                        "identifier": {
                                "job_id": 104,
                                "out_file": "/var/opt/xpressworkx/app-manager/ecf/media/download/subscriber-import-2022-04-07-23770cb05d.csv"
                        },
                        "uri": "/job"
                },
        },
        "attributes": {
                "status": "processing",
                "out_file": "/var/opt/xpressworkx/app-manager/ecf/media/download/subscriber-import-2022-04-07-23770cb05d.csv",
                "pid": null,
                "object": "subscriber",
                "job_type": "import",
                "job_id": 104,
                "elapsed": "0",
                "in_file": "/var/opt/xpressworkx/app-manager/ecf/media/upload/subscriber-import.csv",
                "kwargs": null,
                "progress": null,
                "role_id": "service_provider:ecf_service_provider",
                "output_hash": null
        },
}],
"jsonapi": {
        "version": "2.2-14",
        "name": "Enhanced Call Forwarding",
        "short_name": "ecf",
        "author": "IMSWorkX, Inc."
}

Export a CSV file¶

Export Using the Web UI

Whether the database operation to export records to a file is available depends on which page is currently displayed.

1. Click Export on the task bar.

2. Click Start Export.

The output CSV file can be found on the My Account page under Job Logs.

Export Using the API

To export data with the API, the user sends a POST command to the specific object.

The example below shows a Platform Owner exporting Service Providers.

curl -X POST \
 -H "Content-Type:ecf/json" localhost/ecf/api/job/platform_owner?executable=restworkx-ecf \
 -H "Authorization:Basic <secure-access-token>" \
 -d '{"job_type": "export","object": "service_provider"}'

Which would return a message such as:

"meta": {
        "executable": "restworkx-ecf",
        "code": 200,
        "encoding": "ascii",
        "scope": "success",
        "records_shown": 1,
        "message": "",
        "authorization": "Basic <secure-access-token>"
},
"data": [{
        "scope": "job",
        "meta": {
                "modified_by": "system",
                "txnid": null,
                "modified": "2022-04-07 13:50:20.834266",
                "created_by": "system",
                "created": "2022-04-07 13:50:20.834246"
        },
        "links": {
                "self": {
                        "scope": "job",
                        "identifier": {
                                "job_id": 109,
                                "out_file": "/var/opt/xpressworkx/app-manager/ecf/media/download/service_provider-export-2022-04-07-e996a4f9dc.csv"
                        },
                        "uri": "/job"
                },
        },
        "attributes": {
                "status": "processing",
                "out_file": "/var/opt/xpressworkx/app-manager/ecf/media/download/service_provider-export-2022-04-07-e996a4f9dc.csv",
                "pid": null,
                "object": "service_provider",
                "job_type": "export",
                "job_id": 109,
                "elapsed": "0",
                "in_file": null,
                "kwargs": null,
                "progress": null,
                "role_id": "platform_owner",
                "output_hash": null
        },
}],
"jsonapi": {
        "version": "2.2-14",
        "name": "Enhanced Call Forwarding",
        "short_name": "ecf",
        "author": "IMSWorkX, Inc."
}

Call Detail Records¶

The CSV files exported for Call Detail Records (CDRs) will have the following format.

called_number

The number to which this specific call is routed.

subscriber_name

A unique string that is the name of the Subscriber using this service. Must match an existing Subscriber.

cdrs

An array that is all of the events for this specific call.

start_time

A timestamp indicating the date and time this specific call started.

calling_number

The number making this specific call.

end_time

A timestamp indicating the date and time this specific call ended.

original_called_number

The number that was dialed to start this call.

route

A JSON object that is the route event of the CDR. If blank, this CDR was ended without a route being returned.

service_provider_name

A unique string that is the name of the Service Provider for this Subscriber using this service. Must match an existing Service Provider.

Archiving¶

Data that is not currently in use by the ECF application can be removed from the live database by archiving the data. Provisioned data can be archived in the web UI or through the API.

Archive a Single Object Using the Web UI

1. Navigate to the object that you want to archive.

2. Right-click on the object to be archived.

3. Click Archive.

The object will be moved to the archive database.

Archive Multiple Objects Using the Web UI

1. Navigate to the objects that you want to archive.

2. Select the objects by clicking on the first object then:

   • Hold the Shift key and click another object to select everything between and including the two selected objects.

   • Hold the Ctrl key and click the other objects you want.

3. Click Archive Selected on the bottom of the page.

The objects will be moved to the archive database.

Archive Using the API

To archive an object with the API, the user sends a DELETE command to the specific object.

The example below shows a user archiving a Subscriber object called new_subscriber.

curl -X DELETE \
 -H "Authorization:Basic <secure-access-token>" \
 -d 'localhost/ecf/api/subscriber/service_test/new_subscriber'

Which would return a message such as:

"meta": {
        "encoding": "ascii",
        "records_shown": 0,
        "message": "Record successfully archived or restored.",
        "code": "205",
        "scope": "success"
},
"data": [],
"jsonapi": {
        "version": "2.2-17",
        "name": "Enhanced Call Forwarding",
        "short_name": "ecf",
        "author": "IMSWorkX, Inc."
}

Restoring¶

Restoring data will move data from the archive database to the live database. Restoring data can be done through the web UI or the API.

Restore a Single Object Using the Web UI

1. Switch to the archive view by toggling Live / Archive Database in the task bar.

2. Navigate to the object that you want to restore.

3. Right-click on the object to be restored.

4. Click Restore.

The object will be moved to the live database.

Restore Multiple Objects Using the Web UI

1. Switch to the archive view by toggling Live / Archive Database in the task bar.

2. Navigate to the objects that you want to restore.

3. Select the objects by clicking on the first object then:

   • Hold the Shift key and click another object to select everything between and including the two selected objects.

   • Hold the Ctrl key and click the other objects you want.

4. Click Restore Selected on the bottom of the page.

The objects will be moved to the live database.

Restore Using the API

To restore an object with the API, the user sends a DELETE command to the specific object.

The example below shows a user restoring a Subscriber object called new_subscriber.

curl -X DELETE \
         -H "Authorization:Basic <secure-access-token>" \
         -d 'localhost/ecf/api/subscriber/service_test/new_subscriber?archive=true&restore=true'

Which would return a message such as:

"meta": {
        "encoding": "ascii",
        "records_shown": 0,
        "message": "Record successfully archived or restored.",
        "code": "205",
        "scope": "success"
},
"data": [],
"jsonapi": {
        "version": "2.2-14",
        "name": "Enhanced Call Forwarding",
        "short_name": "ecf",
        "author": "IMSWorkX, Inc."
}

Purging¶

Purging data permanently removes the data from the archived database. Purging data can be done through the API, web UI, or the Maximum Inactive Days for Records setting in the web UI.

Purge a Single Object Using the Web UI

1. Switch to the archive view by toggling Live / Archive Database in the task bar.

2. Navigate to the object that you want to purge.

3. Right-click on the object to be purged.

4. Click Purge.

The object will be permanently removed from the database.

Purge Multiple Objects Using the Web UI

1. Switch to the archive view by toggling Live / Archive Database in the task bar.

2. Navigate to the objects that you want to purge.

3. Select the objects by clicking on the first object then:

   • Hold the Shift key and click another object to select everything between and including the two selected objects.

   • Hold the Ctrl key and click the other objects you want.

4. Click Purge Selected on the bottom of the page.

The objects will be permanently removed from the database.

Purge Using the Maximum Inactive Days Setting

ECF will remove records that have been archived longer than the value specified by this setting every night at midnight, which is determined by the time on the active NIU. A value of zero will always keep archived records in the database.

This setting can be found in the Settings page when the user is logged in as a Platform Owner.

Purge Using the API

To purge an object with the API, the user sends a DELETE command to the specific object.

The example below shows a user purging a Subscriber object called new_subscriber.

curl -X DELETE \
 -H "Authorization:Basic <secure-access-token>" \
 -d 'localhost/ecf/api/subscriber/service_test/new_subscriber?archive=true'

Which would return a message such as:

"meta": {
        "encoding": "ascii",
        "records_shown": 0,
        "message": "Record successfully archived or restored.",
        "code": "205",
        "scope": "success"
},
"data": [],
"jsonapi": {
        "version": "2.2-14",
        "name": "Enhanced Call Forwarding",
        "short_name": "ecf",
        "author": "IMSWorkX, Inc."
}