= 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: #ServicePackages
    * {{{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 [[DOCSISTemplating#Packagevariables|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
}
}}}