wiki:API/Tasks

Context Navigation

Tasks

Portax tasks REST API

DESCRIPTION

Tasks REST API is available at $Portax::WebPath/rest/tasks

Workorder REST resource provides single POST method to insert workorders. It accepts JSON as input data format.

API allows for multiple workorders to be sent within one request encoded as array of objects.

METHODS

POST

Insert new workorder. Expects UTF-8 JSON encoded data in the POST body.

FIELDS

Available workorder attributes. Required attributes are underlined.

wo_id: CRM workorder ID (integer)

pn: Subscriber's personal number (eg. account number)

unit_id: Subscriber's unit identifier

address_key: UIR or RUIAN address key ID

former_pn: Subscriber's previous PN, required for transfers

former_unit_id: Subscriber's previous unit identifier, required for transfers

profile_id: Service identifier

first_name: Subscriber's first name

last_name: Subscriber's last_name

organization: Subscriber's organization name

At least one of first_name, last_name or organization must be present.

house: Subscriber's house number

apartment: Subscriber's apartment ID

street: Subscriber's street address

city: Subscriber's city name

zip: Subscriber's ZIP code

phone: Subscriber's contact phone number

email: Subscriber's contact email

username: Selfcare username

password: Selfcare password

inet_service: Current Internet service.

One of disconnect, terminate, warn, debt, redirect or regular data service as per CRM system specification. ~~It can also carry additional service packages. Packages must be delimited by ; and +.~~

other_services: Additional service packages array

mac: Endpoint MAC address

iptv_service: Current IPTV service as a base service and packages delimited by ; and a + sign. Eg. DRT1;DB90+DB91. Special services as per inet_service

voip_service_1: Current voice service line 1. disconnect and terminate available

voip_service_2: Current voice service line 2. disconnect and terminate available

voip_no_1: First voice service number

voip_no_2: Second voice service number

voip_type: sip or null

sip_user_1: First voice service username

sip_user_2: Second voice service username

sip_pass_1: First voice service password

sip_pass_2: Second voice service password

aux_options

Special options JSON object, eg.

  "aux_options": { "sip_proxy": "a.b.c.d" }

tags: Optional tags array, eg. "tags": [ "tag1", "tag2" ]

lat: Latitude
lng: Longitude

Optional arguments

sid: Subscriber's internal Portax ID (e.g. for updating pn and/or unit_id)

Service packages:

VLAN(\d+)
L2VPN, eg. DRT1;VLAN100 indicates base service DRT1 and package VLAN100 which translates to DOCSIS L2VPN VLAN 100.
DS(\d+)
Download speed, eg. DRT1;DS50 indicates base service DRT1 and package DS50 which translates to download speed of 50mbps.
US(\d+)
Upload speed, eg. DRT1;US25 indicates base service DRT1 and package US25 which translates to upload speed of 25mbps.

Packages are allowed to combine, ie. DRT1;VLAN100+DS50+US25 is accepted. For usage see here.

Special options

redirect_url

URL to redirect when redirect inet_service is set, eg.:

  "inet_service": "redirect",
  "aux_options": { "redirect_url":"https://provider.com" }

warn

Warning reminder attributes, eg:

  "inet_service": "warn",
  "aux_options": {
    "warn":
      {
        "expiry": 1593681626,
        "pause": 30,
        "interval": 86400
        "repeat": 10
        "invoice": { "qr": "SPD*1.0*ACC:...", "account": "1234567890", "amount": 199, "reference": "123456", "currency": "CZK" }
      }
  }

expiry: unix time of expiration
pause: delay before ack allowed
interval: interwal between reminders
repeat: reminder display count
invoice: payment details

Portal template example:

<h4 class="card-title">Vážený zákazníku,</h1>

<p>dovolujeme si Vás upozornit, že jsme dosud neobdrželi úhradu za poskytnuté služby</p>

<p>Bankovní účty pro úhradu nedoplatku: [$account]</p>
<p>Částka: [$amount]</p>
<p>VS: [$reference]</p>

<div class="clearfix kjua">
  <fieldset><legend>QR platba</legend><div class="qr">[$qr]</div></fieldset>
</div>

Save as portal/manifest/warn/cs.

EXAMPLES

Connecting a service

All services use a so called late binding (or post-provisioning) process which means that binding a specific CPE (cable modem in this case) is done at customer's premises by the installer. Provisioning process starts by posting a new workorder:

{
  "wo_id": 56916,
  "pn": "01002",
  "first_name": "Libor",
  "last_name": "Toms",
  "organization": "RIO Media a.s.",
  "street": "Jiráskova",
  "house": "1391/111",
  "apartment": "",
  "city": "Moravská Třebová",
  "zip": "57101",
  "phone": "420844746746",
  "unit_id": "122559",
  "password": "teyagyu185",
  "inet_service": "DRT1",
  "other_services": [ "PKG1" ],
  "mac": "01:02:03:04:05:06",
  "voip_service_1": "aktiv",
  "voip_service_2": "",
  "iptv_service": "DRT1",
  "tags": [ "testing" ]
}

Changing a service

Each new workorder for subscriber 01002 changes the service for that particular subscriber, eg. to change from DRT1 data service class to the DRT2 one, issue following workorder:

{
  "wo_id": 56916,
  "pn": "01002",
  "first_name": "Libor",
  "last_name": "Toms",
  "organization": "RIO Media a.s.",
  "street": "Jiráskova",
  "house": "1391/111",
  "apartment": "",
  "city": "Moravská Třebová",
  "zip": "57101",
  "phone": "420844746746",
  "unit_id": "122559",
  "password": "teyagyu185",
  "inet_service": "DRT2",
  "other_services": [ "PKG2" ],
  "voip_service_1": "aktiv",
  "voip_service_2": "",
  "iptv_service": "DRT1",
}

Disconnecting or terminating a service

Several special service classes disconnect and terminate are used to temporarily disconnect or terminate the subscriber from the service respectively.

Other available special services are warn to notify subscriber of late payments and debt to disconnect subscriber from service with notification.

{
  "wo_id": 56916,
  "pn": "01002",
  "first_name": "Libor",
  "last_name": "Toms",
  "organization": "RIO Media a.s.",
  "street": "Jiráskova",
  "house": "1391/111",
  "apartment": "",
  "city": "Moravská Třebová",
  "zip": "57101",
  "phone": "420844746746",
  "unit_id": "122559",
  "password": "teyagyu185",
  "inet_service": "terminate",
  "voip_service_1": "terminate",
  "iptv_service": "terminate",
}

Redirect web traffic

redirect is a special service to redirect subscriber's web traffic to required URL.

{
  "wo_id": 56916,
  "pn": "01002",
  "first_name": "Libor",
  "last_name": "Toms",
  "organization": "RIO Media a.s.",
  "street": "Jiráskova",
  "house": "1391/111",
  "apartment": "",
  "city": "Moravská Třebová",
  "zip": "57101",
  "phone": "420844746746",
  "unit_id": "122559",
  "password": "teyagyu185",
  "inet_service": "redirect",
  "voip_service_1": "aktiv",
  "voip_service_2": "",
  "iptv_service": "DRT1",
  "aux_options": { "redirect_url":"https://nastenka.nej.cz/abuse" }
}

Use warn or debt to redirect web traffic to predefined warning pages.

Cancel workorder

Cancel workorder wo_id if not finished. wo_id is found in task response as externalId.

Use REST DELETE method to cancel task (only unfinished tasks can be cancelled):

curl -s --cert-type P12 --cert $CERT:$PASS -X DELETE \
  $URL/rest/tasks/56916

EXAMPLE

data.json

{
  "wo_id": 1,
  "password": "tomiyu233",
  "voip_no_2": null,
  "iptv_service": "disconnect",
  "unit_id": "127",
  "sip_pass_2": null,
  "street": "Ben Rapid",
  "profile_id": null,
  "pn": "26",
  "sip_user_2": null,
  "house": "0472",
  "zip": "49460",
  "voip_no_1": null,
  "apartment": null,
  "email": null,
  "city": "Klockoton",
  "mta_ip": null,
  "inet_service": "TST",
  "address_key": null,
  "username": "Murl",
  "sip_user_1": null,
  "phone": null,
  "organization": null,
  "alt_pn": null,
  "id": 9,
  "voip_service_2": "disconnect",
  "voip_service_1": "disconnect",
  "voip_type": null,
  "fixed_ip_cnt": null,
  "sip_pass_1": null,
  "aux_ip_cnt": null,
  "first_name": "German",
  "last_name": "Schneider"
}

curl -s --cert-type P12 --cert $CERT:$PASS -X POST \
  --data @data.json $URL/rest/tasks

GET

Get task status. ie:

curl -s --cert-type P12 --cert $CERT:$PASS \
  $URL/rest/tasks/1

Response:

{
  "status": "completed",
  "responseCode": 200
}

Last modified 4 months ago Last modified on Jan 3, 2024, 11:16:57 AM

Note: See TracWiki for help on using the wiki.

Download in other formats:

Plain Text